provider

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2025 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package provider implements the factory and builder patterns for creating and configuring OpenTelemetry tracer providers. It encapsulates the complexity of resource creation, exporter setup, batch processing, and sampler configuration.

The package provides a clean, modular API for constructing tracer providers with sensible defaults and extensible configuration options.

Key components: - InitializationError: Custom error type for initialization failures - createResource: Creates or returns an OpenTelemetry resource for service identification - createExporter: Factory method for OTLP exporters (HTTP or gRPC) - createBatchProcessor: Configures batch span processor with performance tuning options - newProvider: Orchestrates creation of the tracer provider from components - createSampler: Strategy pattern for sampler selection based on config

Usage example: 

ctx := context.Background()
cfg := NewProviderConfig("my-service", "v1.0.0")
provider, err := newProvider(ctx, cfg)
if err != nil {
    log.Fatal(err)
}

Design patterns: - Factory Method: createExporter, createResource, createBatchProcessor - Builder: ProviderConfig fluent API - Strategy: createSampler selects sampling strategy

This package follows SOLID principles and Go best practices for maintainable, testable, and extensible code.

Package provider provides OpenTelemetry tracer provider configuration and initialization. This file contains the core provider setup that configures exporters, sampling, resource identification, and batch processing for the entire tracing system.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewDefaultProvider 

func NewDefaultProvider(ctx context.Context, serviceName string, serviceVersion ...string) (*sdktrace.TracerProvider, error)

NewDefaultProvider creates a tracer provider with default settings and sets it as the global provider. This is a convenience function for quick setup in development or simple applications. It creates a provider with opinionated defaults:

  • HTTP OTLP exporter to localhost:4318 (insecure)
  • Probabilistic sampling at the default rate (typically 20%)
  • Standard batch processing settings
  • Automatic resource detection for service identification

The provider is set as the global OpenTelemetry provider (only once per application). For production use or when you need custom configuration, use NewProvider with NewProviderConfig.

Note: This is the function most users will start with. It's designed to "just work" for local development and testing scenarios.

Example: 

provider, err := tracer.NewDefaultProvider(ctx, "my-service", "v1.0.0")
if err != nil {
    log.Fatal(err)
}
defer provider.Shutdown(ctx)

func NewProvider 

func NewProvider(ctx context.Context, cfg *ProviderConfig) (*sdktrace.TracerProvider, error)

NewProvider creates and configures a new TracerProvider using the provided configuration, then sets it as the global OpenTelemetry provider (only once per application lifecycle). This is the recommended way to initialize tracing when you need custom configuration.

The function ensures that the global provider is set only once, even if called multiple times. This prevents conflicts and ensures consistent tracing behavior across the application.

Example: 

config := tracer.NewProviderConfig("payment-service", "v1.2.3").
    WithOTLPExporter("https://api.honeycomb.io", "http", false).
    WithSampling("probabilistic", 0.05)

provider, err := tracer.NewProvider(ctx, config)
if err != nil {
    log.Fatal(err)
}
defer provider.Shutdown(ctx)

func ShutdownTracerProvider 

func ShutdownTracerProvider(ctx context.Context, tp *sdktrace.TracerProvider) error

ShutdownTracerProvider gracefully shuts down the tracer provider, ensuring all pending spans are exported before the application terminates. This function should be called during application shutdown, typically with a context that has a reasonable timeout.

The shutdown process:

  1. Stops accepting new spans
  2. Exports all remaining spans in the queue
  3. Closes the exporter connection
  4. Releases any resources held by the provider

Example: 

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := tracer.ShutdownTracerProvider(ctx, provider); err != nil {
    log.Printf("Error during tracer shutdown: %v", err)
}

Types

type AlwaysOffSamplerFactory 

type AlwaysOffSamplerFactory struct{}

AlwaysOffSamplerFactory creates always-off samplers

func (*AlwaysOffSamplerFactory) CreateSampler 

func (f *AlwaysOffSamplerFactory) CreateSampler(cfg *config.Config) sdktrace.Sampler

type AlwaysOnSamplerFactory 

type AlwaysOnSamplerFactory struct{}

AlwaysOnSamplerFactory creates always-on samplers

func (*AlwaysOnSamplerFactory) CreateSampler 

func (f *AlwaysOnSamplerFactory) CreateSampler(cfg *config.Config) sdktrace.Sampler

type InitializationError 

type InitializationError struct {
	Component string
	Cause     error
}

InitializationError represents an error during provider initialization

func (*InitializationError) Error 

func (e *InitializationError) Error() string

Error implements the error interface

func (*InitializationError) Unwrap 

func (e *InitializationError) Unwrap() error

Unwrap returns the underlying error

type ProbabilisticSamplerFactory 

type ProbabilisticSamplerFactory struct{}

ProbabilisticSamplerFactory creates probabilistic samplers

func (*ProbabilisticSamplerFactory) CreateSampler 

func (f *ProbabilisticSamplerFactory) CreateSampler(cfg *config.Config) sdktrace.Sampler

type ProviderConfig 

