telemetry

package
v0.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 2, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

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

View Source
const (
	TelemetryFile = "run-telemetry.jsonl"
	SummaryFile   = "run-summary.json"
)

TelemetryFile and SummaryFile are the artifact names written to the output dir.

View Source
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

func TraceIDFromUUID(uuid string) string

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

func TraceParent(traceID, spanID string) string

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

func New(dir, traceID, rootSpanID, agent, workItemID string, start time.Time) *Recorder

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

func (r *Recorder) EndSpan(spanID, status string, attrs map[string]any)

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

func (r *Recorder) Finalize(exitCode int)

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

func (r *Recorder) SetModel(model string)

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

func (r *Recorder) StartSpan(name, parentID string, attrs map[string]any) string

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

func (r *Recorder) TraceParent() string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL