PtcRunner.TraceLog.Event (PtcRunner v0.9.0)

Copy Markdown View Source

Handles safe JSON encoding for telemetry events.

Transforms telemetry data into JSON-safe formats by:

  • Converting PIDs, refs, functions to string representation
  • Summarizing large strings (>64KB by default)
  • Summarizing large lists (>100 items by default)
  • Summarizing large maps (>100 keys by default)
  • Handling binary data safely
  • Recursively sanitizing nested structures

Configuration

Sanitization limits are runtime-configurable via application config:

  • :trace_max_string_size - Maximum string size in bytes before truncation (default: 65_536)
  • :trace_max_list_size - Maximum list length before summarizing (default: 100)
  • :trace_max_map_size - Maximum map size (keys) before summarizing (default: 100)
  • :trace_preserve_full_keys - Map keys whose string values are never truncated (default: ["system_prompt"])

Example:

config :ptc_runner,
  trace_max_string_size: 128_000,
  trace_max_list_size: 200,
  trace_preserve_full_keys: ["system_prompt", "custom_prompt"]

Summary

Functions

encode(event)

Encodes an event map to a JSON string.

encode!(event)

Encodes an event map to a JSON string, raising on failure.

from_telemetry(event, measurements, metadata, trace_id)

Creates a JSON-encodable event map from telemetry data.

sanitize(value)

Sanitizes a value for safe JSON encoding.

Functions

encode(event)

@spec encode(map()) :: {:ok, String.t()} | {:error, term()}

Encodes an event map to a JSON string.

Returns {:ok, json} on success, {:error, reason} on failure.

encode!(event)

@spec encode!(map()) :: String.t()

Encodes an event map to a JSON string, raising on failure.

from_telemetry(event, measurements, metadata, trace_id)

@spec from_telemetry(list(), map(), map(), String.t()) :: map()

Creates a JSON-encodable event map from telemetry data.

Examples

iex> event = [:ptc_runner, :sub_agent, :run, :start]
iex> measurements = %{system_time: 1000}
iex> metadata = %{agent: %{name: "test"}}
iex> result = PtcRunner.TraceLog.Event.from_telemetry(event, measurements, metadata, "trace-123")
iex> result["event"]
"run.start"
iex> result["trace_id"]
"trace-123"

sanitize(value)

@spec sanitize(term()) :: term()

Sanitizes a value for safe JSON encoding.

Handles:

  • PIDs, refs, ports, functions → inspect/1 string
  • Non-printable binaries → %{"__binary__" => true, "size" => N}
  • Large strings (>64KB by default, configurable) → truncated with preview
  • Large lists (>100 by default, configurable) → "List(N items)"
  • Maps → recursively sanitized
  • Structs → converted to maps and sanitized
  • Tuples → converted to lists and sanitized

Examples

iex> result = PtcRunner.TraceLog.Event.sanitize(self())
iex> String.starts_with?(result, "#PID<")
true

iex> PtcRunner.TraceLog.Event.sanitize(%{a: 1, b: 2})
%{"a" => 1, "b" => 2}

iex> PtcRunner.TraceLog.Event.sanitize({:ok, "result"})
[:ok, "result"]

iex> PtcRunner.TraceLog.Event.sanitize(<<0, 1, 2, 3>>)
%{"__binary__" => true, "size" => 4}