Skip to main content
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.
Keep both in your platform’s secrets, never in your code or a page:
  • AGENTRAIL_SECRET lets your servers send this source’s events.
  • AGENTRAIL_HASH_KEY is your workspace’s key. Identities are hashed with it before anything leaves your server. Give the edge and every server the same one.
The examples below write the collector’s address as <collector>. The Collector endpoint Agentrail shows has yours in it.

Install it

Create instrumentation.ts, and load it before your application’s HTTP modules:
  • serviceName names this service on each step.
  • outboundOrigins lists the exact origins allowed to receive your trace context. The default is none.
  • onError is told of anything that could not be captured or delivered. The default is the console. None of it replaces your application’s response.
If your application already has an OpenTelemetry provider, init refuses to start. Use createProcessors instead, as An existing OpenTelemetry setup describes.

Join the edge to your servers

With agentrail-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:
The kind is 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:
Use a stable operation name, without arguments or ids. The result of your callback is returned as it was, and an error it throws is thrown again.

Send your logs

The Pino hook leaves your logger’s own output unchanged:
By default, a log sends its severity, error type, event name, a stable id and the span it belongs to. Message text is sent only for the fields you list in 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

Call await 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.