otel

README

go-otel 🔭

Tiny OpenTelemetry bootstrap for Go services — one call wires OTLP/gRPC trace and metric exporters into global providers, installs W3C trace-context propagation, and ships instrument helpers plus RED HTTP middleware.

📦 Install

go get github.com/Bugs5382/go-otel

🚀 Usage

Init sets up both traces and metrics on the same OTLP/gRPC endpoint, sharing one resource tagged with service.name. The returned shutdown flushes both pipelines.

shutdown, err := otel.Init(ctx, "my-service", "localhost:4317")
if err != nil {
	log.Fatal(err)
}
defer shutdown(context.Background())

Traces export over OTLP/gRPC (insecure) to the given endpoint. A logs exporter is planned for a later release. 📈

📊 Metrics

After Init, create instruments off the global meter with the helpers and record against them:

requests := otel.Counter("orders.placed", "Orders placed.")
requests.Add(ctx, 1)

latency := otel.Histogram("db.query.duration", "Query duration.", "s")
latency.Record(ctx, 0.042)

Wrap an http.Handler with the middleware to record the RED signals (request rate, errors, duration) using HTTP semantic-convention names — the templated route is picked up automatically from a net/http ServeMux:

mux := http.NewServeMux()
mux.HandleFunc("GET /items/{id}", itemsHandler)

http.ListenAndServe(":8080", otel.Metrics(mux))

🛠 Develop

task build    # go build ./...
task test     # go test ./...
task lint     # gofmt check + golangci-lint + yamllint
task license  # inject MIT headers (golic)

⚖️ License

MIT © 2026 Shane

Documentation

Overview

Package otel wires OTLP gRPC trace and metric exporters into global Tracer and Meter providers from a single Init call, and provides convenience instrument constructors plus RED HTTP middleware. A logs exporter arrives in a later release.

Index

• func Counter(name, description string) metric.Int64Counter
• func Histogram(name, description, unit string) metric.Float64Histogram
• func Init(ctx context.Context, service, otlpEndpoint string) (shutdown func(context.Context) error, err error)
• func Metrics(next http.Handler) http.Handler

Functions

func Counter

func Counter(name, description string) metric.Int64Counter

Counter returns a monotonic Int64Counter off the global meter. Instrument creation only fails on a malformed name, which is a programming error, so the helper panics rather than forcing every call site to handle an error that cannot occur at runtime.

func Histogram

func Histogram(name, description, unit string) metric.Float64Histogram

Histogram returns a Float64Histogram off the global meter. unit is a UCUM string (for example "s" or "ms"); pass "" for no unit. Like Counter, it panics on the programming-error case of a malformed name.

func Init

func Init(ctx context.Context, service, otlpEndpoint string) (shutdown func(context.Context) error, err error)

Init configures global Tracer and Meter providers that export over OTLP gRPC (insecure) to otlpEndpoint, tagged with service.name=service. Traces and metrics ride the same endpoint and share one resource, so a single call wires both. The returned shutdown func flushes and closes both providers; callers should defer it.

func Metrics

func Metrics(next http.Handler) http.Handler

Metrics wraps an http.Handler and records the RED signals (request rate, errors, duration) for every request it serves, using OTel HTTP server semantic-convention instrument and attribute names:

• http.server.request.duration histogram, seconds
• http.server.request.count counter (rate and errors derive from it)

Each measurement carries http.request.method, http.route, and http.response.status_code attributes. It depends only on net/http, so it composes with any stdlib-compatible router. Call Init first so the instruments record against the global MeterProvider.