Skip to main content

​
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.tracing import Tracer, set_default_tracer
from coevolved.base.sinks import ConsoleSink, JSONLSink
from coevolved.base.sinks.jsonl import make_verbose_jsonl_serializer

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.