tracing

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 20, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package tracing provides a reusable, library-friendly wrapper around the OpenTelemetry Go SDK for distributed tracing.

It handles the boilerplate of constructing a TracerProvider with a configurable exporter (OTLP gRPC, OTLP HTTP, stdout, or no-op), a Resource describing the service, a sampler, and W3C Trace Context propagation — while leaving the application in full control of when to start, flush, and shut down the pipeline.

The Jaeger native exporter is deprecated upstream; Jaeger accepts OTLP directly (port 4317 for gRPC, 4318 for HTTP), so this package only ships OTLP exporters.

Quick start

shutdown, err := tracing.Init(ctx, tracing.Config{
    ServiceName:    "my-service",
    ServiceVersion: "1.0.0",
    Exporter:       tracing.ExporterOTLPGRPC,
    OTLPEndpoint:   "localhost:4317",
    SampleRatio:    0.1,
})
if err != nil {
    log.Fatal(err)
}
defer shutdown(ctx)

// Use the global tracer.
ctx, span := tracing.Start(ctx, "operation-name")
defer span.End()

Library usage

Instead of using the global provider, you can create a standalone Provider and pass it explicitly:

tp, shutdown, err := tracing.NewProvider(ctx, config)
defer shutdown(ctx)
tracer := tp.Tracer("my-library")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContextWithSpan

func ContextWithSpan(ctx context.Context, span trace.Span) context.Context

ContextWithSpan returns a new context with the given span set.

func Extract

Extract extracts the trace context from the carrier (e.g. HTTP headers).

func Init

func Init(ctx context.Context, cfg Config) (func(context.Context) error, error)

Init creates a tracing Provider from the given Config, registers it globally (if SetGlobal is true), and returns a shutdown function.

The returned shutdown function flushes pending spans and releases resources. It should be called on application exit.

func Inject

func Inject(ctx context.Context, carrier propagation.TextMapCarrier)

Inject injects the current trace context into the carrier (e.g. HTTP headers).

func IsTracingEnabled

func IsTracingEnabled() bool

IsTracingEnabled returns true if a real (non-noop) TracerProvider is registered globally.

func SpanFromContext

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext returns the active span from the context, or a no-op span if no span is active.

func Start

func Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

Start starts a new span using the global TracerProvider. It returns the context with the span and the span itself.

func myHandler(ctx context.Context) {
    ctx, span := tracing.Start(ctx, "myHandler")
    defer span.End()
    ...
}

Types

type Config

type Config struct {
	// ServiceName identifies the emitting service. Required.
	ServiceName string
	// ServiceVersion is the service version (e.g. "1.0.0"). Optional.
	ServiceVersion string
	// ServiceNamespace groups services under a namespace. Optional.
	ServiceNamespace string
	// Environment is the deployment environment (e.g. "production", "staging"). Optional.
	Environment string
	// Exporter selects the exporter kind. Default: ExporterNoop.
	Exporter ExporterKind
	// OTLPEndpoint is the OTLP collector address (e.g. "localhost:4317"). Used
	// for OTLP gRPC and HTTP exporters.
	OTLPEndpoint string
	// OTLPInsecure disables TLS for OTLP connections. Default: true for
	// localhost endpoints, false otherwise.
	OTLPInsecure *bool
	// OTLPHeaders are additional headers sent with OTLP requests.
	OTLPHeaders map[string]string
	// SampleRatio is the probability [0.0, 1.0] of sampling a trace.
	// 1.0 = sample all, 0.0 = sample none. Default: 1.0 (always sample).
	SampleRatio float64
	// SpanBatchTimeout is the maximum delay before a batch of spans is exported.
	// Default: 5s.
	SpanBatchTimeout time.Duration
	// SpanMaxQueueSize is the maximum number of spans buffered before export.
	// Default: 2048.
	SpanMaxQueueSize int
	// SpanMaxExportBatchSize is the maximum number of spans in a single export batch.
	// Default: 512.
	SpanMaxExportBatchSize int
	// ResourceAttributes are additional key-value attributes attached to the
	// resource (e.g. host.name, deployment.environment).
	ResourceAttributes map[string]string
	// SetGlobal registers the provider as the global TracerProvider. Default: true.
	SetGlobal bool
}

Config configures the tracing provider.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type ExporterKind

type ExporterKind string

ExporterKind selects which trace exporter to use.

const (
	// ExporterOTLPGRPC sends spans via OTLP over gRPC (default Jaeger/Collector port 4317).
	ExporterOTLPGRPC ExporterKind = "otlp_grpc"
	// ExporterOTLPHTTP sends spans via OTLP over HTTP (default port 4318).
	ExporterOTLPHTTP ExporterKind = "otlp_http"
	// ExporterStdout writes spans to stdout (useful for development).
	ExporterStdout ExporterKind = "stdout"
	// ExporterNoop discards all spans (useful for testing or disabled tracing).
	ExporterNoop ExporterKind = "noop"
)

type Provider

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

Provider wraps an sdktrace.TracerProvider with its shutdown function.

func NewProvider

func NewProvider(ctx context.Context, cfg Config) (*Provider, error)

NewProvider creates a tracing Provider without setting globals.

func (*Provider) Resource

func (p *Provider) Resource() *resource.Resource

Resource returns the OTel Resource associated with this provider.

func (*Provider) Shutdown

func (p *Provider) Shutdown(ctx context.Context) error

Shutdown flushes and shuts down the provider. It is safe to call multiple times and from concurrent goroutines.

func (*Provider) Tracer

func (p *Provider) Tracer() trace.Tracer

Tracer returns a tracer with the configured service name.

func (*Provider) TracerProvider

func (p *Provider) TracerProvider() *sdktrace.TracerProvider

TracerProvider returns the underlying SDK TracerProvider.

Jump to

Keyboard shortcuts

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