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 ¶
- func ContextWithSpan(ctx context.Context, span trace.Span) context.Context
- func Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
- func Init(ctx context.Context, cfg Config) (func(context.Context) error, error)
- func Inject(ctx context.Context, carrier propagation.TextMapCarrier)
- func IsTracingEnabled() bool
- func SpanFromContext(ctx context.Context) trace.Span
- func Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- type Config
- type ExporterKind
- type Provider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextWithSpan ¶
ContextWithSpan returns a new context with the given span set.
func Extract ¶
func Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
Extract extracts the trace context from the carrier (e.g. HTTP headers).
func Init ¶
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 ¶
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 ¶
NewProvider creates a tracing Provider without setting globals.
func (*Provider) Shutdown ¶
Shutdown flushes and shuts down the provider. It is safe to call multiple times and from concurrent goroutines.
func (*Provider) TracerProvider ¶
func (p *Provider) TracerProvider() *sdktrace.TracerProvider
TracerProvider returns the underlying SDK TracerProvider.