3.4 Composability & Extension: Plugin Interfaces, Distributions & Contrib

3.4 Composability & Extension: Plugin Interfaces, Distributions & Contrib

Quick Answer: OpenTelemetry is built from interchangeable parts. The SDK exposes standard plugin interfaces, including samplers, span and log processors, exporters, metric readers, views, propagators, resource detectors, and ID generators, so teams can add behaviour without forking the project. Instrumentation libraries, vendor exporters, and extra propagators live in contrib repositories; vendors package upstream parts as distributions; and the Collector is composed at build time from receivers, processors, exporters, connectors, and extensions.

The "Composability and Extension" competency asks a practical question: when the default behaviour is not enough, where do you plug in your change? Choosing the right extension point keeps instrumentation portable. The wrong choice usually means patching the SDK, losing data, or hard-coding a vendor into application code.

---

Why OpenTelemetry Is Designed to Be Composed

Three design decisions make OpenTelemetry composable:

1. API/SDK separation (Section 3.1). Libraries depend only on the API, so any SDK, whether the reference SDK or a vendor distribution, can be installed underneath without touching library code.
2. Specified plugin interfaces. The specification defines the interfaces the SDK must expose (for example Sampler, SpanProcessor, SpanExporter, MetricReader, TextMapPropagator). A custom component written against one of them works with the standard pipeline.
3. A common data model and protocol. Because every component speaks the same data model and OTLP, you can swap an exporter or add a Collector stage without changing the producers.

---

SDK Extension Points

Several contract details from the specification matter when you write or combine these components:

• Processors run in registration order. Each OnStart receives a writable span, so an enrichment processor must be registered before the batch processor that exports.
• OnEnd receives a read-only span. An exporter cannot add attributes; enrichment belongs in OnStart (a newer OnEnding hook, still in Development status, allows a last change just before the span becomes read-only).
• Export is serialized: the specification says Export should not be called concurrently for the same exporter instance, and the built-in processors follow that rule, so an exporter does not need its own locking around Export.
• ForceFlush and Shutdown cascade: calling them on a provider calls them on every registered processor or reader, which in turn flush their exporters.

Example: A Custom Enrichment Processor

The following Python processor copies a tenant.id baggage entry onto every new span. It is registered before the batch processor so that the attribute exists when the span is exported:

from opentelemetry import baggage
from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter


class TenantSpanProcessor(SpanProcessor):
    def on_start(self, span, parent_context=None):
        tenant = baggage.get_baggage("tenant.id", parent_context)
        if tenant is not None:
            span.set_attribute("tenant.id", tenant)


provider = TracerProvider()
provider.add_span_processor(TenantSpanProcessor())                     # enrichment first
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))   # export last

You rarely need to write this one yourself: ready-made baggage span processors exist in the Java, JavaScript, Python, and Go contrib repositories. The example shows the pattern that every enrichment processor follows.

---

Core, Contrib, and Instrumentation Libraries

Each language has a core repository (API, SDK, OTLP exporter) and a contrib repository. Contrib holds the pieces that are optional or backend-specific:

• Instrumentation libraries for frameworks and clients (HTTP servers, database drivers, messaging clients).
• Extra propagators such as B3, Jaeger (deprecated), and AWS X-Ray.
• Resource detectors for cloud platforms and container runtimes.
• Vendor exporters, samplers such as the Jaeger remote sampler, and processors such as the baggage span processor.

Contrib components carry their own stability levels. The long-term goal is native instrumentation, where a library calls the OpenTelemetry API itself, so no separate instrumentation package is needed.

---

Distributions

A distribution is a customized package of an upstream OpenTelemetry component. It is a wrapper around upstream code, not a fork. The OpenTelemetry documentation describes three kinds:

Because distributions keep the upstream APIs and data model, code instrumented against the OpenTelemetry API keeps working if you switch distributions.

---

Extending the Collector

The Collector is composable at build time. Every component (receiver, processor, exporter, extension, connector) is a Go module with a factory, and a binary contains only the components compiled into it. The OpenTelemetry Collector Builder (OCB, Section 9.1) turns a manifest listing those modules into a custom binary; a custom component is simply one more module in that manifest. At run time, the YAML configuration chooses which compiled components to instantiate and how to wire them into pipelines. Each component declares a stability level per signal (Development, Alpha, Beta, Stable, Deprecated, or Unmaintained), which you should check before relying on it in production.

---

Choosing the Right Extension Point