Tracing

Overview

Coevolved includes an event-based tracing system that emits structured events for:

• Step lifecycle (start, end, error)
• LLM prompts/responses
• Tool calls/results
• Agent loop phases (loop start/end, iteration start/end)

Tracing is designed to be:

• pluggable (swap sinks/formatters)
• safe (sink failures should not break execution)
• privacy-aware (snapshot policies, optional prompt logging)

Events and sinks

Events are dataclasses emitted by a Tracer. A tracer can be configured with one or more sinks.

The default tracer includes a console sink for lightweight visibility during development.

Common sink strategies:

• Log to stdout in dev
• Write JSON lines to a file in staging
• Forward events to a queue or observability pipeline in production

If you want JSONL output, use JSONLSink with a serializer:

from coevolved.base import (
    ConsoleSink,
    JSONLSink,
    Tracer,
    make_verbose_jsonl_serializer,
    set_default_tracer,
)

serializer = make_verbose_jsonl_serializer()
tracer = Tracer(sinks=[ConsoleSink(), JSONLSink("coevolved.trace.jsonl", serializer=serializer)])
set_default_tracer(tracer)

Snapshot policy

Snapshots are optional “captured views” of input/output state attached to events.

SnapshotPolicy controls when snapshots are captured:

• Start events (input snapshot)
• End events (output snapshot)
• Error events (input snapshot)

The default behavior captures inputs on errors only. This is often the right tradeoff between debuggability and data exposure.

Input hashing and redaction

To group invocations and de-duplicate traces, the tracer computes a hash of the input.

If you pass a redactor to the tracer, it can scrub sensitive fields before hashing.

Hashing is a grouping tool, not a security boundary. If you handle secrets, implement redaction and avoid logging full prompt text.

Custom formatters

Formatters convert events to text (for console/file sinks) or to structured payloads you can export.

If you want different formatting per event type (step vs LLM vs agent), use a per-type formatter approach.

Next steps

Observability guide

Practical tracing setups for local dev and production.

base.tracing reference

Event types, tracer API, and snapshot policy details.