Unverified Commit 60e68070 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

docs: note that instrumentation-time spans don't join request traces (#100324)

## Summary

Stacked on #100294.

Documents in the OpenTelemetry guide that spans created while
`instrumentation.ts` loads or inside `register()` don't automatically
join a request trace:

- Spans started before the tracer provider is installed (e.g. at module
top level before `registerOTel()`) are not recorded.
- Spans started inside `register()` after `registerOTel()` / the SDK has
started typically become separate root traces: the SDK installs the
context manager during `register()`, so no parent context set before
that is carried over.

It also clarifies the existing sentence so it refers to spans created
while handling a request, and recommends creating request-scoped spans
in request-handling code.

Making these spans nest under a Next.js span would require Next.js to
install its own global OpenTelemetry context manager before loading
`instrumentation.ts`; that was decided against, so this documents the
behavior instead.

## Verification

- Reproduced with `@opentelemetry/api`,
`@opentelemetry/context-async-hooks` and
`@opentelemetry/sdk-trace-base`: a span started before the provider
exists isn't exported; a span started after installing provider +
context manager inside a function wrapped in `context.with(parent, …)`
has no parent; the same `context.with` after the manager exists parents
correctly.

<!-- NEXT_JS_LLM -->


<!-- fleet ce0ecb23-b14c-4679-92a9-e676130f618e -->
Co-authored-by: 's avatarvercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: 's avatarTobias Koppers <1365881+sokra@users.noreply.github.com>
Co-authored-by: 's avatarLuke Sandberg <210140+lukesandberg@users.noreply.github.com>
Co-authored-by: 's avatarNiklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
parent 4abb437d
...@@ -248,7 +248,9 @@ export async function fetchGithubStars() { ...@@ -248,7 +248,9 @@ export async function fetchGithubStars() {
``` ```
The `register` function will execute before your code runs in a new environment. 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. After that, spans you create while handling a request are added to that request's trace.
> **Good to know**: Spans created while the `instrumentation` file is loaded, or inside `register`, don't automatically join a request trace. Spans started before the tracer provider is installed (for example, at the top level of the file before `registerOTel` runs) are not recorded, and spans started inside `register` after `registerOTel` (or your OpenTelemetry SDK) has started typically become separate root traces. To trace work as part of a request, create the span in code that runs while handling the request, such as when rendering a page or in a Route Handler or API Route.
## Default Spans in Next.js ## Default Spans in Next.js
......
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