trace

Documentation

Overview

Package trace provides W3C traceparent propagation and OpenTelemetry tracer lifecycle management for gofly services.

Package trace provides W3C traceparent propagation and OpenTelemetry tracer lifecycle management for gofly services.

Package trace provides W3C trace context propagation for gofly services. It supports traceparent parsing, context injection/extraction, and pluggable sampling strategies.

Index

• Constants
• func NewContext(ctx context.Context, sc SpanContext) context.Context
• func ShouldSample(sampler Sampler, traceID string) bool
• func ToOTel(sc SpanContext) (oteltrace.SpanContext, bool)
• func TraceParent(sc SpanContext) string
• type Agent
  • func StartAgent(ctx context.Context, conf AgentConfig, exporters ...sdktrace.SpanExporter) (*Agent, error)
  • func (a *Agent) Shutdown(ctx context.Context) error
• type AgentConfig
• type Sampler
  • func AlwaysSampler() Sampler
  • func NeverSampler() Sampler
  • func ParentBasedSampler(root Sampler) Sampler
  • func RatioSampler(ratio float64) Sampler
• type SamplerFunc
  • func (fn SamplerFunc) Sample(traceID string, parentSampled bool, hasParent bool) bool
• type SpanContext
  • func FromContext(ctx context.Context) (SpanContext, bool)
  • func FromOTel(sc oteltrace.SpanContext) (SpanContext, bool)
  • func ParseTraceParent(value string) (SpanContext, bool)
  • func Start(ctx context.Context, parent string) (context.Context, SpanContext)
  • func StartWithSampler(ctx context.Context, parent string, sampler Sampler) (context.Context, SpanContext)

Constants

const (
	// TraceParentHeader is the HTTP header name for W3C traceparent.
	TraceParentHeader = "traceparent"
	// TraceIDKey is the structured-log key for the trace ID.
	TraceIDKey = "trace_id"
	// SpanIDKey is the structured-log key for the span ID.
	SpanIDKey = "span_id"
	// SampledKey is the structured-log key for the sampling decision.
	SampledKey = "trace_sampled"
)

W3C trace context header and context key constants.

Functions

func NewContext

func NewContext(ctx context.Context, sc SpanContext) context.Context

NewContext returns a context carrying the given SpanContext.

func ShouldSample

func ShouldSample(sampler Sampler, traceID string) bool

ShouldSample evaluates the sampler for the given trace ID. If sampler is nil, it defaults to true. If traceID is empty, a random trace ID is generated for the sampling decision.

func ToOTel

func ToOTel(sc SpanContext) (oteltrace.SpanContext, bool)

ToOTel converts a gofly SpanContext to an OpenTelemetry SpanContext.

func TraceParent

func TraceParent(sc SpanContext) string

TraceParent formats a SpanContext as a W3C traceparent string.

Types

type Agent

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

Agent wraps an OpenTelemetry TracerProvider.

func StartAgent

func StartAgent(ctx context.Context, conf AgentConfig, exporters ...sdktrace.SpanExporter) (*Agent, error)

StartAgent initialises and starts the trace agent with the given config and optional additional exporters.

func (*Agent) Shutdown

func (a *Agent) Shutdown(ctx context.Context) error

type AgentConfig

type AgentConfig struct {
	Enabled     bool                `json:"enabled"`
	ServiceName string              `json:"serviceName,omitempty"`
	SampleRatio float64             `json:"sampleRatio,omitempty"`
	OTLP        exporter.OTLPConfig `json:"otlp,omitempty"`
}

AgentConfig controls the OpenTelemetry trace agent.

type Sampler

type Sampler interface {
	Sample(traceID string, parentSampled bool, hasParent bool) bool
}

Sampler decides whether a trace should be sampled.

func AlwaysSampler

func AlwaysSampler() Sampler

AlwaysSampler returns a sampler that always samples.

func NeverSampler

func NeverSampler() Sampler

NeverSampler returns a sampler that never samples.

func ParentBasedSampler

func ParentBasedSampler(root Sampler) Sampler

ParentBasedSampler delegates to root sampler when there is no parent. When a parent exists, the parent's sampling decision is preserved.

func RatioSampler

func RatioSampler(ratio float64) Sampler

RatioSampler returns a sampler that samples probabilistically based on traceID. ratio must be in the range [0,1]; values outside the range are clamped to AlwaysSampler or NeverSampler.

type SamplerFunc

type SamplerFunc func(traceID string, parentSampled bool, hasParent bool) bool

SamplerFunc is an adapter to allow ordinary functions as Samplers.

func (SamplerFunc) Sample

func (fn SamplerFunc) Sample(traceID string, parentSampled bool, hasParent bool) bool

Sample evaluates the sampling decision.

type SpanContext

type SpanContext struct {
	TraceID string
	SpanID  string
	Sampled bool
}

SpanContext carries trace and span identifiers for a single request.

func FromContext

func FromContext(ctx context.Context) (SpanContext, bool)

FromContext extracts the SpanContext from a context.

func FromOTel

func FromOTel(sc oteltrace.SpanContext) (SpanContext, bool)

FromOTel converts an OpenTelemetry SpanContext to a gofly SpanContext.

func ParseTraceParent

func ParseTraceParent(value string) (SpanContext, bool)

ParseTraceParent parses a W3C traceparent string into a SpanContext. It returns false if the value is malformed or contains all-zero IDs.

func Start

func Start(ctx context.Context, parent string) (context.Context, SpanContext)

Start creates a new child span context from the parent traceparent string. If parent is invalid or empty, a new root trace is started.

func StartWithSampler

func StartWithSampler(ctx context.Context, parent string, sampler Sampler) (context.Context, SpanContext)

StartWithSampler creates a new child span context using the given sampler. If parent is invalid or empty, a new root trace is started.