otel

OpenTelemetry Integration

Unified OpenTelemetry v2 configuration and instrumentation utilities for the pkg library ecosystem.

Overview

The otel package provides centralized OpenTelemetry configuration that enables observability across all library packages. It supports the three pillars of observability:

• Traces - Distributed tracing for request flows
• Metrics - Performance and health measurements
• Logs - Structured logging via OpenTelemetry standard

Features

• Unified Configuration: Single config object for all telemetry pillars
• Selective Enablement: Enable only the telemetry you need
• No-op by Default: Zero overhead when providers are not configured
• Method Chaining: Fluent API for configuration
• Semantic Conventions: Library-specific attributes for consistent instrumentation
• Graceful Shutdown: Proper resource cleanup

Installation

go get github.com/jasoet/pkg/v2/otel

Quick Start

Basic Configuration

package main

import (
    "context"
    "github.com/jasoet/pkg/v2/otel"
    "go.opentelemetry.io/otel/sdk/trace"
    "go.opentelemetry.io/otel/sdk/metric"
)

func main() {
    // Create tracer and meter providers (your setup)
    tracerProvider := trace.NewTracerProvider(/* ... */)
    meterProvider := metric.NewMeterProvider(/* ... */)

    // Create unified OTel config
    otelConfig := otel.NewConfig("my-service").
        WithTracerProvider(tracerProvider).
        WithMeterProvider(meterProvider).
        WithServiceVersion("1.0.0")

    // Use with library packages
    // server.Start(server.Config{OTelConfig: otelConfig, ...})
    // db.Pool(db.Config{OTelConfig: otelConfig, ...})

    // Cleanup on shutdown
    defer otelConfig.Shutdown(context.Background())
}

Selective Telemetry

Enable only what you need:

// Tracing only
cfg := otel.NewConfig("my-service").
    WithTracerProvider(tracerProvider).
    WithoutLogging()  // Disable default logging

// Metrics only
cfg := otel.NewConfig("my-service").
    WithMeterProvider(meterProvider).
    WithoutLogging()

// All three pillars
cfg := otel.NewConfig("my-service").
    WithTracerProvider(tracerProvider).
    WithMeterProvider(meterProvider).
    WithLoggerProvider(loggerProvider)

Custom Logger Provider

Use the logging package for better formatting and automatic trace correlation:

import (
    "github.com/jasoet/pkg/v2/logging"
    "github.com/jasoet/pkg/v2/otel"
)

// Production-ready logger with trace correlation
loggerProvider := logging.NewLoggerProvider("my-service", false)

cfg := otel.NewConfig("my-service").
    WithTracerProvider(tracerProvider).
    WithMeterProvider(meterProvider).
    WithLoggerProvider(loggerProvider)

Configuration API

Config Struct

type Config struct {
    TracerProvider trace.TracerProvider  // nil = no tracing
    MeterProvider  metric.MeterProvider  // nil = no metrics
    LoggerProvider log.LoggerProvider    // nil = no OTel logs
    ServiceName    string
    ServiceVersion string
}

Builder Methods

Helper Methods

// Check what's enabled
cfg.IsTracingEnabled()  // bool
cfg.IsMetricsEnabled()  // bool
cfg.IsLoggingEnabled()  // bool

// Get instrumentation components
tracer := cfg.GetTracer("scope-name")   // Returns no-op if disabled
meter := cfg.GetMeter("scope-name")     // Returns no-op if disabled
logger := cfg.GetLogger("scope-name")   // Returns no-op if disabled

// Cleanup
cfg.Shutdown(context.Background())

Semantic Conventions

Library-specific attributes for consistent instrumentation:

Server Package

otel.AttrServerPort         // "pkg.server.port"

gRPC Package

otel.AttrGRPCMode           // "pkg.grpc.mode"
otel.AttrGRPCPort           // "pkg.grpc.port"
otel.AttrGRPCHTTPPort       // "pkg.grpc.http_port"
otel.AttrGRPCReflection     // "pkg.grpc.reflection_enabled"
otel.AttrGRPCGatewayEnabled // "pkg.grpc.gateway_enabled"

// Values
otel.GRPCModeSeparate       // "separate"
otel.GRPCModeH2C            // "h2c"

REST Client Package

otel.AttrRESTClientName     // "pkg.rest.client.name"
otel.AttrRESTRetryCount     // "pkg.rest.retry.max_count"
otel.AttrRESTRetryAttempt   // "pkg.rest.retry.attempt"
otel.AttrRESTTimeout        // "pkg.rest.timeout_ms"

Database Package

otel.AttrDBConnectionPool   // "pkg.db.pool.name"
otel.AttrDBType            // "pkg.db.type"
otel.AttrDBMaxIdleConns    // "pkg.db.pool.max_idle"
otel.AttrDBMaxOpenConns    // "pkg.db.pool.max_open"

// Values
otel.DBTypePostgreSQL      // "postgresql"
otel.DBTypeMySQL           // "mysql"
otel.DBTypeMSSQL           // "mssql"

Concurrent Package

otel.AttrConcurrentTaskCount   // "pkg.concurrent.task.count"
otel.AttrConcurrentTaskSuccess // "pkg.concurrent.task.success"
otel.AttrConcurrentTaskFailed  // "pkg.concurrent.task.failed"
otel.AttrConcurrentMaxWorkers  // "pkg.concurrent.max_workers"

Integration Examples

HTTP Server

import (
    "github.com/jasoet/pkg/v2/otel"
    "github.com/jasoet/pkg/v2/server"
)

otelConfig := otel.NewConfig("my-api").
    WithTracerProvider(tracerProvider).
    WithMeterProvider(meterProvider)

server.Start(server.Config{
    Port:       8080,
    OTelConfig: otelConfig,
})

