0840d521d5
### What?
This PR adds an experimental option `clientTraceMetadata` that will use
the existing OpenTelemetry functionality to propagate conventional
OpenTelemetry trace information to the client.
The propagation metadata is propagated to the client via meta tags,
having a `name` and a `content` attribute containing the value of the
tracing value:
```html
<html>
<head>
<meta name="baggage" content="key1=val1,key2=val2">
<meta name="traceparent" content="00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01">
<meta name="custom" content="foobar">
</head>
</html>
```
The implementation adheres to OpenTelemetry as much as possible,
treating the meta tags as if they were tracing headers on outgoing
requests. The `clientTraceMetadata` will contain the keys of the
metadata that're going to injected for tracing purpose.
### Why?
Telemetry providers usually want to provide visibility across the entire
stack, meaning it is useful for users to be able to associate, for
example, web vitals on the client, with a span tree on the server. In
order to be able to correlate tracing events from the front- and
backend, it is necessary to share something like a trace ID or similar,
that the telemetry providers can pick up and stitch back together to
create a trace.
### How?
The tracer was extended with a method `getTracePropagationData()` that
returns the propagation data on the currently active OpenTelemetry
context.
We are using `makeGetServerInsertedHTML()` to inject the meta tags into
the HTML head for dynamic requests.
The meta tags are generated through using the newly added
`getTracePropagationData()` method on the tracer.
It is important to mention that **the trace information should only be
propagated for the initial loading of the page, including hard
navigations**. Any subsequent operations should not propagate trace data
from the server to the client, as the client generally is the root of
the trace. The exception is initial pageloads, since while the request
starts on the client, no JS has had the opportunity to run yet, meaning
there is no trace propagation on the client before the server hasn't
responded.
Situations that we do not want tracing information to be propagated from
the server to the client:
- _Prefetch requests._ Prefetches generally start on the client and are
already instrumented.
- _Any sort of static precomputation, including PPR._ If we include
trace information in static pages, it means that all clients that will
land on the static page will be part of the "precomputation" trace. This
would lead to gigantic traces with a ton of unrelated data that is not
useful. The special case is dev mode where it is likely fine to
propagate trace information, even for static content, since it is
usually not actually static in dev mode.
- _Clientside (soft) navigations._ Navigations start on the client and
are usually already instrumented.
### Alternatives considered
An implementation that purely lives in user-land could have been
implemented with `useServerInsertedHTML()`, however, that implementation
would be cumbersome for users to set up, since the implementation of
tracing would have to happen in a) the instrumentation hook, b) in a
client-component that is used in a top-level layout.
### Related issues/discussions
- https://github.com/vercel/next.js/issues/47660
- https://github.com/vercel/next.js/discussions/62353 (Could be used as
an alternative to the server-timing header)
- https://github.com/getsentry/sentry-javascript/issues/9571
---------
Co-authored-by: Jiachi Liu <inbox@huozhi.im>
35 lines
1.1 KiB
TypeScript
35 lines
1.1 KiB
TypeScript
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
|
|
import { trace } from '@opentelemetry/api'
|
|
|
|
export async function register() {
|
|
if (process.env.NEXT_RUNTIME === 'nodejs') {
|
|
const provider = new NodeTracerProvider()
|
|
provider.register({
|
|
propagator: {
|
|
inject(context, carrier, setter) {
|
|
setter.set(carrier, 'my-test-key-1', 'my-test-value-1')
|
|
setter.set(carrier, 'my-test-key-2', 'my-test-value-2')
|
|
// This non-metadata-key-3 is not going to be injected into the page
|
|
setter.set(carrier, 'non-metadata-key-3', 'non-metadata-key-3')
|
|
setter.set(
|
|
carrier,
|
|
'my-parent-span-id',
|
|
trace.getSpanContext(context).spanId
|
|
)
|
|
},
|
|
extract(context) {
|
|
// This is a noop because we don't extract in this test
|
|
return context
|
|
},
|
|
fields() {
|
|
return [
|
|
'my-parent-span-id',
|
|
'my-test-key-1',
|
|
'my-test-key-2',
|
|
'non-metadata-key-3',
|
|
]
|
|
},
|
|
},
|
|
})
|
|
}
|
|
}
|