PtcRunner.TraceLog.Collector (PtcRunner v0.7.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 tracks write errors and closes the file cleanly when stopped or terminated.

If the underlying file device process crashes, the collector logs a warning on the first write error and stops attempting further writes.

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

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(collector, json_line)

Writes a JSON line to the trace file.

write_event(collector, event)

Writes an event map to the trace file.

Types

t()

@type t() :: %PtcRunner.TraceLog.Collector{
  file: File.io_device() | nil,
  meta: map(),
  parent_ref: reference() | nil,
  path: String.t(),
  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.

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.
:meta - Additional metadata to include with the trace. Defaults to %{}.

Examples

{:ok, collector} = Collector.start_link(path: "/tmp/trace.jsonl")

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(collector, json_line)

@spec write(GenServer.server(), String.t()) :: :ok

Writes a JSON line to the trace file.

This is an asynchronous operation that never blocks the caller. Write errors are tracked but do not crash the caller.

write_event(collector, event)

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

Writes an event map to the trace file.

The event is encoded to JSON before writing.