observability

Documentation

Overview

Package observability — OpenTelemetry instrumentation seam for the dispatch surface (ADR-014 carry-over T1, design from the 2026-04-26 multi-CLI fan-out).

One Observer per `clawtool` process. Disabled = pointer-cheap no-op: StartSpan returns the input ctx and a no-op end func, RecordError is a void call. Enabled hooks an OTLP/HTTP exporter (Langfuse- compatible when the operator wires its public/secret key) into the global tracer provider; Supervisor.Send and Transport.startStreamingExec open spans on top.

Per ADR-007 we wrap go.opentelemetry.io/otel and friends; we do not invent trace context propagation, sampler logic, or exporter transport. Adding a new exporter (Datadog, Honeycomb) is a one-file extension; the Observer surface stays stable.

Index

• type EndFunc
• type Observer
  • func New() *Observer
  • func (o *Observer) Enabled() bool
  • func (o *Observer) Init(ctx context.Context, cfg config.ObservabilityConfig) error
  • func (o *Observer) RecordError(ctx context.Context, err error)
  • func (o *Observer) SetAttributes(ctx context.Context, attrs ...attribute.KeyValue)
  • func (o *Observer) Shutdown(ctx context.Context) error
  • func (o *Observer) StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, EndFunc)

Types

type EndFunc

type EndFunc func()

EndFunc closes a span. Returned by StartSpan; safe to call on a disabled Observer (no-op).

type Observer

type Observer struct {
	// contains filtered or unexported fields
}

Observer is the single seam every dispatch goes through. The zero value is a usable no-op; Init upgrades it to a live tracer when the operator's config opts in.

func New

func New() *Observer

New returns a zero-value Observer. Equivalent to a disabled observer; safe to use immediately.

func (*Observer) Enabled

func (o *Observer) Enabled() bool

Enabled reports whether the observer is wired to a live exporter. Useful for tests and for skipping expensive attribute construction behind a cheap check.

func (*Observer) Init

func (o *Observer) Init(ctx context.Context, cfg config.ObservabilityConfig) error

Init wires the OTLP/HTTP exporter and tracer provider when cfg.Enabled is true. When disabled, returns nil and leaves the observer in no-op mode.

Init is idempotent within a single process: a second call is a no-op. To re-configure call Shutdown first.

func (*Observer) RecordError

func (o *Observer) RecordError(ctx context.Context, err error)

RecordError attaches an error to the span carried in ctx and marks the span's status. No-op on a disabled observer or when ctx carries no active span.

func (*Observer) SetAttributes

func (o *Observer) SetAttributes(ctx context.Context, attrs ...attribute.KeyValue)

SetAttributes adds attributes to the active span in ctx. No-op when disabled or when ctx has no recording span.

func (*Observer) Shutdown

func (o *Observer) Shutdown(ctx context.Context) error

Shutdown flushes pending spans and tears down the tracer provider. Idempotent. Always safe to call (no-op when disabled).

func (*Observer) StartSpan

func (o *Observer) StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, EndFunc)

StartSpan opens a span named `name`. Returns the derived context and an end func. On a disabled observer, returns the input ctx and a no-op end. Caller convention: `ctx, end := obs.StartSpan(ctx, "agents.Send"); defer end()`.