PtcRunner.TraceLog.Collector (PtcRunner v0.13.0)

GenServer that collects trace events and writes them to a JSONL file.

The Collector holds an open file handle and writes events as they arrive. It manages a monotonic seq counter for deterministic event ordering and deduplicates agent.config events by agent_id.

Events are written in v2 format with schema_version: 2.

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

max_event_bytes()

Returns the event byte cap applied before enqueueing and writing events.

max_mailbox_len()

Returns the collector mailbox length at which new events are shed.

path(collector)

Returns the file path for this collector's trace output.

start_link(opts \\ [])

Starts a new Collector process.

stop(collector)

Stops the Collector and closes the file.

trace_id(collector)

Returns the trace_id for this collector.

write_event(collector, event)

Writes an event map to the trace file.

Types

t()

@type t() :: %PtcRunner.TraceLog.Collector{
  emitted_agent_ids: MapSet.t(String.t()),
  file: File.io_device() | nil,
  header: term(),
  meta: map(),
  parent_ref: reference() | nil,
  path: String.t(),
  seq: non_neg_integer(),
  start_time: integer(),
  trace_id: String.t(),
  write_errors: non_neg_integer()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

max_event_bytes()

@spec max_event_bytes() :: pos_integer()

Returns the event byte cap applied before enqueueing and writing events.

max_mailbox_len()

@spec max_mailbox_len() :: non_neg_integer()

Returns the collector mailbox length at which new events are shed.

path(collector)

@spec path(GenServer.server()) :: String.t()

Returns the file path for this collector's trace output.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts a new Collector process.

Options

:path - File path for the JSONL output. Defaults to a timestamped file in the directory configured by Application.get_env(:ptc_runner, :trace_dir), or CWD if unset.
:trace_id - Unique identifier for this trace. Defaults to a random hex string.
:trace_kind - Discriminator for the type of trace (e.g., "benchmark", "analysis", "planning").
:producer - Identifier for the component that created this trace (e.g., "demo.benchmark").
:trace_label - Human-readable label for this trace (e.g., test case name).
:model - LLM model used for this trace.
:query - The input query or question for this trace.
:meta - Producer-specific metadata to include under data. Defaults to %{}.

Examples

{:ok, collector} = Collector.start_link(
  path: "/tmp/trace.jsonl",
  trace_kind: "benchmark",
  producer: "demo.benchmark",
  query: "How many products?"
)

stop(collector)

@spec stop(GenServer.server()) :: {:ok, String.t(), non_neg_integer()}

Stops the Collector and closes the file.

Returns the path to the trace file and the number of write errors.

Examples

{:ok, path, errors} = Collector.stop(collector)

trace_id(collector)

@spec trace_id(GenServer.server()) :: String.t()

Returns the trace_id for this collector.

write_event(collector, event)

@spec write_event(GenServer.server(), map()) :: :ok

Writes an event map to the trace file.

The event is assigned a monotonic seq number server-side, then encoded to JSON and written. If the event carries an agent_id with an agent_config in its data, the collector will emit an agent.config event first (deduplicated by agent_id).

This is an asynchronous operation that never blocks the caller.