agentrail-go adds your Go servers to a journey. It records the requests your server answers and the calls it makes while answering them, the identity your application verified, the milestones you name, your slog logs and your MCP tool calls. It needs Go 1.26 or later.
The same features are in the Python SDK. The Node SDK has them too, except the approximate location and workflow tracking.
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 and operation references 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
New returns an error when an option is wrong. It never reads environment variables itself, so check yours are set before calling it.
Middlewarerecords each request it wraps. Install it once. If you already trace incoming requests withotelhttp, replace that for this scope, or each request is recorded twice.Transportrecords outgoing calls. Only the exact origins inOutboundOriginsreceive your trace context.OnErroris told of anything that could not be captured or delivered. None of it replaces your application’s response.
New registers no global provider. If your application already has an OpenTelemetry provider, use NewProcessors and Bind, as the module’s README 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.
Name who is calling
After your application has authenticated a request, tell Agentrail who it was:PrincipalUser, PrincipalAgentRegistration, PrincipalAgentInstance, PrincipalOAuthClient or PrincipalAPIKey. 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:Milestone records an instant step, and StartMilestone returns a function to end one yourself. Use a stable operation name, without arguments or ids. Your error is returned as it was, and a panic is raised again. To report workflow attempts and plugin calls on a milestone, see Plugin workflow tracking.
Send your logs
Theslog handler passes every record on to your own handler unchanged:
…Context calls, so a log is tied to its request. 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 the handlers you register with the official MCP Go SDK:capturemcp.ToolHandler, capturemcp.Resource and capturemcp.Prompt wrap the others. This targets MCP Go SDK 1.8.0. Arguments, results, prompt text and resource addresses are not recorded.
Add an approximate location
To record where a request came from, setIncomingLocation. It runs for each request and returns the country, region and city from your platform’s trusted headers or a local database:
Country is a two-letter code, and Source is LocationCloudflare, LocationVercel, LocationDBIP or LocationConfigured. Return agentrail.IPLocation{} when there is none. Make no network call in it. Without it, no location is recorded.
Shut down cleanly
Stop accepting requests, wait for your handlers, then callcapture.Shutdown(ctx), so what is queued is sent. Records wait in a bounded queue in memory, with nothing kept on disk. capture.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 Go SDK reference.
Next, leave out your own servers, and see what Agentrail records.