agentrail-node. To install it, start with Install the Node SDK. It needs Node 22 or later.
Options
init and createProcessors take the same options. Invalid options throw a ConfigurationError, so check your environment before calling them.
How init starts
init installs one tracer provider, one logger provider, an async context manager and the instrumentation for http and fetch. Load it before your application’s HTTP modules, with node --import, so the requests your application makes are recorded too.
Calling init again with the same options object returns the same client, and calling it with different options throws. It refuses to replace an OpenTelemetry provider, context manager or propagator that is already installed. If another library already set one up in your process, use createProcessors instead. After shutdown, the installation cannot be started again.
Requests from the edge
Withagentrail-edge in front of your service, the edge signs each request it forwards. A request with a valid signature continues the edge’s trace, so your server’s steps join the visit the edge recorded. A direct call, or one whose signature fails, starts a trace of its own, and a trace context the caller sent is kept only as a link.
The signature covers the method, the exact path and query, and the time it was made, and is accepted for 60 seconds. So:
- give the edge and every service the same workspace hash key;
- keep your servers’ clocks synchronized;
- rewrite a path or query on the edge in
prepareOriginRequest, before it signs.
outboundOrigins receive your trace context, and the address a call actually connects to decides, not a Host header. Baggage and trace state never leave a recorded request. The SDK’s own calls to the collector are not recorded.
Logs
The Pino hook works with Pino 9 and 10. It records in the caller’s async context and leaves your logger’s own output unchanged. Pass an existing hook as its second argument to keep it. By default, a log sends its severity, error type, event name, a stable id and the span it was written in. Message text and other fields are sent only when you list them inlogs.includeFields: ['msg'] for Pino, ['message'] for an OpenTelemetry log body. agentrail.log() picks the fields from its fields value.
Only listed top-level fields with text, number, boolean or null values are sent, in the order you listed them, as a JSON object of at most 4,096 characters. A long value is shortened to fit, and a field that cannot fit is left out. Never list fields that hold credentials, identities or customer content.
MCP
The MCP adapter targets@modelcontextprotocol/server 2.3.1 and wraps the callbacks you register, without changing the server’s own handlers or transports. Each call is recorded with its registered name, method, the client’s name and version, the protocol version and whether it failed. A result with isError marks the step as failed and is returned unchanged.
Behind HTTP capture, each call nests under its request and shares its verified identity. Outside a request, it starts a step of its own. The protocol version 2026-07-28 and the official client’s 2025-11-25 HTTP exchange are tested. A stateless server may not know the client’s name after a 2025-11-25 initialize request. What a client says about itself is never a verified identity.
An existing OpenTelemetry setup
If your process already sets up OpenTelemetry, create the processors before you construct your provider. A provider that is already running cannot recover the spans its sampler dropped.- Pass your existing propagator as
propagator, and register the returnedcapture.propagator, not yours. It hands work outside recorded requests to yours, and stops a late injection from adding headers to a recorded call. - Install only one HTTP and one Undici instrumentation, with these options. Keep the propagator and the HTTP options together: they are how a signature is checked against the method and path.
createProcessorsregisters nothing globally, and never changes what your other processors and exporters receive.- The sampler keeps the spans of a recorded request your sampler would drop, as record-only, without changing your sampled flag. An exporter that sends only sampled spans behaves as before. Without it, a dropped entry is reported as
entry_not_recording. agentrail.shutdown()never shuts down your provider.
SentrySampler, keep SentrySpanProcessor and its context manager, pass new SentryPropagator() as propagator, and register the returned capture.propagator globally. Even at a 100% sample rate, Sentry drops HEAD and OPTIONS requests, which only the sampler wrapper keeps.
Recording after your framework admits a request. If your framework authenticates or parses a request before your handler runs, you can record from that point: use the HTTP options and propagator in the admitted part of your application, and turn off automatic incoming instrumentation, so each request has one entry. What happens before that point is not recorded.
This release is built on OpenTelemetry API 1.9.1, SDK 2.10.0, logs, exporters and HTTP instrumentation 0.221.0, and Undici instrumentation 0.31.0. Check that your own OpenTelemetry packages are compatible when you combine them.
Delivery and shutdown
Records wait in a bounded queue in memory, one for spans and one for logs. Nothing is written to disk.
Limits must be positive whole numbers,
batchSize cannot be more than maxRecords, and the flush and shutdown times cannot be shorter than exportTimeoutMs. One batch is sent at a time. A send the collector can retry is retried within its time; a refusal, or a batch still failing, is dropped and reported.
await agentrail.flush()waits until every record accepted so far has been tried. It does not mean every record arrived.await agentrail.shutdown()stops recording and sends what is queued, once. Call it after your server stops taking requests.agentrail.diagnostics()reports the records accepted, sent, dropped and still waiting, for spans and for logs.
Capture errors
A capture problem never changes your application’s response. Each goes toonError with a code, a signal (traces, logs or context) and a count of records, and never holds customer data.
Reporting runs outside capture, even when it goes through the same Pino or OpenTelemetry logger, so it can never fill the queue it reports on. If your
onError throws, both errors go to the console and delivery carries on.
What is sent
- Each request’s method, route, status and user agent, the hash of its verified identity, and only Agentrail’s own
hmarkers from its address. An address longer than 4,096 characters is left out, and the step is kept. - Supporting operations carry only their place in the trace and their timing: their names are replaced, and exception details and status messages are dropped.
- The service name and instance, the SDK’s name and version, and the hash key’s id, never the key.