Unverified Commit a3acbf4f authored by Jan Kaifer's avatar Jan Kaifer Committed by GitHub

Add documentation on OTEL support (#47194)

Added docs that mention:
- important code-snippets from example
- links to official OTEL docs
- document NEXT_VERBOSE_OTEL
- explain what we provide out of the box
- what we don’t
- explain how you can add tracing yourself
- explain how instrumentation.js works
- it can be used for different types of instrumentation that don't use
OTEL. It's just a hook called when starting up a new node environment.

- list of all spans we instrument by default
 
fix NEXT-799 ([link](https://linear.app/vercel/issue/NEXT-799))

---------
Co-authored-by: 's avatarS3Prototype <liuqahs15@gmail.com>
parent 43ff6cfd
---
description: Learn how to instrument 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`.
# `instrumentation.ts`
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).
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:
```ts
// /instrumentation.ts
import { init } from 'package-init'
export const register() {
init()
}
```
However, we recommend importing files with side effects using `require` from within your `register` function instead. The following example demonstrates a basic usage of `require` in a `register` function:
```ts
// /instrumentation.ts
export const register() {
require('package-with-side-effect')
}
```
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 require any code that doesn't support both `edge` and `nodejs`. You can use environment variable `NEXT_RUNTIME` to get the current environment. Importing environment specific code would look like this:
```ts
// /instrumentation.ts
export const register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
require('./instrumentation-node')
}
if (process.env.NEXT_RUNTIME === 'edge') {
require('./instrumentation-edge')
}
}
```
---
description: Learn how 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`.
# OpenTelemetry in Next.js
Observability is crucial for understanding and optimizing the behavior and performance of your Next.js app.
As applications become more complex, it becomes increasingly difficult to identify and diagnose issues that may arise. By leveraging observability tools, such as logging and metrics, developers can gain insights into their application's behavior and identify areas for optimization. With observability, developers can proactively address issues before they become major problems and provide a better user experience. Therefore, it is highly recommended to use observability in your Next.js applications to improve performance, optimize resources, and enhance user experience.
We recommend using OpenTelemetry for instrumenting your apps.
It's a platform agnostic way to instrument apps that allows you to change your observability provider without changing your code.
Read [Official OpenTelemetry docs](https://opentelemetry.io/docs/) for more information about OpenTelemetry and how it works.
This documentation uses terms like _Span_, _Trace_ or _Exporter_ throughout this doc, all of which can be found in [the OpenTelemetry Observability Primer](https://opentelemetry.io/docs/concepts/observability-primer/).
Next.js supports OpenTelemetry instrumentation out of the box, that means that we already instrumented Next.js itself.
When you enable OpenTelemetry you we will automatically wrap all your code like `getStaticProps` in a _spans_ with helpful attributes.
> **Note:** We currently support OpenTelemetry bindings only in serverless functions.
> We don't provide any for `edge` or client side code.
## Getting Started
To get started, you must install the required packages:
```bash
npm install @vercel/otel
```
Next, create a custom [`instrumentation.ts`](./instrumentation.md) file in the root of the project:
```ts
// instrumentation.ts
import { registerOTel } from '@vercel/otel'
export function register() {
registerOTel('next-app')
}
```
> **Note**: We have created a basic [with-opentelemetry](https://github.com/vercel/next.js/tree/canary/examples/with-opentelemetry) example that you can use.
## Testing your instrumentation
You need a OpenTelemetry collector with a compatible backend to test OpenTelemetry traces locally.
We recommend using our [OpenTelemetry dev environment](https://github.com/vercel/opentelemetry-collector-dev-setup).
If everything works well you should be able to see the root server span labeled as `GET /requested/pathname`.
All other spans from that particular trace will be nested under it.
Next.js traces more spans than are emitted by default.
To see more spans, you must set `NEXT_OTEL_VERBOSE=1`.
## Custom Spans
OpenTelemetry enables you to add your own custom spans to trace using official OpenTelemetry APIs.
Our package `@vercel/otel` exports everything from `@opentelemetry/api` so you don't need to install anything.
The following example demonstrates a function that fetches GitHub stars and adds a custom `fetchGithubStars` span to track the fetch request's result:
```ts
import { trace } from '@vercel/otel'
export async function fetchGithubStars() {
return await trace
.getTracer('nextjs-example')
.startActiveSpan('fetchGithubStars', async (span) => {
try {
return await getValue()
} finally {
span.end()
}
})
}
```
More documentation can be found in [OpenTelemetry docs](https://opentelemetry.io/docs/instrumentation/js/instrumentation/).
The `register` function will execute before your code runs in a new environment.
You can start creating new spans, and they should be correctly added to the exported trace.
## Custom register function
We have created `@vercel/otel` to make it easier to get started with OpenTelemetry. But this package won't be able to satisfy some advanced setups. You can always use OpenTelemetry APIs directly.
In order to be able to leverage instrumentation provided by next.js you will need to setup and register custom [TraceProvider](https://opentelemetry.io/docs/reference/specification/trace/api/#tracerprovider).
> **Note**: `instrumentation.ts` get's called in both `edge` and `nodejs` runtime. You need to make sure that you are initializing OpenTelemetry only in `nodejs` runtime. OpenTelemetry APIs are not available on `edge`.
## Default Spans in Next.js
Next.js automatically instruments several spans for you to provide useful insights into your application's performance.
All spans have these attributes:
- `next.span_name`: this is name the of the span
- `next.span_type`: this is unique identifier for particular span
Here's a list of default spans provided by Next.js:
### `[http.method] [next.route]`
This span represents the root span for each incoming request to your Next.js application. It tracks the HTTP method, route, target, and status code of the request.
Attributes:
- `http.method`: The HTTP method of the request (e.g., GET, POST).
- `http.route`: Same as `next.route`.
- `http.status_code`: The HTTP status code of the response.
- `http.target`: The actual requested path (e.g., `/value/user`).
- `next.route`: The route pattern of the request (e.g., `/[param]/user`).
- `next.span_type`: `BaseServer.handleRequest`
### `render route (app) [next.route]`
This span represents the process of rendering a route in the application.
Attributes:
- `next.route`: The route pattern of the request (e.g., `/[param]/user`).
- `next.span_type`: `AppRender.getBodyResult`.
### `fetch [http.method] [http.url]`
This span represents the fetch request executed in your code.
Attributes:
- `http.method`: The HTTP method of the fetch request (e.g., GET).
- `http.url`: The URL of the fetch request (e.g., `https://vercel.com/`).
- `net.peer.name`: The domain name of the fetch request (e.g., `vercel.com`).
- `next.span_type`: `AppRender.fetch`
### `executing api route (app) [next.route]`
This span represents the execution of an API route handler in the application.
Attributes:
- `next.route`: The route pattern of the request (e.g., `/[param]/getUser`).
- `next.span_type`: `AppRouteRouteHandlers.runHandler`.
### `getServerSideProps [next.route]`
This span represents the execution of `getServerSideProps` for a specific route.
Attributes:
- `next.route`: The route pattern of the request (e.g., `/[param]/user`).
- `next.span_type`: `Render.getServerSideProps`.
### `getStaticProps [next.route]`
This span represents the execution of `getStaticProps` for a specific route.
Attributes:
- `next.route`: The route pattern of the request (e.g., `/[param]/user`).
- `next.span_type`: `Render.getStaticProps`.
### `render route (pages) [next.route]`
This span represents the process of rendering the document for a specific route.
Attributes:
- `next.route`: The route pattern of the request (e.g., `/[param]/user`).
- `next.span_type`: `Render.renderDocument`.
### `generateMetadata [next.page]`
This span represents the process of generating metadata for a specific route.
Attributes:
- `next.page`: The page pattern for which the metadata is generated (e.g., `/app/[param]/layout` or `/app/[param]/page`).
- `next.span_type`: `ResolveMetadata.generateMetadata`.
......@@ -320,6 +320,14 @@
"title": "Output File Tracing",
"path": "/docs/advanced-features/output-file-tracing.md"
},
{
"title": "Instrumentation",
"path": "/docs/advanced-features/instrumentation.md"
},
{
"title": "Open Telemetry",
"path": "/docs/advanced-features/open-telemetry.md"
},
{
"title": "Security Headers",
"path": "/docs/advanced-features/security-headers.md"
......
......@@ -9,6 +9,8 @@ You can easily deploy this example on Vercel. It manages OpenTelemetry collector
But you need to run your own collector if you want to test OpenTelemetry locally. We recommend cloning pre-made [dev setup](https://github.com/vercel/opentelemetry-collector-dev-setup). It contains pre-configured docker images for Collector, ZipKin, Jaeger and Prometheus.
More information about OpenTelemetry can be found in [Next.js docs](https://nextjs.org/docs/advanced-features/open-telemetry).
## Deploy your own
Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example) or preview live with [StackBlitz](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/data-fetch)
......
import { Resource } from '@opentelemetry/resources'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import {
NodeTracerProvider,
SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-node'
// You can use gRPC exporter instead
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
// Next.js expects you to use to register TraceProvider. It won't work if you use NodeSDK.
// We use registered provider to create traces inside of Next.js internals.
const provider = new NodeTracerProvider({
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: 'next-app',
}),
})
provider.addSpanProcessor(new SimpleSpanProcessor(new OTLPTraceExporter({})))
// Make sure to register you provider
provider.register()
import { registerOTel } from '@vercel/otel'
export function register() {
// We need to make sure that we import these files only in Node.js environment.
// OpenTelemetry is **not** supported on Edge or Client side at the moment.
if (process.env.NEXT_RUNTIME === 'nodejs') {
require('./instrumentation-node')
}
registerOTel('next-app')
}
......@@ -7,11 +7,7 @@
"start:otel-verbose": "NEXT_OTEL_VERBOSE=1 next start"
},
"dependencies": {
"@opentelemetry/api": "1.4.0",
"@opentelemetry/exporter-trace-otlp-http": "0.35.1",
"@opentelemetry/resources": "1.9.1",
"@opentelemetry/sdk-trace-base": "1.9.1",
"@opentelemetry/semantic-conventions": "1.9.1",
"@vercel/otel": "latest",
"next": "latest",
"react": "^18.2.0",
"react-dom": "^18.2.0"
......
// hello world api route
import { NextApiRequest, NextApiResponse } from 'next'
import { fetchGithubStars } from '../../shared/fetch-github-stars'
......
import { trace } from '@opentelemetry/api'
import { trace } from '@vercel/otel'
export async function fetchGithubStars() {
const span = trace.getTracer('nextjs-example').startSpan('fetchGithubStars')
return fetch('https://api.github.com/repos/vercel/next.js', {
next: {
revalidate: 0,
},
})
.then((res) => res.json())
.then((data) => data.stargazers_count)
.finally(() => {
span.end()
return await trace
.getTracer('nextjs-example')
.startActiveSpan('fetchGithubStars', async (span) => {
try {
const res = await fetch('https://api.github.com/repos/vercel/next.js', {
next: {
revalidate: 0,
},
})
const data = await res.json()
return data.stargazers_count
} finally {
span.end()
}
})
}
......@@ -210,7 +210,7 @@ async function getDefinedMetadata(
{
spanName: `generateMetadata ${route}`,
attributes: {
'next.route': route,
'next.page': route,
},
},
() => mod.generateMetadata(props, parent)
......
......@@ -1294,6 +1294,9 @@ export async function renderToHTMLOrFlight(
AppRenderSpan.getBodyResult,
{
spanName: `render route (app) ${pathname}`,
attributes: {
'next.route': pathname,
},
},
async ({
asNotFound,
......
......@@ -320,13 +320,16 @@ export class AppRouteRouteModule extends RouteModule<
}
)
// TODO: propagate this pathname from route matcher
const route = getPathnameFromAbsolutePath(this.resolvedPagePath)
getTracer().getRootSpanAttributes()?.set('next.route', route)
return getTracer().trace(
AppRouteRouteHandlersSpan.runHandler,
{
// TODO: propagate this pathname from route matcher
spanName: `executing api route (app) ${route}`,
attributes: {
'next.route': route,
},
},
() =>
handler(wrappedRequest, {
......
......@@ -795,6 +795,9 @@ export async function renderToHTML(
RenderSpan.getStaticProps,
{
spanName: `getStaticProps ${pathname}`,
attributes: {
'next.route': pathname,
},
},
() =>
getStaticProps!({
......@@ -1005,6 +1008,9 @@ export async function renderToHTML(
RenderSpan.getServerSideProps,
{
spanName: `getServerSideProps ${pathname}`,
attributes: {
'next.route': pathname,
},
},
async () =>
getServerSideProps({
......@@ -1366,6 +1372,9 @@ export async function renderToHTML(
RenderSpan.renderDocument,
{
spanName: `render route (pages) ${renderOpts.pathname}`,
attributes: {
'next.route': renderOpts.pathname,
},
},
async () => renderDocument()
)
......
import { Resource } from '@opentelemetry/resources'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
// You can use gRPC exporter instead
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
......
......@@ -89,6 +89,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/app/[param]/rsc-fetch",
"next.span_name": "render route (app) /app/[param]/rsc-fetch",
"next.span_type": "AppRender.getBodyResult",
},
......@@ -118,7 +119,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/app/[param]/layout",
"next.page": "/app/[param]/layout",
"next.span_name": "generateMetadata /app/[param]/layout",
"next.span_type": "ResolveMetadata.generateMetadata",
},
......@@ -131,7 +132,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/app/[param]/rsc-fetch/page",
"next.page": "/app/[param]/rsc-fetch/page",
"next.span_name": "generateMetadata /app/[param]/rsc-fetch/page",
"next.span_type": "ResolveMetadata.generateMetadata",
},
......@@ -153,6 +154,7 @@ createNextDescribe(
Array [
Object {
"attributes": Object {
"next.route": "/api/app/[param]/data/route",
"next.span_name": "executing api route (app) /api/app/[param]/data/route",
"next.span_type": "AppRouteRouteHandlers.runHandler",
},
......@@ -208,6 +210,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/pages/[param]/getServerSideProps",
"next.span_name": "getServerSideProps /pages/[param]/getServerSideProps",
"next.span_type": "Render.getServerSideProps",
},
......@@ -220,6 +223,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/pages/[param]/getServerSideProps",
"next.span_name": "render route (pages) /pages/[param]/getServerSideProps",
"next.span_type": "Render.renderDocument",
},
......@@ -258,6 +262,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/pages/[param]/getStaticProps",
"next.span_name": "getStaticProps /pages/[param]/getStaticProps",
"next.span_type": "Render.getStaticProps",
},
......@@ -270,6 +275,7 @@ createNextDescribe(
},
Object {
"attributes": Object {
"next.route": "/pages/[param]/getStaticProps",
"next.span_name": "render route (pages) /pages/[param]/getStaticProps",
"next.span_type": "Render.renderDocument",
},
......
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