opentracing-go

opentracing-go is the Go platform implementation of the OpenTracing specification: a small, vendor-neutral set of interfaces (Tracer, Span, SpanContext) that let application and library code create and propagate distributed traces without binding to any single tracing backend. Instrumented code calls opentracing.StartSpan or StartSpanFromContext and injects/extracts span context over the wire via Inject/Extract, while the actual recording, sampling, and export logic lives entirely in a separate Tracer implementation (Jaeger, LightStep, Zipkin-compatible tracers, etc.) supplied by the application at startup.

The package ships a goroutine-safe global tracer singleton, a zero-overhead NoopTracer default so libraries can instrument unconditionally, a context.Context integration for span propagation across call boundaries, and companion packages (ext for semantic-convention tags, log for typed log fields, mocktracer for an in-memory test double, and harness for a reusable Tracer conformance test suite). The project is explicitly deprecated in favor of OpenTelemetry, which merged OpenTracing and OpenCensus into a single standard — it remains useful mainly for maintaining or understanding legacy instrumentation written against the OpenTracing API.

What You Get

• Core Tracer/Span/SpanContext interfaces for starting, tagging, logging, and finishing spans
• A goroutine-safe global tracer (SetGlobalTracer/GlobalTracer) plus a no-op default so instrumentation is always safe to call
• context.Context integration via StartSpanFromContext/ContextWithSpan/SpanFromContext for idiomatic Go span propagation
• Built-in TextMap and HTTPHeaders propagation formats with Inject/Extract for cross-process trace context
• The ext subpackage of semantic-convention tag helpers (HTTP status, DB statement, peer service, etc.)
• The mocktracer subpackage, an in-memory Tracer implementation for asserting on spans in unit tests
• The harness subpackage, a conformance test suite any real Tracer implementation can embed against its own code

Common Use Cases

• Instrumenting an HTTP or RPC service to emit spans that a tracing backend (Jaeger, LightStep, Zipkin) can consume
• Writing framework or middleware code that traces requests without hard-coding a specific tracing vendor
• Propagating trace context across service boundaries via HTTP headers or message-queue metadata
• Unit-testing span creation and tagging logic against mocktracer instead of a live tracing backend
• Maintaining legacy Go services instrumented before their tracing stack migrated to OpenTelemetry

Under The Hood

Architecture The root opentracing package is a pure interface/spec layer: tracer.go and span.go define the Tracer, Span, SpanContext, and StartSpanOption contracts; propagation.go defines the Inject/Extract format constants and carrier types (TextMapCarrier, HTTPHeadersCarrier); gocontext.go bridges spans into context.Context via a private context key; globaltracer.go holds a package-level mutable singleton (registeredTracer) that SetGlobalTracer/GlobalTracer read and write directly, with no mutex — safe only because real code sets it once at startup; and noop.go supplies the zero-cost NoopTracer/noopSpan used before any real tracer is registered. Sibling packages ext, log, mocktracer, and harness are consumers of these same interfaces rather than internal layers — mocktracer is a full alternate Tracer implementation, and harness is a generic conformance suite any third-party Tracer can run against itself. Because this package defines a contract rather than behavior, changing the core Tracer interface breaks every downstream tracing implementation by design.

Tech Stack Plain Go 1.14 module with zero runtime dependencies — only the standard library (context, net/http, errors, time) is imported by non-test code; stretchr/testify is the sole dependency, and it’s test-only. There is no build step beyond go build; the Makefile’s test-and-lint target runs go test -race -cover, golint, and go vet, and GitHub Actions workflows plus a .golangci.yml back that up in CI. As a spec-only library it has no runtime, deployment target, or database of its own — it’s consumed by whichever tracing backend a service links in.

Code Quality 11 test files cover the core package and every subpackage, using testify’s assert/require for readable assertions; harness/api_checkers.go is a particularly mature pattern — a shared conformance test that any Tracer implementation (in this repo or a downstream one) can embed to verify it satisfies the OpenTracing contract. Errors are idiomatic Go sentinel values (ErrUnsupportedFormat, ErrSpanContextNotFound, ErrInvalidCarrier, ErrSpanContextCorrupted, ErrInvalidSpanContext) rather than panics, exported symbols carry full godoc comments, and CI runs the race detector, golint, and go vet on every push.

API Design The API is deliberately minimal and functional-options-based (StartSpanOption, Tag, StartTime) so callers only touch a handful of entry points — StartSpan, ChildOf, StartSpanFromContext — to get root spans, child spans, and context propagation. That minimalism was historically influential: OpenTracing was the first widely-adopted vendor-neutral tracing API for Go, decoupling instrumented libraries from any single tracing backend. The project is now explicitly deprecated — its GitHub description points directly to OpenTelemetry, which absorbed OpenTracing and OpenCensus into one standard — so its API design is a legacy reference point rather than an active target for new instrumentation.