Skip to content

OpenTelemetry Traces

Some agents give Omnodex nothing to hook into. Claude Managed Agents run on Anthropic’s platform, and plenty of in-house agents are just an application calling a model API. What many of them can do is export OpenTelemetry traces. omnodex otel serve runs a small receiver for those traces on a machine you control. It turns each span into an Omnodex event, writes it to the local event log, and runs the community rules over it, the same as a hook would.

Prompts and tool arguments go from the agent to your receiver and stay with you. Nothing passes through Omnodex’s servers unless you’ve connected the machine to the hosted dashboard, and then only encrypted, as with any other event.

Your agentUse
Claude Code, Codex, Antigravity, GitHub Copilot, Cursor, OpenCodeTheir hooks. See the setup guide for each. Hooks see more and can stop a call; traces can’t
An MCP client with no hooksThe MCP proxy
Claude Managed Agents, or your own agent built on an SDK that emits OpenTelemetry GenAI spansThis receiver

Receiving traces from an agent on the same machine

Section titled “Receiving traces from an agent on the same machine”
  1. Start the receiver.

    Terminal window
    omnodex otel serve

    It listens on 127.0.0.1:4318, the standard OTLP/HTTP port, and prints the address it receives traces at. Leave it running: Ctrl+C stops it and prints how many spans it received and how many events and findings it wrote. Use --listen <host:port> for a different port.

  2. Point the agent’s exporter at it. Most OpenTelemetry SDKs read the standard variable:

    Terminal window
    export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

    The receiver takes OTLP over HTTP as protobuf or JSON, compressed or not.

  3. Run the agent. Sessions appear in the local dashboard as they arrive.

With no token set, any process on the same machine can post spans to the receiver. To require one, run omnodex otel token once (see Tokens) and give it to the exporter:

Terminal window
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<token>"

Receiving traces from Claude Managed Agents

Section titled “Receiving traces from Claude Managed Agents”

Managed Agents send their telemetry from Anthropic’s platform to a destination you set up in the Claude Console. That destination has to reach your receiver over the internet, so the receiver can’t stay on loopback.

  1. Create a token.

    Terminal window
    omnodex otel token

    It prints the token on its own line. Keep it somewhere safe; it only lets a sender post spans to this receiver.

  2. Start the receiver on an outside address.

    Terminal window
    omnodex otel serve --listen 0.0.0.0:4318 --allow-remote

    The receiver refuses to listen anywhere but loopback without both --allow-remote and a token.

  3. Put it behind TLS. The receiver speaks plain HTTP. Run it behind a reverse proxy or tunnel that terminates HTTPS, so spans and the token never cross the internet in the clear.

  4. Add the destination in the Console. Use your HTTPS address as the endpoint and send the token as Authorization: Bearer <token>. The Console’s Test button reaches the receiver and is counted, but writes nothing to your log.

  5. Run an agent session. Sessions appear in the local dashboard as the spans arrive.

The receiver answers each delivery as soon as it has checked the token and saved the body, then works through what it saved. A sender that waits only a few seconds, or disables a destination that keeps failing, gets a fast answer even when a large batch is still being processed. Anything saved but not yet processed when the receiver stops is picked up again at the next start, so a restart loses nothing. A span delivered twice maps to the same event IDs, so it counts once in the dashboards.

From the traceRecorded as
A turn, with the user’s messageA session, and the prompt that started the turn
The model the turn requestedThe session’s model, and a marker when it changes
A tool call span, with its arguments and result sizeA tool call, with its duration and whether it failed. File reads and writes are recorded as file events too
A tool that asked for permissionA permission request
A sub-agentSub-agent start and stop
A call the turn made but that has no tool span (Managed Agents)A permission denial, marked as inferred

The receiver reads spans by their OpenTelemetry GenAI attributes (gen_ai.operation.name of invoke_agent or execute_tool), plus the attributes Claude’s own spans carry. Spans it doesn’t recognize are counted and skipped. Log exports are accepted and ignored.

Recorded events go through the same steps as hook events: credentials Omnodex recognizes are masked when captured, pausing applies, and the community rules run. If the machine is connected to the hosted dashboard, events are pushed to it live as well, and reach its stored history at the machine’s next sync.

The token is stored in your Omnodex home. Once it exists, serve requires it on every request, and the start-up message says so.

CommandWhat it does
omnodex otel tokenPrint the token, creating it the first time
omnodex otel token --rotateReplace it. Restart the receiver, then update every sender
OMNODEX_OTEL_TOKEN=<token>Use this token instead of the stored one, for example from a service manager’s secret store

GET /healthz answers without a token, for a load balancer or uptime check. GET /status (with the token) returns counts: requests answered and refused, spans received, mapped and skipped, events and findings written, and anything still waiting.

  • Telemetry can’t stop anything. A span is sent after the work it describes has finished, so shadow mode and guardrails don’t apply to these sessions. Findings are recorded after the fact.
  • The receiver only knows what it’s sent. Spans the agent never exports, or that its sampler drops, leave no trace, and Omnodex can’t tell they’re missing. Turn sampling off, or set it to keep every trace, for agents you want a full record of.
  • Inferred denials are a best guess. Managed Agents leave out the span for a denied call, so a call named in a turn’s output with no tool span after 30 seconds is recorded as denied. A span that arrives later than that leaves a denial in the log for a call that ran.
  • What’s in a span depends on the sender. If an SDK doesn’t include tool arguments or messages, Omnodex can’t record them, and rules that read them have nothing to work with.