From c326f832a189ea833320ebe0eed8bda42f2fd1f8 Mon Sep 17 00:00:00 2001 From: Delba de Oliveira Date: Mon, 29 Jan 2024 15:06:19 +0000 Subject: [PATCH 1/3] Add the `instrumentationHook` next config option --- .../05-next-config-js/instrumentationHook.mdx | 17 +++++++++++++++++ .../03-next-config-js/instrumentationHook.mdx | 7 +++++++ 2 files changed, 24 insertions(+) create mode 100644 docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx create mode 100644 docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx diff --git a/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx b/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx new file mode 100644 index 0000000000000..2fc16bc01a1f3 --- /dev/null +++ b/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx @@ -0,0 +1,17 @@ +--- +title: instrumentationHook +description: Use the instrumentationHook option to set up instrumentation in your Next.js App. +--- + +{/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} + +The `instrumentationHook` option allows you to set up instrumentation in your Next.js App. To be used with the [`instrumentation` file](/docs/app/api-reference/file-conventions/instrumentation) and [`register` function](/docs/app/api-reference/file-conventions/instrumentation#register). + +```js filename="next.config.js" +module.exports = { + experimental: { + instrumentationHook: true + }, +} +``` + diff --git a/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx b/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx new file mode 100644 index 0000000000000..5d61da83d8794 --- /dev/null +++ b/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx @@ -0,0 +1,7 @@ +--- +title: instrumentationHook +description: Use the instrumentationHook option to set up instrumentation in your Next.js App. +source: app/api-reference/next-config-js/instrumentationHook +--- + +{/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} From 36ee3a18000c074d6ea53595620ae741f1249026 Mon Sep 17 00:00:00 2001 From: Delba de Oliveira Date: Tue, 30 Jan 2024 19:00:45 +0000 Subject: [PATCH 2/3] wip --- .../06-optimizing/09-instrumentation.mdx | 63 ++++++++++++------- .../02-file-conventions/instrumentation.mdx | 53 ++++++++++++++++ .../05-next-config-js/instrumentationHook.mdx | 7 +-- .../03-next-config-js/instrumentationHook.mdx | 2 +- 4 files changed, 97 insertions(+), 28 deletions(-) create mode 100644 docs/02-app/02-api-reference/02-file-conventions/instrumentation.mdx diff --git a/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx b/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx index 9fbf79e1f2030..1bcc486613715 100644 --- a/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx +++ b/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx @@ -1,43 +1,58 @@ --- title: Instrumentation description: Learn how to use instrumentation to run code at server startup in your Next.js app +related: + title: Learn more about Instrumentation + links: + - app/api-reference/file-conventions/instrumentation + - app/api-reference/next.config.js/instrumentationHook --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} Instrumentation is the process of using code to integrate monitoring and logging tools into your application. This allows you to track the performance and behavior of your application, and to debug issues in production. -Next.js provides a `register` function that can be exported from a `instrumentation.ts|js` file in the **root directory** of your project (or inside the `src` folder if using one). Next.js will then call `register` whenever a new Next.js server instance is bootstrapped. +## Convention - +To set up instrumentation, create `instrumentation.ts|js` file in the **root directory** of your project (or inside the `src` folder if using one). -> **Good to know** -> -> - This feature is **experimental**. To use it, you must explicitly opt in by defining `experimental.instrumentationHook = true;` in your `next.config.js`. -> - The `instrumentation` file should be in the root of your project and not inside the `app` or `pages` directory. If you're using the `src` folder, then place the file inside `src` alongside `pages` and `app`. -> - If you use the [`pageExtensions` config option](/docs/app/api-reference/next-config-js/pageExtensions) to add a suffix, you will also need to update the `instrumentation` filename to match. -> - We have created a basic [with-opentelemetry](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) example that you can use. +Then, export a `register` function from the file. This function will be called **once** when a new Next.js server instance is initiated. + +For example, to use Next.js with [OpenTelemetry](https://opentelemetry.io/) and [@vercel/otel](https://github.com/vercel/otel): + +```ts filename="instrumentation.ts" switcher +import { registerOTel } from '@vercel/otel' + +export function register() { + registerOTel('next-app') +} +``` - +```js filename="instrumentation.js" switcher +import { registerOTel } from '@vercel/otel' + +export function register() { + registerOTel('next-app') +} +``` - +See the [Next.js with Open Telemetry example](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) for a complete implementation. > **Good to know** > -> - This feature is **experimental**. To use it, you must explicitly opt in by defining `experimental.instrumentationHook = true;` in your `next.config.js`. +> - This feature is **experimental**. To use it, you must explicitly opt in by defining [`experimental.instrumentationHook = true;`](/docs/app/api-reference/next-config-js/instrumentationHook) in your `next.config.js`. > - The `instrumentation` file should be in the root of your project and not inside the `app` or `pages` directory. If you're using the `src` folder, then place the file inside `src` alongside `pages` and `app`. -> - If you use the [`pageExtensions` config option](/docs/pages/api-reference/next-config-js/pageExtensions) to add a suffix, you will also need to update the `instrumentation` filename to match. -> - We have created a basic [with-opentelemetry](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) example that you can use. +> - If you use the [`pageExtensions` config option](/docs/app/api-reference/next-config-js/pageExtensions) to add a suffix, you will also need to update the `instrumentation` filename to match. - +## Examples -When your `register` function is deployed, it will be called on each cold boot (but exactly once in each environment). +### Importing files with side effects Sometimes, it may be useful to import a file in your code because of the side effects it will cause. For example, you might import a file that defines a set of global variables, but never explicitly use the imported file in your code. You would still have access to the global variables the package has declared. -You can import files with side effects in `instrumentation.ts`, which you might want to use in your `register` function as demonstrated in the following example: +You can import files with side effects in `instrumentation.ts`, which you might want to use in your `register` function: -```ts filename="your-project/instrumentation.ts" switcher +```ts filename="instrumentation.ts" switcher import { init } from 'package-init' export function register() { @@ -45,7 +60,7 @@ export function register() { } ``` -```js filename="your-project/instrumentation.js" switcher +```js filename="instrumentation.js" switcher import { init } from 'package-init' export function register() { @@ -55,13 +70,13 @@ export function register() { However, we recommend importing files with side effects using `import` from within your `register` function instead. The following example demonstrates a basic usage of `import` in a `register` function: -```ts filename="your-project/instrumentation.ts" switcher +```ts filename="instrumentation.ts" switcher export async function register() { await import('package-with-side-effect') } ``` -```js filename="your-project/instrumentation.js" switcher +```js filename="instrumentation.js" switcher export async function register() { await import('package-with-side-effect') } @@ -69,9 +84,11 @@ export async function register() { By doing this, you can colocate all of your side effects in one place in your code, and avoid any unintended consequences from importing files. -We call `register` in all environments, so it's necessary to conditionally import any code that doesn't support both `edge` and `nodejs`. You can use the environment variable `NEXT_RUNTIME` to get the current environment. Importing an environment-specific code would look like this: +### Importing runtime-specific code + +Next.js calls `register` in all environments, so it's important to conditionally import any code that doesn't support either [Edge](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#edge-runtime) or [Node.js](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#nodejs-runtime). You can the `NEXT_RUNTIME` environment variable to get the current environment. Importing runtime-specific code would look like this: -```ts filename="your-project/instrumentation.ts" switcher +```ts filename="instrumentation.ts" switcher export async function register() { if (process.env.NEXT_RUNTIME === 'nodejs') { await import('./instrumentation-node') @@ -83,7 +100,7 @@ export async function register() { } ``` -```js filename="your-project/instrumentation.js" switcher +```js filename="instrumentation.js" switcher export async function register() { if (process.env.NEXT_RUNTIME === 'nodejs') { await import('./instrumentation-node') diff --git a/docs/02-app/02-api-reference/02-file-conventions/instrumentation.mdx b/docs/02-app/02-api-reference/02-file-conventions/instrumentation.mdx new file mode 100644 index 0000000000000..6f4eb854e4b03 --- /dev/null +++ b/docs/02-app/02-api-reference/02-file-conventions/instrumentation.mdx @@ -0,0 +1,53 @@ +--- +title: instrumentation.js +description: API reference for the instrumentation.js file. +related: + title: Learn more about Instrumentation + links: + - app/building-your-application/optimizing/instrumentation +--- + +The `instrumentation.js|ts` file is used to integrate monitoring and logging tools into your application. This allows you to track the performance and behavior of your application, and to debug issues in production. + +To use it, place the file in the **root** of your application or inside a [`src` folder](/docs/app/building-your-application/configuring/src-directory) if using one. + +## Config Option + +Instrumentation is currently an experimental feature, to use the `instrumentation` file, you must explicitly opt-in by defining [`experimental.instrumentationHook = true;`](/docs/app/api-reference/next-config-js/instrumentationHook) in your `next.config.js`: + +```js filename="next.config.js" +module.exports = { + experimental: { + instrumentationHook: true, + }, +} +``` + +## Exports + +### `register` (required) + +The file exports a `register` function that is called **once** when a new Next.js server instance is initiated. `register` can be an async function. + +```ts filename="instrumentation.ts" switcher +import { registerOTel } from '@vercel/otel' + +export function register() { + registerOTel('next-app') +} +``` + +```js filename="instrumentation.js" switcher +import { registerOTel } from '@vercel/otel' + +export function register() { + registerOTel('next-app') +} +``` + +## Version History + +| Version | Changes | +| --------- | ------------------------------------------------------- | +| `v14.0.4` | Turbopack support for `instrumentation` | +| `v13.2.0` | `instrumentation` introduced as an experimental feature | diff --git a/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx b/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx index 2fc16bc01a1f3..2b3dae1a3f4ab 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx @@ -1,17 +1,16 @@ --- title: instrumentationHook -description: Use the instrumentationHook option to set up instrumentation in your Next.js App. +description: Use the instrumentationHook option to set up instrumentation in your Next.js App. --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} -The `instrumentationHook` option allows you to set up instrumentation in your Next.js App. To be used with the [`instrumentation` file](/docs/app/api-reference/file-conventions/instrumentation) and [`register` function](/docs/app/api-reference/file-conventions/instrumentation#register). +The `instrumentationHook` option allows you to set up instrumentation in your Next.js App. To be used with the [`instrumentation` file](/docs/app/api-reference/file-conventions/instrumentation) and [`register` function](/docs/app/api-reference/file-conventions/instrumentation#register-required). ```js filename="next.config.js" module.exports = { experimental: { - instrumentationHook: true + instrumentationHook: true, }, } ``` - diff --git a/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx b/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx index 5d61da83d8794..784b768d37634 100644 --- a/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx +++ b/docs/03-pages/02-api-reference/03-next-config-js/instrumentationHook.mdx @@ -1,6 +1,6 @@ --- title: instrumentationHook -description: Use the instrumentationHook option to set up instrumentation in your Next.js App. +description: Use the instrumentationHook option to set up instrumentation in your Next.js App. source: app/api-reference/next-config-js/instrumentationHook --- From 3c1efe0cf74d530bf80f3de49f6541b446465c25 Mon Sep 17 00:00:00 2001 From: Delba de Oliveira Date: Wed, 31 Jan 2024 13:32:01 +0000 Subject: [PATCH 3/3] polish --- .../06-optimizing/09-instrumentation.mdx | 34 +++++-------------- .../05-next-config-js/instrumentationHook.mdx | 7 +++- 2 files changed, 15 insertions(+), 26 deletions(-) diff --git a/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx b/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx index 1bcc486613715..693b6b7e09bdc 100644 --- a/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx +++ b/docs/02-app/01-building-your-application/06-optimizing/09-instrumentation.mdx @@ -5,7 +5,7 @@ related: title: Learn more about Instrumentation links: - app/api-reference/file-conventions/instrumentation - - app/api-reference/next.config.js/instrumentationHook + - app/api-reference/next-config-js/instrumentationHook --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} @@ -14,9 +14,9 @@ Instrumentation is the process of using code to integrate monitoring and logging ## Convention -To set up instrumentation, create `instrumentation.ts|js` file in the **root directory** of your project (or inside the `src` folder if using one). +To set up instrumentation, create `instrumentation.ts|js` file in the **root directory** of your project (or inside the [`src`](/docs/app/building-your-application/configuring/src-directory) folder if using one). -Then, export a `register` function from the file. This function will be called **once** when a new Next.js server instance is initiated. +Then, export a `register` function in the file. This function will be called **once** when a new Next.js server instance is initiated. For example, to use Next.js with [OpenTelemetry](https://opentelemetry.io/) and [@vercel/otel](https://github.com/vercel/otel): @@ -36,7 +36,7 @@ export function register() { } ``` -See the [Next.js with Open Telemetry example](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) for a complete implementation. +See the [Next.js with OpenTelemetry example](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) for a complete implementation. > **Good to know** > @@ -50,25 +50,7 @@ See the [Next.js with Open Telemetry example](https://github.com/vercel/next.js/ Sometimes, it may be useful to import a file in your code because of the side effects it will cause. For example, you might import a file that defines a set of global variables, but never explicitly use the imported file in your code. You would still have access to the global variables the package has declared. -You can import files with side effects in `instrumentation.ts`, which you might want to use in your `register` function: - -```ts filename="instrumentation.ts" switcher -import { init } from 'package-init' - -export function register() { - init() -} -``` - -```js filename="instrumentation.js" switcher -import { init } from 'package-init' - -export function register() { - init() -} -``` - -However, we recommend importing files with side effects using `import` from within your `register` function instead. The following example demonstrates a basic usage of `import` in a `register` function: +We recommend importing files using JavaScript `import` syntax within your `register` function. The following example demonstrates a basic usage of `import` in a `register` function: ```ts filename="instrumentation.ts" switcher export async function register() { @@ -82,11 +64,13 @@ export async function register() { } ``` -By doing this, you can colocate all of your side effects in one place in your code, and avoid any unintended consequences from importing files. +> **Good to know:** +> +> We recommend importing the file from within the `register` function, rather than at the top of the file. By doing this, you can colocate all of your side effects in one place in your code, and avoid any unintended consequences from importing globally at the top of the file. ### Importing runtime-specific code -Next.js calls `register` in all environments, so it's important to conditionally import any code that doesn't support either [Edge](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#edge-runtime) or [Node.js](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#nodejs-runtime). You can the `NEXT_RUNTIME` environment variable to get the current environment. Importing runtime-specific code would look like this: +Next.js calls `register` in all environments, so it's important to conditionally import any code that doesn't support specific runtimes (e.g. [Edge](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#edge-runtime) or [Node.js](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#nodejs-runtime)). You can use the `NEXT_RUNTIME` environment variable to get the current environment: ```ts filename="instrumentation.ts" switcher export async function register() { diff --git a/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx b/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx index 2b3dae1a3f4ab..ff183d402b739 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/instrumentationHook.mdx @@ -1,11 +1,16 @@ --- title: instrumentationHook description: Use the instrumentationHook option to set up instrumentation in your Next.js App. +related: + title: Learn more about Instrumentation + links: + - app/api-reference/file-conventions/instrumentation + - app/building-your-application/optimizing/instrumentation --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} -The `instrumentationHook` option allows you to set up instrumentation in your Next.js App. To be used with the [`instrumentation` file](/docs/app/api-reference/file-conventions/instrumentation) and [`register` function](/docs/app/api-reference/file-conventions/instrumentation#register-required). +The experimental `instrumentationHook` option allows you to set up instrumentation via the [`instrumentation` file](/docs/app/api-reference/file-conventions/instrumentation) in your Next.js App. ```js filename="next.config.js" module.exports = {