type ProviderConfig struct {
	// Config contains the core tracing configuration including service identification,
	// exporter settings, and sampling strategy.
	Config *config.Config

	// Resource provides custom resource attributes for service identification.
	// If nil, a default resource will be created using service name, version,
	// environment, hostname, and instance ID from Config.
	Resource *sdkresource.Resource

	// BatchTimeout is the maximum time the batch processor waits before
	// exporting spans. Lower values reduce latency but may increase overhead.
	// Default: 5 seconds.
	BatchTimeout time.Duration

	// ExportTimeout is the maximum time allowed for exporting a batch of spans.
	// Exports exceeding this timeout will be cancelled. Default: 30 seconds.
	ExportTimeout time.Duration

	// MaxExportBatchSize is the maximum number of spans to export in a single batch.
	// Larger batches improve throughput but use more memory. Default: 512.
	MaxExportBatchSize int

	// MaxQueueSize is the maximum number of spans that can be queued for export.
	// When the queue is full, new spans will be dropped. Default: 2048.
	MaxQueueSize int
}

ProviderConfig holds comprehensive configuration for creating a TracerProvider. It combines basic tracing configuration with advanced options for batch processing, resource identification, and performance tuning. This allows fine-grained control over the tracing pipeline behavior.

The configuration supports fluent method chaining for ease of use: 

config := tracer.NewProviderConfig("my-service", "v1.0.0").
    WithOTLPExporter("localhost:4317", "grpc", true).
    WithSampling("probabilistic", 0.1).
    WithBatchOptions(5*time.Second, 30*time.Second, 512, 2048)

func NewProviderConfig 

func NewProviderConfig(serviceName, serviceVersion string) *ProviderConfig

NewProviderConfig creates a new ProviderConfig with sensible defaults for advanced configuration. It initializes the configuration with default batch processing settings and creates a base Config using the provided service name and version. The returned config supports fluent method chaining for customization.

Default settings:

  • BatchTimeout: 5 seconds
  • ExportTimeout: 30 seconds
  • MaxExportBatchSize: 512 spans
  • MaxQueueSize: 2048 spans
  • OTLP HTTP exporter pointing to localhost:4318
  • Probabilistic sampling at 20%

Example: 

config := tracer.NewProviderConfig("user-service", "v2.1.0")
provider, err := tracer.NewProvider(ctx, config)

func (*ProviderConfig) WithBatchOptions 

func (pc *ProviderConfig) WithBatchOptions(batchTimeout, exportTimeout time.Duration, maxExportBatchSize, maxQueueSize int) *ProviderConfig

WithBatchOptions configures the batch processor settings for span export optimization. These settings control how spans are batched and exported, affecting both performance and resource usage. Tune these values based on your application's traffic patterns and latency requirements.

Parameters:

  • batchTimeout: Maximum time to wait before exporting (lower = less latency, higher = better throughput)
  • exportTimeout: Maximum time allowed for export operations (prevents hanging exports)
  • maxExportBatchSize: Maximum spans per batch (higher = better throughput, more memory usage)
  • maxQueueSize: Maximum queued spans before dropping (higher = more memory, less data loss)

Example: 

// Low-latency configuration
config.WithBatchOptions(1*time.Second, 10*time.Second, 256, 1024)

// High-throughput configuration
config.WithBatchOptions(10*time.Second, 60*time.Second, 1024, 4096)

func (*ProviderConfig) WithOTLPExporter 

func (pc *ProviderConfig) WithOTLPExporter(endpoint, protocol string, insecure bool) *ProviderConfig

WithOTLPExporter configures the OTLP exporter settings for trace export. This method allows you to specify the endpoint, protocol, and security settings for sending traces to an OTLP-compatible backend.

Parameters:

  • endpoint: The URL or address of the OTLP collector (e.g., "localhost:4317", "https://api.honeycomb.io")
  • protocol: Either "grpc" for gRPC transport or "http" for HTTP transport
  • insecure: true to disable TLS (for development), false to use TLS (for production)

Example: 

config.WithOTLPExporter("https://api.honeycomb.io", "http", false)
config.WithOTLPExporter("localhost:4317", "grpc", true)  // Development

func (*ProviderConfig) WithResource 

func (pc *ProviderConfig) WithResource(resource *sdkresource.Resource) *ProviderConfig

WithResource sets a custom OpenTelemetry resource for service identification. Resources contain attributes that identify the service, version, environment, and other metadata. If not provided, a default resource will be created automatically using the service name, version, and other attributes from the Config.

Example: 

resource, _ := resource.New(ctx,
    resource.WithAttributes(
        semconv.ServiceName("payment-service"),
        semconv.ServiceVersion("v1.2.3"),
        semconv.DeploymentEnvironment("production"),
        attribute.String("region", "us-west-2"),
    ),
)
config.WithResource(resource)

func (*ProviderConfig) WithSampling 

func (pc *ProviderConfig) WithSampling(samplingType config.SamplingType, ratio float64) *ProviderConfig

WithSampling configures the sampling strategy and ratio for trace collection. Sampling controls what percentage of traces are collected and exported, which is crucial for managing overhead in high-traffic applications.

Parameters:

  • samplingType: SamplingProbabilistic (ratio-based), SamplingAlwaysOn (100%), or SamplingAlwaysOff (0%)
  • ratio: For probabilistic sampling, the ratio of traces to sample (0.0 to 1.0) Ignored for "always_on" and "always_off" strategies

Example: 

config.WithSampling(config.SamplingProbabilistic, 0.01)  // 1% sampling for production
config.WithSampling(config.SamplingAlwaysOn, 0)         // 100% sampling for development
config.WithSampling(config.SamplingAlwaysOff, 0)        // Disable tracing

type SamplerFactory 

type SamplerFactory interface {
	CreateSampler(cfg *config.Config) sdktrace.Sampler
}

SamplerFactory defines the interface for creating samplers. This allows for extensible sampler creation without modifying existing code.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.