telemetry

package
v0.46.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package telemetry implements fullsend's distributed tracing (ADR 0050).

Setup configures an OpenTelemetry TracerProvider with two exporters:

  • fileExporter (synchronous) writes every span as OTLP JSON to run-telemetry.jsonl.
  • otlptracehttp (batched) exports to a remote backend when an OTEL_EXPORTER_OTLP_*ENDPOINT is configured.

When neither exporter can be created, Setup returns a noop tracer so the run is never affected.

Index

Constants

View Source
const ContentCaptureEnvVar = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"

ContentCaptureEnvVar is the Level 3 content-capture opt-in named by ADR 0050. The variable name and its value vocabulary come from the OpenTelemetry GenAI instrumentation convention (documented by the opentelemetry-python-contrib GenAI instrumentations); the pinned semantic-conventions v1.37.0 release does not define this variable. Fullsend's runner is the GenAI instrumentation that reads it — it is never passed to the agent runtime, whose own content-logging variables (OTEL_LOG_*) fullsend never sets.

View Source
const FlushTimeout = 5 * time.Second

FlushTimeout is the budget for tp.Shutdown to flush pending spans at CLI exit.

View Source
const MaxSpanAttrValueLen = 8192

MaxSpanAttrValueLen bounds span attribute values recorded through this provider in metadata-only mode. When the Level 3 content gate is on, spanLimits lifts the provider-wide cap (a capped cut would corrupt the content JSON mid-value), so free-text values that relied on this cap are bounded at their call sites instead (internal/cli boundedStringAttr). The SDK applies the limit to span attributes only — event messages are bounded at their call site — counting characters, not bytes (a multibyte value can reach four bytes per character on the wire), and it repairs invalid UTF-8 only when it truncates: values at or under the limit pass through unrepaired, so free-text attribute values are repaired at their call sites (internal/cli stringAttr). Both properties are pinned by TestAttrLimit_SDKBehaviorCanary. The exception-event bound in internal/cli (maxSpanEventMsgLen, bytes) is defined from this constant so the shared numeric default cannot drift, each side applying it in its own unit. It applies only when the SDK took no operator override — the first non-empty of OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT and OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT decides alone, and a parseable value there, including -1 (unlimited), is honored as-is.

View Source
const TelemetryFile = "run-telemetry.jsonl"

TelemetryFile is the artifact name written to the output dir.

Variables

This section is empty.

Functions

func BuildResource added in v0.43.0

func BuildResource(serviceVersion string) *resource.Resource

BuildResource returns the fullsend OTLP resource (service.name, version, plus OTEL_RESOURCE_ATTRIBUTES). Shared by agent Setup and score export so backends that group by resource keep both on the same service identity.

func ContentCaptureEnabled added in v0.38.0

func ContentCaptureEnabled() bool

ContentCaptureEnabled reports whether Level 3 content capture is on.

Fullsend records content on span attributes only, so the affirmative values are the ones whose intent span recording can honor: "true" (legacy boolean form), "span_only", and "span_and_event". "event_only" is off — fullsend implements no event-based capture, and recording on spans would contradict the operator's "only". "NO_CONTENT", "false", unset, and anything unrecognized are off: telemetry never fails a run (ADR 0050), so an unexpected value disables capture rather than erroring.

func FreeTextAttrValueLenLimit added in v0.43.0

func FreeTextAttrValueLenLimit() int

FreeTextAttrValueLenLimit is the call-site bound for free-text values the SDK does not truncate (event attributes) or that must stay intact when Level 3 content capture lifts SpanLimits. Honors an explicit operator OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT / OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT (including -1 = unlimited); otherwise defaults to MaxSpanAttrValueLen. Independent of ContentCaptureEnabled — that gate only lifts the provider cap for content JSON span attrs.

func InstallOTELRedactingLogger added in v0.46.0

func InstallOTELRedactingLogger()

InstallOTELRedactingLogger configures the global OpenTelemetry logger with a redacting sink that emits error messages without keysAndValues context. Safe for concurrent use and runs at most once per process.

func NewOTLPExporter added in v0.43.0

func NewOTLPExporter(ctx context.Context) (sdktrace.SpanExporter, error)

NewOTLPExporter builds the HTTP OTLP span exporter from OTEL_* env (same path Setup uses for agent traces). Callers must validate endpoints first with ValidateOTLPEndpoints when they want fail-closed setup.

func NewOTLPExporterBounded added in v0.43.0

func NewOTLPExporterBounded(ctx context.Context, maxElapsed time.Duration) (sdktrace.SpanExporter, error)

NewOTLPExporterBounded is NewOTLPExporter with MaxElapsedTime set so post-hoc exporters (eval scores) cannot retry forever on a flaky collector.

func NewRedactingLogger added in v0.46.0

func NewRedactingLogger(w io.Writer) logr.Logger

NewRedactingLogger returns a logr.Logger backed by a redactingLogSink writing to w.

func OTLPEnabled added in v0.43.0

func OTLPEnabled() bool

OTLPEnabled reports whether an OTLP traces endpoint is configured via OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT.

func Setup added in v0.32.0

func Setup(dir string, serviceVersion string) (trace.Tracer, func(context.Context))

Setup creates a TracerProvider with file and (optionally) OTLP exporters. On any failure it returns a noop tracer and an empty cleanup func so the run is never affected. The cleanup func shuts down the provider (flushing the OTLP batch processor) and closes the file; it should be called with a context that has enough budget for the OTLP flush (typically context.Background() with a 5s timeout).

func SpanLimits added in v0.43.0

func SpanLimits() sdktrace.SpanLimits

SpanLimits returns the SDK span limits used by Setup (default 8KiB attribute value length unless OTEL_*_ATTRIBUTE_VALUE_LENGTH_LIMIT is set, or unlimited when Level 3 content capture lifts the provider cap).

func Traceparent added in v0.32.0

func Traceparent(sc trace.SpanContext) string

Traceparent returns the W3C traceparent header value for a span context. Returns "" for invalid (zero) span contexts so callers can omit the header rather than emitting an all-zero value that W3C forbids.

func TraceparentWithFlags added in v0.32.0

func TraceparentWithFlags(sc trace.SpanContext, flags trace.TraceFlags) string

TraceparentWithFlags formats a W3C traceparent using sc's trace/span IDs but with explicit flags. Use this to propagate a sampling decision that differs from the local span's (e.g. preserving an upstream unsampled bit that AlwaysSample overrode locally).

func ValidateOTLPEndpoints added in v0.43.0

func ValidateOTLPEndpoints() error

ValidateOTLPEndpoints checks all configured OTEL endpoint env vars (OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) that the SDK will parse for traces export.

func ValidateOTLPHeaders added in v0.46.0

func ValidateOTLPHeaders() error

ValidateOTLPHeaders checks the OTEL header env vars (OTEL_EXPORTER_OTLP_HEADERS and OTEL_EXPORTER_OTLP_TRACES_HEADERS) for syntax errors like missing '=', invalid RFC 7230 token characters in keys, or invalid URL-escapes in values.

Types

This section is empty.

Jump to

Keyboard shortcuts

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