Capturing Traces

NOOA traces every agent method call, LLM call, code execution, and tool invocation as OpenTelemetry spans using OpenInference semantic conventions. Traces are grouped by session.id and nested by call hierarchy.

Automatic tracing (zero config)

Every Agent.init() auto-attempts tracing once per process: it probes the trace viewer at http://localhost:5001 (or $OTLP_ENDPOINT) and, if reachable, streams spans to it. Nothing to import, nothing to call:

nooa start-dev            # terminal 1: viewer + OTLP receiver on :5001
uv run python my_agent.py    # terminal 2: traces appear automatically

If the viewer is not reachable, tracing is silently disabled. There is NO automatic fallback to files. The only exception: if you explicitly set OTLP_ENDPOINT and it's unreachable, a warning is printed to stderr. If you need traces without a viewer, use explicit file export (below).

Explicit tracing

from nooa.tracing import enable_tracing, exporters, flush_traces

# Write JSONL files — one file per session: {trace_dir}/{session_id}.jsonl
enable_tracing(exporters=[exporters.jsonl("./traces")])

# ... run the agent ...
flush_traces()   # force-flush pending spans (e.g. before process exit)

Signature: enabletracing(exporters=None, *, experiment=None, extraresourceattrs=None) -> None (source: src/nooa/tracing/init.py). It is idempotent for no-arg calls; calling again with explicit exporters replaces the previous exporters. experiment tags every span's resource with an experiment name (defaults to $TRACEEXPERIMENT), which the viewer uses to group eval runs.

Exporter factories (nooa.tracing.exporters)

Multiple destinations at once:

enable_tracing(exporters=[
    exporters.jsonl("./traces"),
    exporters.journal(),          # viewer too, if running
])

Session IDs

Spans are grouped by session.id. Set it explicitly when you need a stable, known ID (e.g. eval harnesses):

from nooa.tracing import set_session, get_session
set_session("my-run-001")   # call before running the agent

What gets traced

All agent methods are traced by default — public, private (_x), and async dunders. Generation methods, plain-Python orchestrators, and deterministic helpers all produce spans. Opt out per-method:

from nooa import no_trace

class MyAgent(Agent, llm=llm):
    @no_trace
    async def utility(self):
        """Runs (and generates) normally, but produces no span."""
        ...

(Older docs claiming "private methods are not traced" are outdated — trust this table.)

Parent-child nesting follows the call hierarchy: orchestrator → generation methods → generations → LLM calls / code executions.

Trace file format

Files are OTLP JSON Lines: each line is one {"resourceSpans": [...]} object. This is the interchange format for the whole toolchain — the viewer imports it (nooa import-traces ./traces) and the trace explorer reads it directly (trace-explorer ./traces/<session_id>.jsonl).

Environment variables

Pitfalls

• Do NOT use legacy OpenInference instrumentation imports or enabletracing(tracedir=...) — both appear in older docs/comments but do not exist. Tracing lives in nooa.tracing; tracedir is an argument of exporters.jsonl(), and enabletracing() returns None.
• Auto-tracing is attempted once per process. If the viewer wasn't running when the first Agent was constructed, later agents won't retry — call enable_tracing(...) explicitly or restart with the viewer up.
• For short scripts, call flush_traces() before exit; batch exporters flush on a ~1s schedule and a fast exit can drop the tail of a trace.
• Logic that runs outside agent methods (module-level preprocessing, main() helpers) is invisible in traces. Keep interesting logic inside agent methods so failures leave trace evidence.

Verifying capture works

from nooa.tracing import enable_tracing, exporters, flush_traces
enable_tracing(exporters=[exporters.jsonl("./traces")])
agent = MyAgent()
await agent.run("test")
flush_traces()
# ls ./traces/*.jsonl  → one file per session; inspect with trace-explorer

Related skills

• nooa-trace-viewer — run the web viewer and browse captured traces.
• nooa-trace-explorer — programmatic/CLI trace analysis and root-cause debugging.