trace

README

Trace Package

The trace package provides an easy-to-use utility for adding distributed tracing to Go applications using OpenTelemetry. With support for multiple trace exporters, function-level tracing, and integration with web frameworks like Gin, this package simplifies instrumentation and performance monitoring across services.

Key Features:

• Tracer Provider Initialization: Easily initialize and configure OpenTelemetry's Tracer Provider with support for multiple exporters, including: gRPC Exporter: Export traces to remote tracing backends. Stdout Exporter: Print traces to the console for local development and debugging.
• Function-Level Tracing (TraceFunc): Automatically trace the execution of any Go function, including capturing function start/end times, execution status, and errors.

Usage

1. Initialize Tracer Provider

To initialize the Tracer Provider, call InitTracerProvider with the service name and desired exporter:

ctx := context.Background()
tracerProvider, err := trace.InitTracerProvider(ctx, "my-service", nil, trace.ExporterStdout)
if err != nil {
    log.Fatalf("Failed to initialize tracer provider: %v", err)
}
defer tracerProvider.Shutdown(ctx)

You can also set the OTEL_SERVICE_NAME environment variable to override the service name dynamically. Additionally, you can set the OTEL_RESOURCE_ATTRIBUTES environment variable to specify additional resource attributes.

2. Function-Level Tracing (TraceFunc)

Wrap any function in TraceFunc to automatically trace its execution:

result, err := trace.TraceFunc(ctx, otel.Tracer("my-tracer"), func(ctx context.Context) (string, error) {
    // Simulate some processing
    time.Sleep(100 * time.Millisecond)
    return "Hello, World!", nil
})

if err != nil {
    log.Fatalf("Error executing traced function: %v", err)
}
fmt.Println("Result:", result)

Example

You can find a complete working example in the repository under framework/trace/example.

Documentation

Index

• func DefaultTracer() trace.Tracer
• func InitTracerProvider(ctx context.Context, serviceName string, endpoint *string, ...) (*sdktrace.TracerProvider, error)
• func TraceFunc[T any](ctx context.Context, tracer trace.Tracer, ...) (T, error)
• type ExporterType

Functions

func DefaultTracer

func DefaultTracer() trace.Tracer

func InitTracerProvider

func InitTracerProvider(ctx context.Context, serviceName string, endpoint *string, exporterType ExporterType) (*sdktrace.TracerProvider, error)

InitTracerProvider initializes an OpenTelemetry TracerProvider with the specified service name, exporter type, and gRPC endpoint (if needed). It supports both stdout and gRPC exporters and sets global tracing and propagation configurations.

Params:

• ctx: Context for initialization, used for trace exporter creation and resource detection.
• serviceName: The name of the service being traced. Can be overridden by the environment variable `OTEL_SERVICE_NAME`.
• endpoint: The gRPC endpoint for trace exporters (only applicable for the gRPC exporter).
• exporterType: The type of exporter to use (either "stdout" or "grpc").

Returns:

• *sdktrace.TracerProvider: A new tracer provider to manage tracing.
• error: An error if the initialization fails.

func TraceFunc

func TraceFunc[T any](ctx context.Context, tracer trace.Tracer, f func(ctx context.Context) (T, error)) (T, error)

TraceFunc traces the start and end of a function and returns its result. It works with any function that returns a result and an error.

Types

type ExporterType

type ExporterType string

const (
	ExporterStdout ExporterType = "stdout"
	ExporterGRPC   ExporterType = "grpc"
)