tracing

Documentation

Index

• func Middleware(tr Tracer, headerName string) func(next http.Handler) http.Handler
• func SpanIDFromContext(ctx context.Context) (string, bool)
• func TraceIDFromContext(ctx context.Context) (string, bool)
• type ExporterType
• type OTelConfig
• type OTelTracer
  • func InitOpenTelemetry(ctx context.Context, cfg OTelConfig) (*OTelTracer, func(context.Context) error, error)
  • func (o *OTelTracer) StartSpan(ctx context.Context, name string) (context.Context, func(err error))
• type SimpleTracer
  • func NewSimpleTracer() *SimpleTracer
  • func (t *SimpleTracer) FinishedSpans() []*SpanRecord
  • func (t *SimpleTracer) StartSpan(ctx context.Context, name string) (context.Context, func(err error))
• type SpanRecord
• type Tracer

Functions

func Middleware

func Middleware(tr Tracer, headerName string) func(next http.Handler) http.Handler

Middleware returns an HTTP middleware that ensures a trace id is present on the request context and response header, and starts a span for the request. headerName defaults to "X-Trace-ID" when empty.

func SpanIDFromContext

func SpanIDFromContext(ctx context.Context) (string, bool)

SpanIDFromContext retrieves the span id stored in the context, if any.

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) (string, bool)

TraceIDFromContext retrieves the trace id stored in the context, if any.

Types

type ExporterType

type ExporterType string

ExporterType selects the span exporter used by InitOpenTelemetry.

const (
	// ExporterStdout pretty-prints spans to stdout. Suitable for development.
	ExporterStdout ExporterType = "stdout"
	// ExporterNoop discards all spans. Suitable as a safe default when no
	// tracing backend is configured.
	ExporterNoop ExporterType = "noop"
	// ExporterOTLP sends spans via OTLP/HTTP to any OpenTelemetry-compatible
	// backend (Grafana Tempo, Jaeger, Honeycomb, Datadog, …).
	// Set OTelConfig.Endpoint to the collector URL, e.g. "http://localhost:4318".
	// When Endpoint is empty the OTLP exporter uses the standard environment
	// variable OTEL_EXPORTER_OTLP_ENDPOINT as a fallback.
	ExporterOTLP ExporterType = "otlp"
)

type OTelConfig

type OTelConfig struct {
	// ServiceName is used as the OTel resource service.name attribute.
	ServiceName string
	// Exporter selects the span exporter. Defaults to ExporterNoop when empty.
	Exporter ExporterType
	// Endpoint is the OTLP collector URL, e.g. "http://localhost:4318".
	// Only used when Exporter is ExporterOTLP.
	// When empty the OTLP client falls back to the OTEL_EXPORTER_OTLP_ENDPOINT
	// environment variable.
	Endpoint string
}

OTelConfig holds the configuration for InitOpenTelemetry.

type OTelTracer

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

OTelTracer adapts OpenTelemetry to the local Tracer interface.

func InitOpenTelemetry

func InitOpenTelemetry(ctx context.Context, cfg OTelConfig) (*OTelTracer, func(context.Context) error, error)

InitOpenTelemetry initialises an OpenTelemetry tracer provider. The exporter is selected via cfg.Exporter:

• "stdout" — pretty-prints spans to stdout (development)
• "otlp" — sends spans via OTLP/HTTP to cfg.Endpoint (production)
• "noop" or "" — discards all spans (safe default)

func (*OTelTracer) StartSpan

func (o *OTelTracer) StartSpan(ctx context.Context, name string) (context.Context, func(err error))

StartSpan implements Tracer. It starts an OpenTelemetry span and stores the trace/span ids in the returned context so other parts of the system can access them via TraceIDFromContext / SpanIDFromContext.

type SimpleTracer

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

SimpleTracer is an in-memory tracer useful for tests and as a default. It is intentionally minimal and not a full OpenTelemetry replacement.

func NewSimpleTracer

func NewSimpleTracer() *SimpleTracer

NewSimpleTracer constructs a new SimpleTracer instance.

func (*SimpleTracer) FinishedSpans

func (t *SimpleTracer) FinishedSpans() []*SpanRecord

FinishedSpans returns a copy of finished spans.

func (*SimpleTracer) StartSpan

func (t *SimpleTracer) StartSpan(ctx context.Context, name string) (context.Context, func(err error))

StartSpan starts a new span. If ctx doesn't contain a trace id one is generated. Returns a derived context (containing trace/span ids) and a finish func to call when the span ends.

type SpanRecord

type SpanRecord struct {
	TraceID string
	SpanID  string
	Name    string
	Start   time.Time
	End     time.Time
	Errored bool
}

SpanRecord stores basic span information for tests and inspection.

type Tracer

type Tracer interface {
	StartSpan(ctx context.Context, name string) (context.Context, func(err error))
}

Tracer provides a minimal tracing surface: start a span and receive a finish func.