Documentation
¶
Overview ¶
Package telemetry implements fullsend's Level 1 distributed tracing: a zero-config, metadata-only local baseline (per ADR 0050). Every run writes a crash-safe NDJSON event stream (run-telemetry.jsonl) and an aggregated summary (run-summary.json) to the run output directory.
The package is deliberately dependency-free and safe by construction: a nil *Recorder is valid, every method is a no-op when the recorder is nil or disabled, and no method returns an error. Any failure in the telemetry path disables the recorder rather than affecting the run — graceful degradation is a hard requirement.
Index ¶
- Constants
- func NewSpanID() string
- func TraceIDFromUUID(uuid string) string
- func TraceParent(traceID, spanID string) string
- type Recorder
- func (r *Recorder) EndSpan(spanID, status string, attrs map[string]any)
- func (r *Recorder) Finalize(exitCode int)
- func (r *Recorder) SetMetrics(m RunMetrics)
- func (r *Recorder) SetModel(model string)
- func (r *Recorder) StartSpan(name, parentID string, attrs map[string]any) string
- func (r *Recorder) TraceParent() string
- type RunMetrics
Constants ¶
const ( TelemetryFile = "run-telemetry.jsonl" SummaryFile = "run-summary.json" )
TelemetryFile and SummaryFile are the artifact names written to the output dir.
const SchemaVersion = 1
SchemaVersion is the bespoke fullsend telemetry schema version, present on every event line and in the summary. Bump on incompatible schema changes.
Variables ¶
This section is empty.
Functions ¶
func NewSpanID ¶
func NewSpanID() string
NewSpanID returns a random 16-hex-character (8-byte) W3C span-id.
func TraceIDFromUUID ¶
TraceIDFromUUID converts a dashed UUID (e.g. the output of security.GenerateTraceID) into a 32-hex-character W3C trace-id by removing the dashes. This deliberately reuses the per-run security trace id so a single id correlates security findings, telemetry, and child processes.
W3C forbids an all-zero trace-id; if the input is malformed or strips to all zeros, a fresh random trace-id is returned instead so callers never emit an invalid value.
func TraceParent ¶
TraceParent returns a W3C traceparent header value of the form "00-<32-hex trace-id>-<16-hex span-id>-01" (version 00, sampled flag 01).
Types ¶
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder writes crash-safe NDJSON telemetry and a final summary. The zero value is not usable; obtain one from New. A nil *Recorder is a valid no-op.
func New ¶
New opens <dir>/run-telemetry.jsonl for append and emits the root "run" span (backdated to start). traceID is a 32-hex W3C trace-id and rootSpanID a 16-hex span-id; both are supplied by the caller so the trace correlates with the run's security trace id and with child processes.
New never returns an error: if the file cannot be opened it returns a disabled (no-op) recorder so the run is never affected.
func (*Recorder) EndSpan ¶
EndSpan emits a span_end for spanID, records its duration as a summary step, and defaults an empty status to "ok". No-op for nil/disabled/empty spanID.
func (*Recorder) Finalize ¶
Finalize emits the root span_end, writes run-summary.json atomically, and closes the telemetry file. It is idempotent and a no-op for nil/disabled.
func (*Recorder) SetMetrics ¶
func (r *Recorder) SetMetrics(m RunMetrics)
SetMetrics records aggregate run metrics to include in run-summary.json. Safe to call repeatedly (last wins); no-op for nil/disabled recorders.
func (*Recorder) SetModel ¶
SetModel records the resolved model name to include in run-summary.json. Safe to call repeatedly (last wins); no-op for nil/disabled recorders.
func (*Recorder) StartSpan ¶
StartSpan emits a span_start and returns its span id. An empty parentID makes the span a child of the root span. Returns "" if the recorder is nil/disabled.
func (*Recorder) TraceParent ¶
TraceParent returns the W3C traceparent for child-process propagation, or "" if the recorder is nil/disabled.
type RunMetrics ¶
type RunMetrics struct {
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
CacheCreationInputTokens int `json:"cache_creation_input_tokens"`
CacheReadInputTokens int `json:"cache_read_input_tokens"`
TotalCostUSD float64 `json:"total_cost_usd"`
NumTurns int `json:"num_turns"`
ToolCalls int `json:"tool_calls"`
}
RunMetrics holds aggregate behavioral metrics for the run, surfaced into the summary via SetMetrics. Sourced from fullsend's existing per-run metrics (no new accounting). Omitted from the summary when never set.