docs(instruments): Add documentation for new Instruments API

Author: EmrysMyrddin

packages/web/docs/src/content/gateway/other-features/custom-plugins.mdx

@@ -826,6 +826,123 @@ Prefer `onRequestParse` when possible, or wrap the hook code in a `try` block.
 | `serverContext` | The final context object that is shared between all hooks and the GraphQL execution. [Learn more about the context](https://the-guild.dev/graphql/yoga-server/docs/features/context#server-context). |
 | `response`      | The outgoing HTTP response as WHATWG `Response` object. [Learn more about the response interface](https://developer.mozilla.org/en-US/docs/Web/API/Response).                                        |
 
+### `instruments`
+
+An optional `instruments` instance can be present in the plugin.
+
+This `Instruments` instance allows to wrap an entire phase execution (including all plugin hooks),
+meaning running code just before, just after and around the execution of the phase.
+
+Instruments doesn't have access to input/output of a phase, use hooks to have access to those data.
+If needed, we recommend to share data between instruments and hooks with a `WeakMap` and the given
+`context` as the key.
+
+All instruments takes 2 parameters:
+
+- `payload`: an object containing the graphql context or the http request depending on the
+  instrument.
+- `wrapped`: The function representing the execution of the phase. It takes no parameters, and
+  returns `void` (or `Promise<void>` for asynchrone phases). **This function must always be
+  called**. If this function returns a `Promise`, the instrument should return a `Promise` resolving
+  after it.
+
+#### Instruments composition
+
+If multiple plugins have `instruments`, they are composed in the same order they are defined the
+plugin array (the first is outtermost call, the last is inner most call).
+
+It is possible to customize this composition if it doesn't suite your need (ie. you need hooks and
+instruments to have a different oreder of execution).
+
+```ts
+import { composeInstruments, envelop } from '@envelop/core'
+
+const { instruments: instruments1, ...plugin1 } = usePlugin1()
+const { instruments: instruments2, ...plugin2 } = usePlugin2()
+
+const instruments = composeInstruments([instruments2, instruments1])
+
+const getEnveloped = envelop({
+  plugin: [{ insturments }, plugin1, plugin2]
+})
+```
+
+#### `request`
+
+Wraps the HTTP request handling. This includes all the plugins `onRequest` and `onResponse` hooks.
+
+This instrument can be asynchronous, the wrapped funcion **can be** asynchronous. Be sure to return
+a `Promise` if `wrapped()` returned a `Promise`.
+
+#### `requestParse`
+
+Wraps the parsing of the request phase to extract grapqhl params. This include all the plugins
+`onRequestParse` hooks.
+
+This insturment can be asynchronous, the wrapped function **can be** asynchrounous. Be sure to
+return a `Promise` if `wrapped()` returns a `Promise`.
+
+#### `operation`
+
+Wraps the Graphql operation execution pipeline. This is called for each graphql operation, meaning
+it can be called mutliple time for the same HTTP request if batching is enabled.
+
+This instrument can be asynchronous, the wrapped function **can be** asynchronous. Be sur to return
+a `Promise` if `wrapped()` returnd a `Promise`.
+
+#### `init`
+
+Wraps the envelop (the call to `envelop` function) initialisation.
+
+This includes all the plugins `onEnveloped` hooks, and the creation of the Envelop Orchestrator.
+
+This instruments must be synchrone, the wrapped function is always synchrone.
+
+#### `parse`
+
+Wraps the parse phase. This includes all the plugins `onParse` hooks and the actual engine `parse`.
+
+This instrument must be synchrone, the wrapped function is always synchrone.
+
+#### `validate`
+
+Wraps the validate phase. This includes all the plugins `onValidate` hooks and the actual engine
+`validate`.
+
+This instrument must be synchrone, the wrapped function is always synchrone.
+
+#### `context`
+
+Wraps the context building phase. This includes all the plugins `onContextBuilding` hooks.
+
+This instrument must be synchrone, the wrapped function is always synchrone.
+
+#### `execute`
+
+Wraps the execute phase. This includes all the plugins `onExecute` hooks.
+
+This instrument can be asynchrone, the wrapped function **can be** asynchrone. Be sure to `await` or
+use `.then` on the result of the `wrapped` function to run code after the `execute` phase.
+
+Note that `wrapped` is not guaranted to return a promise.
+
+#### `subscribe`
+
+Wraps the subscribe phase. This includes all the plugins `onSubsribe` hooks. Note that it doesn't
+wrap the entire lifetime of the subscription, but only it's intialisation.
+
+This instrument can be asynchrone, the wrapped function **can be** asynchrone. Be sure to `await` or
+use `.then` on the result of the `wrapped` function to run code after the `subsribe` phase.
+
+Note that `wrapped` is not guaranted to return a promise.
+
+#### `resultProcess`
+
+Wraps the context result processing phase. This includes all the plugins `onResultProcess` hooks.
+
+This instruments can be asynchrone, the wrapped function **can be** asynchronous. a `Promise` if
+`wrapped()` returns a `Promise`.
+
 ### Plugin Context
 
 Hive Gateway comes with ready-to-use `logger`, `fetch`, cache storage and etc that are shared across