otelpkg

package module
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 4 Imported by: 0

README

otelpkg

OpenTelemetry tracing helpers for Go services. Provides framework-native tracing middleware/handlers with path-based skip lists, plus a small tracing package that wires an OTLP gRPC exporter and W3C context propagation into the global OpenTelemetry provider.

  • Module: github.com/beabys/otelpkg (Go 1.26)
  • Root package: otelpkg — chi middleware + gRPC stats handler
  • Subpackage: tracing — TracerProvider initialisation

Install

go get github.com/beabys/otelpkg

Usage

chi middleware

NewChiMiddleware returns a native chi middleware (func(http.Handler) http.Handler) that creates one server span per request, skipping any path in skipPaths. The skip set is built once at construction time, so per-request lookup is O(1).

import (
    "github.com/go-chi/chi/v5"
    otel "github.com/beabys/otelpkg"
)

r := chi.NewRouter()
r.Use(otel.NewChiMiddleware("my-service", []string{"/health", "/ready"}))
r.Get("/users/{id}", handler)

Important: mount the middleware on a chi.NewRouter(). otelchi v0.12.3 requires a chi route context and will panic if the middleware runs around a bare http.Handler that is not mounted on a chi router.

gRPC stats handler

NewGRPCServerHandler returns a stats.Handler that creates one server span per RPC, skipping any full method name in skipMethods.

import (
    "google.golang.org/grpc"
    otel "github.com/beabys/otelpkg"
)

handler := otel.NewGRPCServerHandler([]string{
    "/grpc.health.v1.Health/Check",
    "/grpc.health.v1.Health/Watch",
})
srv := grpc.NewServer(grpc.StatsHandler(handler))
TracerProvider initialisation

tracing.Init configures the global OpenTelemetry TracerProvider and propagator. When Enabled is false it returns a no-op shutdown and dials nothing, so callers never need to branch on the flag.

import "github.com/beabys/otelpkg/tracing"

shutdown, err := tracing.Init(tracing.Config{
    Enabled:     true,
    Endpoint:    "localhost:4317",
    ServiceName: "my-service",
    SampleRatio: 1.0,
})
if err != nil {
    log.Fatal(err)
}
defer shutdown(context.Background())

Init validates that Endpoint and ServiceName are set when enabled, clamps SampleRatio to [0, 1], sets a parent-based trace-ID-ratio sampler, and installs a W3C TraceContext + Baggage propagator. Call it before creating routers and gRPC servers so inbound traceparent is extracted and outbound context injected.

Skip-list semantics

Skip lists are exact match (==), not prefix or glob. An empty or nil list traces every request. For both transports the skip set is constructed once and reused.

Configured skip /health /health/ /healthz /api/health /roles
/health skip trace trace trace trace
(empty) trace trace trace trace trace

Testing

go test -race ./...            # unit tests
go test -race -count=2 ./...   # repeat for flakiness
go vet ./...
gofmt -l .
go test -race -tags integration ./... # integration (in-process fake OTLP collector)

Unit tests use tracetest.SpanRecorder with an in-memory TracerProvider; no network is required. The global provider is saved and restored around each test to avoid cross-test pollution.

Known issues

  • otelchi v0.12.3 span name is the chi route pattern only (e.g. /users/{id}), with no HTTP method prefix.
  • Plain http.Handler unsupported — see the chi note above.

License

MIT — see LICENSE.

Documentation

Overview

otelpkg provides OpenTelemetry tracing utilities.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewChiMiddleware

func NewChiMiddleware(serviceName string, skipPaths []string) func(http.Handler) http.Handler

NewChiMiddleware returns a chi-compatible tracing middleware (func(http.Handler) http.Handler): a server span per request, skipping paths in skipPaths. The path matcher is built once at construction time.

Future framework-specific constructors (e.g. NewGinMiddleware) follow the same contract: return the framework's native middleware signature.

func NewGRPCServerHandler

func NewGRPCServerHandler(skipMethods []string) stats.Handler

NewGRPCServerHandler returns a gRPC server stats.Handler that creates one server span per RPC, skipping full method names in skipMethods. The exact-match filter set is built once at construction time.

Types

This section is empty.

Directories

Path Synopsis
tracing initialises the OpenTelemetry TracerProvider for the auth service.
tracing initialises the OpenTelemetry TracerProvider for the auth service.

Jump to

Keyboard shortcuts

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