gRPC Server

import (
    "github.com/jasoet/pkg/v2/otel"
    "github.com/jasoet/pkg/v2/grpc"
)

otelConfig := otel.NewConfig("my-grpc-service").
    WithTracerProvider(tracerProvider).
    WithMeterProvider(meterProvider)

grpcServer := grpc.NewServer(
    grpc.NewConfig("my-service", 9090).
        WithOTelConfig(otelConfig),
)

Database

import (
    "github.com/jasoet/pkg/v2/otel"
    "github.com/jasoet/pkg/v2/db"
)

otelConfig := otel.NewConfig("my-db-service").
    WithTracerProvider(tracerProvider).
    WithMeterProvider(meterProvider)

pool, _ := db.ConnectionConfig{
    DbType:     db.Postgresql,
    Host:       "localhost",
    OTelConfig: otelConfig,
}.Pool()

// All queries are automatically traced
pool.Find(&users)

REST Client

import (
    "github.com/jasoet/pkg/v2/otel"
    "github.com/jasoet/pkg/v2/rest"
)

otelConfig := otel.NewConfig("my-client").
    WithTracerProvider(tracerProvider).
    WithMeterProvider(meterProvider)

client := rest.NewClient(rest.ClientConfig{
    BaseURL:    "https://api.example.com",
    OTelConfig: otelConfig,
})

// Requests are automatically traced
client.Get("/users", &result)

Complete Example

See the fullstack OTel example for a complete application demonstrating all three telemetry pillars across multiple packages.

Testing

The package includes comprehensive tests with 97.1% coverage:

# Run tests
go test ./otel -v

# With coverage
go test ./otel -cover

Test Utilities

Use no-op providers for testing:

import (
    "github.com/jasoet/pkg/v2/otel"
    noopm "go.opentelemetry.io/otel/metric/noop"
    noopt "go.opentelemetry.io/otel/trace/noop"
)

func TestMyCode(t *testing.T) {
    cfg := otel.NewConfig("test-service").
        WithTracerProvider(noopt.NewTracerProvider()).
        WithMeterProvider(noopm.NewMeterProvider()).
        WithoutLogging()

    // Test your code with cfg
}

Best Practices

1. Create Once, Share Everywhere

// ✅ Good: Single config shared across packages
otelConfig := otel.NewConfig("my-service").
    WithTracerProvider(tp).
    WithMeterProvider(mp)

serverCfg := server.Config{OTelConfig: otelConfig}
dbCfg := db.Config{OTelConfig: otelConfig}

2. Always Shutdown

// ✅ Good: Graceful shutdown
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := otelConfig.Shutdown(ctx); err != nil {
    log.Printf("OTel shutdown error: %v", err)
}

3. Use Semantic Conventions

// ✅ Good: Use defined attributes
import "go.opentelemetry.io/otel/attribute"

span.SetAttributes(
    otel.AttrServerPort.Int(8080),
    otel.AttrGRPCMode.String(otel.GRPCModeH2C),
)

4. Check Before Using

// ✅ Good: Check enablement
if cfg.IsTracingEnabled() {
    tracer := cfg.GetTracer("my-scope")
    // Use tracer
}

5. Production Logger Provider

// ✅ Good: Use logging package for production
import "github.com/jasoet/pkg/v2/logging"

cfg := otel.NewConfig("my-service").
    WithLoggerProvider(logging.NewLoggerProvider("my-service", false))

Architecture

Design Principles

1. Zero Dependencies: Only depends on OTel SDK (no custom exporters)
2. No-op Safety: Nil providers result in no-op implementations
3. Lazy Initialization: Providers created only when needed
4. Immutable Config: Thread-safe after creation

Package Structure

otel/
├── config.go       # Config struct and builder methods
├── attributes.go   # Semantic conventions
├── doc.go         # Package documentation
└── config_test.go # Comprehensive tests (97.1% coverage)

Troubleshooting

No Telemetry Data

Problem: Not seeing traces/metrics/logs

Solutions:

// 1. Check if enabled
fmt.Println("Tracing:", cfg.IsTracingEnabled())
fmt.Println("Metrics:", cfg.IsMetricsEnabled())
fmt.Println("Logging:", cfg.IsLoggingEnabled())

// 2. Verify providers are set
if cfg.TracerProvider == nil {
    // Tracing will be no-op
}

// 3. Ensure shutdown is called
defer cfg.Shutdown(context.Background())

Default Logger Too Verbose

Problem: Stdout logger creating too much output

Solution:

// Disable default logger
cfg := otel.NewConfig("my-service").WithoutLogging()

// Or use custom logger
cfg := otel.NewConfig("my-service").
    WithLoggerProvider(myLoggerProvider)

Provider Already Registered

Problem: Global provider conflicts

Solution: This package doesn't use global providers - it returns scoped instruments from GetTracer(), GetMeter(), and GetLogger().

Version Compatibility

• OpenTelemetry: v1.38.0+
• Go: 1.25+
• pkg library: v2.0.0+

Migration from v1

v2 uses OpenTelemetry v2 API:

// v1 (OTel v1)
import "go.opentelemetry.io/otel"
tracer := otel.Tracer("my-scope")

// v2 (OTel v2)
import "github.com/jasoet/pkg/v2/otel"
cfg := otel.NewConfig("my-service").WithTracerProvider(tp)
tracer := cfg.GetTracer("my-scope")

See VERSIONING_GUIDE.md for complete migration guide.

Related Packages

• logging - Structured logging with OTel integration
• server - HTTP server with automatic tracing
• grpc - gRPC server with automatic instrumentation
• db - Database with query tracing
• rest - REST client with distributed tracing

License

MIT License - see LICENSE for details.