Observability
JSON logs and OpenTelemetry traces for every session.
JSON logs
EGIN_LOG=json egin serve my-agent
Every stored event is written to stderr as one JSON line: model replies, tool calls and results, approvals, errors. Pipe it into whatever already collects your logs. egin’s own messages, such as “resuming session” or a schedule starting, are plain text on the same stream, so keep the lines that start with {.
Traces
Set an OTLP endpoint and egin exports spans over OTLP/HTTP:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 egin serve my-agent
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT works too, and OTEL_EXPORTER_OTLP_HEADERS (or OTEL_EXPORTER_OTLP_TRACES_HEADERS) adds headers as key=value,…, for a backend that needs a key.
To keep where traces go in the agent folder, add a file to instrumentation/. Every file is one more destination, besides the environment’s:
# instrumentation/honeycomb.toml
endpoint = "https://api.honeycomb.io/v1/traces"
headers = { x-honeycomb-team = "${HONEYCOMB_API_KEY}" }
${VAR} reads the host’s environment when a span is sent, so the file holds no secret. egin add instrumentation/honeycomb writes this one; the catalog also has Sentry, Langfuse, Axiom and a local Jaeger. egin info lists where traces go.
Each session is one trace: a session.run span for each run, and under it a span per model call and per tool call, so a slow tool or an expensive turn is easy to find. A subagent is a session of its own, so it exports a trace of its own.
Trace view
The web template (egin init my-chat --template web) lists every session at /traces, and shows each one’s trace at /traces/<session id>. A trace is one timeline with each model call, tool call and subagent, their time and cost, and the time spent waiting for an approval. It updates live while the run goes on. The chat’s header links to the current conversation’s trace.
The view reads the session’s own event stream, so it needs nothing else running. Every stored event carries at, the time it happened in Unix milliseconds. Each assistant event also carries the call’s model, cost in dollars, and ms, how long the call took.
Inside the database
Everything is also in .egin/egin.db. GET /sessions/{id} returns a session’s status, token and cost stats, and its messages.