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.
When to use it
Section titled “When to use it”| Your agent | Use |
|---|---|
| Claude Code, Codex, Antigravity, GitHub Copilot, Cursor, OpenCode | Their hooks. See the setup guide for each. Hooks see more and can stop a call; traces can’t |
| An MCP client with no hooks | The MCP proxy |
| Claude Managed Agents, or your own agent built on an SDK that emits OpenTelemetry GenAI spans | This receiver |
Receiving traces from an agent on the same machine
Section titled “Receiving traces from an agent on the same machine”-
Start the receiver.
Terminal window omnodex otel serveIt 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. -
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:4318The receiver takes OTLP over HTTP as protobuf or JSON, compressed or not.
-
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:
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.
-
Create a token.
Terminal window omnodex otel tokenIt prints the token on its own line. Keep it somewhere safe; it only lets a sender post spans to this receiver.
-
Start the receiver on an outside address.
Terminal window omnodex otel serve --listen 0.0.0.0:4318 --allow-remoteThe receiver refuses to listen anywhere but loopback without both
--allow-remoteand a token. -
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.
-
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. -
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.
What gets recorded
Section titled “What gets recorded”| From the trace | Recorded as |
|---|---|
| A turn, with the user’s message | A session, and the prompt that started the turn |
| The model the turn requested | The session’s model, and a marker when it changes |
| A tool call span, with its arguments and result size | A tool call, with its duration and whether it failed. File reads and writes are recorded as file events too |
| A tool that asked for permission | A permission request |
| A sub-agent | Sub-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.
Tokens
Section titled “Tokens”The token is stored in your Omnodex home. Once it exists, serve requires it on every request, and the start-up message says so.
| Command | What it does |
|---|---|
omnodex otel token | Print the token, creating it the first time |
omnodex otel token --rotate | Replace 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 |
Checking it
Section titled “Checking it”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.
Limits
Section titled “Limits”- 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.
Next steps
Section titled “Next steps”- CLI Commands: every option for
otel serveandotel token - Local Dashboard: where the sessions appear
- Event Schema: the fields in each event