Concepts

​

How a trace is structured

run: support-agent                                         kind: run
├─ llm openai.chat.completions                             kind: llm
│   prompt · completion · tokens · cost · model
├─ tool lookup_order                                       kind: tool
│   input · output · toolName
├─ retrieval vector-search                                 kind: retrieval
│   query · topK · results
└─ llm openai.chat.completions                             kind: llm
    second LLM call in the same run

​

Runs

• Inputs — the initial state and parameters passed to your agent.
• Outputs — the final result produced by your agent.
• Spans — the nested operations within the execution.
• Timing — duration and timing of each operation.
• Metadata — additional context like environment, version, custom tags.
• Rollups — total tokens, total cost, span count, tool count, error count — all summed from child spans, never written by you.

​

What you set vs. what’s rolled up

​

Run ID

const { result, runId } = await trodo.wrapAgent('my-agent', async (run) => { ... });

• Query and filter traces in the dashboard.
• Attach feedback after a run finishes.
• Link multi-turn conversations via a shared conversationId.
• Propagate the run across service boundaries (see Propagation).

​

Distinct ID

await trodo.wrapAgent('my-agent', fn, { distinctId: 'user-42' });

​

Conversation ID

await trodo.wrapAgent('chat', fn, { distinctId: 'user-42', conversationId: 'thread-abc' });

​

Spans

• An LLM generation call.
• A tool or function invocation.
• A retrieval / vector search.
• A nested agent stage.
• Any custom operation you want to track.

• Which operations happened in what order.
• How long each operation took.
• Where errors occurred in the execution path.
• What inputs each step received and what outputs it produced.

​

Span kinds

​

LLM span fields

​

Tool span fields

​

Retrieval span fields

​

Universal span fields

​

parent_run_id

​

Propagation

• In-process. Node uses AsyncLocalStorage, Python uses contextvars. Every withSpan, tool(), llm(), retrieval(), trace(), or auto-instrumented provider call inside wrapAgent (or inside any function it awaits) attaches automatically. Context survives await, imports, helper functions — the whole async chain inside the process.
• Cross-service. Trodo’s SDK attaches an X-Trodo-Run-Id header to outbound HTTP when you use propagationHeaders(). The receiving service’s middleware (expressMiddleware, fastapi_middleware) reads it and calls joinRun so its spans land on the caller’s run. See Recipes → Cross-service.
• Out-of-context. If you emit spans from a file outside an active wrapAgent — worker threads, process pools, queue consumers — you must capture the runId in the parent, pass it across the boundary, and call joinRun(runId, fn) in the child. See Tracing → Spans outside wrapAgent.

​

Projects and sites

• All runs from your agent(s) for a given environment.
• The users tracked in that environment.
• The dashboards, clusters, and monitors built on top of those runs.

• A site ID — used when calling trodo.init() and for SDK authentication.
• A dashboard for viewing and analysing data.

​

Tracer provider

• Dual export. You already run an OTel provider (Honeycomb, Datadog, Jaeger). Trodo attaches its own span processor alongside yours — both backends receive every span. See Recipes → Dual export.
• Advanced custom instrumentation. Use trodo.getTracer() to get the underlying OTel tracer if you want to emit spans via the raw OTel API. They flow through to Trodo like any other span.

​

Next steps

• Tracing → wrapAgent — every option on the run.
• Tracing → Spans — full field reference with examples.
• Tracing → Patterns — custom attributes, errors, feedback, tokens & cost.
• Integrations — per-framework setup.