base.tracing

Events

All trace events inherit from BaseEvent and carry core identifiers:

• run_id
• step_id
• invocation_id
• group_hash
• step_name
• event
• timestamp

Step lifecycle events are emitted as StepEvent with event values:

• "start"
• "end"
• "error"

Tracer

Tracer is the coordinator that:

• Emits events to sinks
• Computes input hashes (optionally after redaction)
• Applies snapshot policies

You can get the global tracer via get_default_tracer() and override it via set_default_tracer(...).

Sinks and formatters

Sinks receive events and decide where to send them (console, file, external service).

Formatters convert events into readable strings or structured payloads. Coevolved includes a simple default formatter and supports per-type formatting.

Built-in sinks live under coevolved.base.sinks:

• ConsoleSink (coevolved.base.sinks.console)
• JSONLSink (coevolved.base.sinks.jsonl)

The JSONL sink is serializer-driven. Coevolved provides a helper to build a verbose serializer:

from coevolved.base import JSONLSink, make_verbose_jsonl_serializer

sink = JSONLSink("coevolved.trace.jsonl", serializer=make_verbose_jsonl_serializer())

Snapshot policy

SnapshotPolicy controls whether Coevolved captures input/output snapshots in trace events.

Common settings:

• Errors-only (default): capture input snapshot only on error
• Capture everything: input on start, output on end, input on error

Invocation context

Coevolved stores invocation metadata in a context variable so nested code can access it without manual threading.

This enables LLM/tool event emission to link back to the originating step invocation.

Next steps

Tracing concept

The high-level model: events, sinks, snapshots, privacy.

Observability guide

Practical setups for dev and production.