Observability¶

Every action the agent takes — LLM calls, tool invocations, connector queries, workflow steps — is recorded as a structured TraceEntry on the agent's ActionTracer. Traces can be inspected programmatically or exported to JSONL files via the JSONLExporter.

For narrative coverage of trace shape, cost tracking, and operational use see Action Traces and Cost Tracking. For the parallel mechanism that protects LLM-visible payloads from filesystem leaks see Security.

`ActionTracer`¶

ActionTracer ¶

ActionTracer(*, max_entries: int = 1000)

Records and stores agent action traces.

Example

tracer = ActionTracer()
with tracer.trace("llm_call", operation="complete") as span:
    result = await llm.complete(messages)
    span.output_summary = result[:100]

entries `property` ¶

entries: list[TraceEntry]

All recorded trace entries.

subscribe(callback: Callable[[TraceEntry], Any]) -> None

Register a callback invoked on every new entry.

record ¶

record(entry: TraceEntry) -> None

Add a trace entry and notify subscribers.

trace ¶

trace(action: str, *, connector: str = '', asset_id: str = '', operation: str = '', conversation_id: str = '', **metadata: Any) -> _TraceContext

Context manager that records timing and outcome.

Parameters:

Name	Type	Description	Default
`action`	`str`	Action category (e.g. `"llm_call"`, `"connector_query"`).	required
`connector`	`str`	Connector name involved.	`''`
`asset_id`	`str`	Asset context.	`''`
`operation`	`str`	Specific operation name.	`''`
`conversation_id`	`str`	Conversation/session identifier.	`''`
`**metadata`	`Any`	Extra metadata to attach.	`{}`

Returns:

Type	Description
`_TraceContext`	A context manager yielding a :class:`TraceEntry` that will
`_TraceContext`	be finalised and recorded on exit.

clear ¶

clear() -> None

Remove all recorded entries.

summary ¶

summary() -> list[dict[str, Any]]

Return a serialisable summary of all entries.

`TraceEntry`¶

TraceEntry ¶

Bases: BaseModel

A single traced action performed by the agent.

redacting_dump_json ¶

redacting_dump_json(*, max_summary_chars: int = 2000) -> str

Serialize to JSON with secret redaction and summary truncation.

Unlike model_dump_json(), this method: - Redacts metadata keys matching sensitive patterns - Truncates input_summary and output_summary

`JSONLExporter`¶

Subscribes to an ActionTracer and writes one redacted JSON object per line to a daily-rotated file. Secrets are stripped automatically — see the _REDACT_PATTERNS constant in the source for the exact key set.

JSONLExporter ¶

JSONLExporter(path: str | Path, *, rotate_daily: bool = True, max_summary_chars: int = 2000)

Write trace entries as redacted JSONL with daily file rotation.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Directory where JSONL files are written.	required
`rotate_daily`	`bool`	If True (default), each day gets a separate file.	`True`
`max_summary_chars`	`int`	Truncation limit for summary fields.	`2000`

Raises:

Type	Description
`FileNotFoundError`	If `path` is inside a missing parent.

attach ¶

attach(tracer: ActionTracer) -> None

Subscribe to a tracer so entries are written automatically.