telemetry

package
v0.31.0 Latest Latest
Warning

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

Go to latest
Published: Jul 16, 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 ParseTraceParent added in v0.28.0

func ParseTraceParent(tp string) (traceID, spanID, flags string, ok bool)

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

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).

func TraceParentWithFlags added in v0.28.0

func TraceParentWithFlags(traceID, spanID, flags string) string

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

func UUIDFromTraceID(traceID string) string

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

func New(dir string, tc TraceContext, agent, workItemID string, start time.Time) *Recorder

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

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.

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).

Directories

Path Synopsis
Package otlp implements ADR 0050 Level 2: best-effort OTLP/HTTP export of the Level 1 telemetry artifacts.
Package otlp implements ADR 0050 Level 2: best-effort OTLP/HTTP export of the Level 1 telemetry artifacts.

Jump to

Keyboard shortcuts

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