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 ParseTraceParent(tp string) (traceID, spanID, flags string, ok bool)
- func TraceIDFromUUID(uuid string) string
- func TraceParent(traceID, spanID string) string
- func TraceParentWithFlags(traceID, spanID, flags string) string
- func UUIDFromTraceID(traceID 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
- type TraceContext
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 ParseTraceParent ¶ added in v0.28.0
ParseTraceParent parses a W3C traceparent header value and returns its trace-id, parent span-id, and trace-flags. ok is false when the value is malformed. Per the W3C spec: version "ff" is forbidden; version "00" has exactly four fields; higher versions are parsed forward-compatibly (the first four fields, ignoring any additions).
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).
func TraceParentWithFlags ¶ added in v0.28.0
TraceParentWithFlags is like TraceParent but carries the given trace-flags (2 lowercase hex chars) so an upstream sampling decision is preserved when continuing an inbound trace. Empty flags default to "01" (sampled).
func UUIDFromTraceID ¶ added in v0.28.0
UUIDFromTraceID converts a 32-hex W3C trace-id into dashed UUID form (8-4-4-4-12) so an adopted inbound trace-id can serve as the run's security trace id. Returns "" unless the input is exactly 32 lowercase hex chars.
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). The trace identity is supplied by the caller so the trace correlates with the run's security trace id, with child processes, and — when continuing an inbound TRACEPARENT — with the parent trace.
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.
type TraceContext ¶ added in v0.28.0
type TraceContext struct {
TraceID string // 32-hex W3C trace-id
RootSpanID string // 16-hex span-id of this run's root span
ParentSpanID string // inbound remote parent span-id; "" = local trace root
Flags string // 2-hex W3C trace-flags; "" defaults to "01"
}
TraceContext is the run's W3C trace identity. When the run continues an inbound TRACEPARENT (issue #2779), ParentSpanID carries the inbound span-id (so the root span joins the parent trace) and Flags carries the inbound trace-flags (so the upstream sampling decision is preserved). For a locally rooted trace both are empty; empty Flags means "01" (sampled).