agentrail-node adds your servers to a journey. It records the requests your server answers and the HTTP and fetch calls it makes while answering them, the identity your application verified, the milestones you name, your structured logs and your MCP tool calls. It needs Node 22 or later.
The Go SDK and the Python SDK have the same features, and can also add an approximate location to each request and report workflow attempts.
Create a server source
An Admin creates the source once. One source can serve every service that shares it.1
Open Set up
Open Journeys, select Set up and choose Your servers. If you are in Settings · Journeys, select Add source, then Your servers.
2
Name the source
Enter a Name, such as “API servers”, and select Create source.
3
Save the secret and hash key
Agentrail shows the Secret and the Hash key once, with the Collector endpoint and the install commands. Copy them before you select I have saved them. If you lose one, revoke the source and create another.
AGENTRAIL_SECRETlets your servers send this source’s events.AGENTRAIL_HASH_KEYis your workspace’s key. Identities are hashed with it before anything leaves your server. Give the edge and every server the same one.
<collector>. The Collector endpoint Agentrail shows has yours in it.
Install it
instrumentation.ts, and load it before your application’s HTTP modules:
serviceNamenames this service on each step.outboundOriginslists the exact origins allowed to receive your trace context. The default is none.onErroris told of anything that could not be captured or delivered. The default is the console. None of it replaces your application’s response.
init refuses to start. Use createProcessors instead, as An existing OpenTelemetry setup describes.
Join the edge to your servers
Withagentrail-edge in front of your site, each request reaches your server with a signed trace, so the edge’s step and your server’s step join as a proof. Give both the same workspace hash key. Your server continues that trace only if the signature is valid, and only for 60 seconds, so keep your clocks synchronized. Direct calls start a trace of their own.
If your edge rewrites a request’s path or query, do it in prepareOriginRequest on the edge’s adapter, so the rewrite happens before signing.
Name who is calling
After your application has authenticated a request, tell Agentrail who it was:user, agent_registration, agent_instance, oauth_client or api_key. Ids are hashed before they leave your server. Nothing a caller merely says about itself becomes a verified identity.
Mark a milestone
A milestone is a step you name, such as a confirmed order:Send your logs
The Pino hook leaves your logger’s own output unchanged:logs.includeFields, so never list anything that holds credentials or customer content. A log is never proof that two steps belong together.
Record MCP calls
Wrap your MCP server’s callbacks to record each call as a step:capture.resource and capture.prompt wrap resources and prompts the same way. This targets @modelcontextprotocol/server 2.3.1. Arguments, results, prompt text and resource addresses are not recorded.
Shut down cleanly
Callawait agentrail.shutdown() when your application stops, so what is queued is sent. Records wait in a bounded queue in memory, with nothing kept on disk. agentrail.diagnostics() reports what was accepted, sent, dropped and still waiting.
Every option, the error codes and how to use an existing OpenTelemetry setup are in the Node SDK reference.
Next, leave out your own servers, and see what Agentrail records.