tracing

Documentation

Overview

Package tracing emits a single wavefront-attributed span per proxied request to an OTLP/HTTP collector, without pulling in the OpenTelemetry SDK. It parses the inbound W3C traceparent, hand-marshals the minimal OTLP/JSON payload, and ships it on a bounded background queue so span emission never blocks or fails the request path. With no endpoint configured the exporter is nil and every method is a zero-overhead no-op.

Index

• type Config
• type Exporter
  • func NewExporter(cfg Config) *Exporter
  • func (e *Exporter) Shutdown(ctx context.Context) error
  • func (e *Exporter) StartSpan(name, traceparent string) *Span
• type Span
  • func (s *Span) End()
  • func (s *Span) SetAttr(key, value string)
  • func (s *Span) SetStatus(code StatusCode)
• type StatusCode
• type Traceparent
  • func ParseTraceparent(v string) (Traceparent, bool)

Types

type Config

type Config struct {
	// Endpoint is the collector base URL; "/v1/traces" is appended. Empty
	// disables the exporter.
	Endpoint string
	// ServiceName is reported as the resource service.name; defaults to
	// "wavefront".
	ServiceName string
	// SampleRatio is the probability [0,1] of recording a root span (a request
	// with no inbound traceparent). Continued traces follow the inbound sampled
	// flag instead. Values <=0 or >1 are treated as 1 (always sample).
	SampleRatio float64
}

Config controls the exporter. An empty Endpoint disables tracing entirely.

type Exporter

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

Exporter ships spans to an OTLP/HTTP collector on a background worker.

func NewExporter

func NewExporter(cfg Config) *Exporter

NewExporter builds an exporter and starts its background worker. It returns nil when Endpoint is empty, so tracing is fully disabled with zero overhead.

func (*Exporter) Shutdown

func (e *Exporter) Shutdown(ctx context.Context) error

Shutdown stops the worker and waits for the queue to drain or ctx to expire. Safe on a nil exporter.

func (*Exporter) StartSpan

func (e *Exporter) StartSpan(name, traceparent string) *Span

StartSpan begins a span named name, continuing the inbound W3C traceparent if present and sampled (the inbound span becomes our parent), otherwise starting a fresh root trace subject to the configured sample ratio. It returns nil when the exporter is disabled or the trace is not sampled — callers pass that nil through the request and rely on Span's nil-safe methods.

type Span

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

Span is one in-flight wavefront span. All methods are safe on a nil receiver (the disabled / unsampled path), so callers never need a nil check.

func (*Span) End

func (s *Span) End()

End stamps the end time and enqueues the span for export. No-op on a nil span.

func (*Span) SetAttr

func (s *Span) SetAttr(key, value string)

SetAttr records a span attribute. No-op on a nil span.

func (*Span) SetStatus

func (s *Span) SetStatus(code StatusCode)

SetStatus sets the span status code. No-op on a nil span.

type StatusCode

type StatusCode int

StatusCode mirrors the OTLP span status codes: UNSET (omitted on the wire), OK, and ERROR.

const (
	StatusUnset StatusCode = 0
	StatusOK    StatusCode = 1
	StatusError StatusCode = 2
)

type Traceparent

type Traceparent struct {
	TraceID  [16]byte
	ParentID [8]byte
	Sampled  bool
}

Traceparent is the parsed W3C trace-context `traceparent` header: `version-traceid-spanid-flags`. ParentID is the inbound span's id, which becomes our emitted span's parentSpanId. Sampled is bit 0 of trace-flags.

func ParseTraceparent

func ParseTraceparent(v string) (Traceparent, bool)

ParseTraceparent parses a W3C `traceparent` value. It returns ok=false for any malformed or absent value (wrong field count/length, non-hex, or an all-zero trace/span id, which the spec forbids). A false result means the caller should start a fresh root trace rather than continue an inbound one. The header itself is never modified — wavefront forwards it untouched.