Unverified Commit 9800eaf4 authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

[Docs] Clarify a few things about the `instrumentation.ts` file (#51034)

There was some confusion about where to place it.
parent 41675c07
...@@ -13,6 +13,7 @@ This page provides an overview of the file and folder structure of a Next.js pro ...@@ -13,6 +13,7 @@ This page provides an overview of the file and folder structure of a Next.js pro
| **Next.js** | | | **Next.js** | |
| [`next.config.js`](/docs/app/api-reference/next-config-js) | Configuration file for Next.js | | [`next.config.js`](/docs/app/api-reference/next-config-js) | Configuration file for Next.js |
| [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware | | [`middleware.ts`](/docs/app/building-your-application/routing/middleware) | Next.js request middleware |
| [`instrumentation.ts`](/docs/app/building-your-application/optimizing/instrumentation) | OpenTelemetry and Instrumentation |
| [`.env`](/docs/app/building-your-application/configuring/environment-variables) | Environment variables | | [`.env`](/docs/app/building-your-application/configuring/environment-variables) | Environment variables |
| [`.env.local`](/docs/app/building-your-application/configuring/environment-variables) | Local environment variables | | [`.env.local`](/docs/app/building-your-application/configuring/environment-variables) | Local environment variables |
| [`.env.production`](/docs/app/building-your-application/configuring/environment-variables) | Production environment variables | | [`.env.production`](/docs/app/building-your-application/configuring/environment-variables) | Production environment variables |
......
...@@ -3,7 +3,7 @@ title: OpenTelemetry ...@@ -3,7 +3,7 @@ title: OpenTelemetry
description: Learn how to instrument your Next.js app with OpenTelemetry. description: Learn how to instrument your Next.js app with OpenTelemetry.
--- ---
> **Note**: This feature is experimental, you need to explicitly opt-in by providing `experimental.instrumentationHook = true;` in your `next.config.js`. > **Note**: This feature is **experimental**, you need to explicitly opt-in by providing `experimental.instrumentationHook = true;` in your `next.config.js`.
Observability is crucial for understanding and optimizing the behavior and performance of your Next.js app. Observability is crucial for understanding and optimizing the behavior and performance of your Next.js app.
...@@ -35,9 +35,9 @@ To get started, you must install `@vercel/otel`: ...@@ -35,9 +35,9 @@ To get started, you must install `@vercel/otel`:
npm install @vercel/otel npm install @vercel/otel
``` ```
Next, create a custom [`instrumentation.ts`](/docs/pages/building-your-application/optimizing/instrumentation) file in the root of the project: Next, create a custom [`instrumentation.ts`](/docs/pages/building-your-application/optimizing/instrumentation) (or `.js`) file in the **root directory** of the project:
```ts filename="instrumentation.ts" switcher ```ts filename="your-project/instrumentation.ts" switcher
import { registerOTel } from '@vercel/otel' import { registerOTel } from '@vercel/otel'
export function register() { export function register() {
...@@ -45,7 +45,7 @@ export function register() { ...@@ -45,7 +45,7 @@ export function register() {
} }
``` ```
```js filename="instrumentation.js" switcher ```js filename="your-project/instrumentation.js" switcher
import { registerOTel } from '@vercel/otel' import { registerOTel } from '@vercel/otel'
export function register() { export function register() {
...@@ -53,7 +53,11 @@ export function register() { ...@@ -53,7 +53,11 @@ export function register() {
} }
``` ```
> **Note**: We have created a basic [with-opentelemetry](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) example that you can use. > **Good to know**
>
> - The `instrumentation` file should be in the root of your project and not the `app` or `pages` directory.
> - If you use the [`pagesExtension` 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.
### Manual OpenTelemetry configuration ### Manual OpenTelemetry configuration
......
...@@ -3,16 +3,23 @@ title: Instrumentation ...@@ -3,16 +3,23 @@ title: Instrumentation
description: Learn how to use instrumentation to run code at server startup in your Next.js app description: Learn how to use instrumentation to run code at server startup in your Next.js app
--- ---
> **Note**: This feature is experimental. To use it, you must explicitly opt in by defining `experimental.instrumentationHook = true;` in your `next.config.js`. > **Note**: This feature is **experimental**. To use it, you must explicitly opt in by defining `experimental.instrumentationHook = true;` in your `next.config.js`.
If you export a function named `register` from a `instrumentation.ts` (or `.js`) file in the **root directory** of your project, we will call that function whenever a new Next.js server instance is bootstrapped.
> **Good to know**
>
> - The `instrumentation` file should be in the root of your project and not the `app` or `pages` directory.
> - If you use the [`pagesExtension` 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 export a function named `register` from this file, we will call that function whenever a new Next.js server instance is bootstrapped.
When your `register` function is deployed, it will be called on each cold boot (but exactly once in each environment). When your `register` function is deployed, it will be called on each cold boot (but exactly once in each environment).
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. 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 as demonstrated in the following example:
```ts filename="/instrumentation.ts" switcher ```ts filename="your-project/instrumentation.ts" switcher
import { init } from 'package-init' import { init } from 'package-init'
export function register() { export function register() {
...@@ -20,7 +27,7 @@ export function register() { ...@@ -20,7 +27,7 @@ export function register() {
} }
``` ```
```js filename="/instrumentation.js" switcher ```js filename="your-project/instrumentation.js" switcher
import { init } from 'package-init' import { init } from 'package-init'
export function register() { export function register() {
...@@ -30,13 +37,13 @@ export function register() { ...@@ -30,13 +37,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: 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="/instrumentation.ts" switcher ```ts filename="your-project/instrumentation.ts" switcher
export async function register() { export async function register() {
await import('package-with-side-effect') await import('package-with-side-effect')
} }
``` ```
```js filename="/instrumentation.js" switcher ```js filename="your-project/instrumentation.js" switcher
export async function register() { export async function register() {
await import('package-with-side-effect') await import('package-with-side-effect')
} }
...@@ -46,7 +53,7 @@ By doing this, you can colocate all of your side effects in one place in your co ...@@ -46,7 +53,7 @@ By doing this, you can colocate all of your side effects in one place in your co
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: 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:
```ts filename="/instrumentation.ts" switcher ```ts filename="your-project/instrumentation.ts" switcher
export async function register() { export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') { if (process.env.NEXT_RUNTIME === 'nodejs') {
await import('./instrumentation-node') await import('./instrumentation-node')
...@@ -58,7 +65,7 @@ export async function register() { ...@@ -58,7 +65,7 @@ export async function register() {
} }
``` ```
```js filename="/instrumentation.js" switcher ```js filename="your-project/instrumentation.js" switcher
export async function register() { export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') { if (process.env.NEXT_RUNTIME === 'nodejs') {
await import('./instrumentation-node') await import('./instrumentation-node')
......
...@@ -117,12 +117,13 @@ module.exports = { ...@@ -117,12 +117,13 @@ module.exports = {
Changing these values affects _all_ Next.js pages, including the following: Changing these values affects _all_ Next.js pages, including the following:
- `middleware.js` - [`middleware.js`](/docs/pages/building-your-application/routing/middleware)
- [`instrumentation.js`](/docs/pages/building-your-application/optimizing/instrumentation)
- `pages/_document.js` - `pages/_document.js`
- `pages/_app.js` - `pages/_app.js`
- `pages/api/` - `pages/api/`
For example, if you reconfigure `.ts` page extensions to `.page.ts`, you would need to rename pages like `_app.page.ts`. For example, if you reconfigure `.ts` page extensions to `.page.ts`, you would need to rename pages like `middleware.page.ts`, `instrumentation.page.ts`, `_app.page.ts`.
## Including non-page files in the `pages` directory ## Including non-page files in the `pages` directory
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment