3.1 Architectural Separation of API and SDK

3.1 Architectural Separation of API and SDK

At the core of OpenTelemetry lies a foundational architectural principle that distinguishes it from almost all legacy monitoring tools: the strict separation between the Application Programming Interface (API) and the Software Development Kit (SDK). This decoupled design solves the historical "dependency hell" and vendor lock-in that plagued earlier distributed tracing and metrics systems.

In legacy monitoring ecosystems, integrating observability required importing heavy vendor-specific libraries directly into domain logic or library code. These vendor libraries pulled in massive dependency trees, required specific network transport libraries (such as conflicting gRPC or HTTP client versions), and caused runtime breakage when two third-party dependencies required different versions of the same monitoring client. OpenTelemetry eliminates this friction by splitting observability into two completely isolated layers.

---

The OpenTelemetry API: Pure Abstraction

The OpenTelemetry API defines the conceptual vocabulary and programming abstractions for capturing telemetry. It specifies the interfaces, data types, context keys, and factory functions required to instrument application code and third-party libraries.

Core Characteristics of the API

1. No Pipeline Logic: The API does not manage queues, maintain export buffers, run background worker threads, execute sampling algorithms, or open network sockets. (It does include context management and, in most languages, the standard W3C propagators, because libraries need those even without an SDK.)
2. Minimal Dependencies: API packages are deliberately small and carry few or no third-party runtime dependencies, so adding the OpenTelemetry API to a shared package or framework creates very little risk of dependency version conflicts for downstream consumers.
3. Abstract Factories and Interfaces: The API defines the interfaces for telemetry primitives—such as Tracer, Meter, Logger, Span, and SpanContext—as well as the provider interfaces (TracerProvider, MeterProvider, LoggerProvider) used to obtain them.
4. Built-in No-Op Implementations: The API provides complete default "no-op" (no-operation) implementations of every interface. If an application invokes API methods without an SDK registered at runtime, the API calls execute as lightweight no-ops. These no-op calls return immediately, allocate minimal to zero heap memory, make no system calls, and will never throw exceptions, panic, or crash the host application.

The Golden Rule for Library Authors

The Golden Rule: Reusable libraries, frameworks, database drivers, and shared middleware MUST depend strictly on the OpenTelemetry API and NEVER on the OpenTelemetry SDK.

Consider an open-source database driver (e.g., an PostgreSQL driver or an HTTP client). If the driver author imported the OpenTelemetry SDK, the driver would force every application using that driver to pull in the SDK, its configuration defaults, its buffer queues, and its exporters. Furthermore, if the host application chose a different telemetry pipeline or SDK version, a diamond dependency conflict would occur.

By depending exclusively on the API, the library author instruments operations using standard calls like tracer.Start(). If the host application decides to enable OpenTelemetry by configuring an SDK at runtime, the library's instrumentation instantly comes alive and emits real telemetry. If the host application does not configure an SDK, the library's API calls seamlessly invoke no-op implementations with negligible CPU overhead and zero memory leakage.

---

The OpenTelemetry SDK: The Operational Engine

While the API specifies how code is instrumented, the OpenTelemetry SDK specifies how telemetry is processed, filtered, batched, and exported. The SDK is the concrete, production implementation of the API interfaces.

Core Responsibilities of the SDK

• Pipeline Construction: Orchestrates processors (e.g., BatchSpanProcessor, SimpleSpanProcessor) and readers that consume data generated by API calls.
• Sampling Algorithms: Evaluates head-based sampling rules (e.g., AlwaysOn, AlwaysOff, TraceIdRatioBased, ParentBased) to determine whether a span should be recorded and transmitted.
• Memory Management & Buffering: Allocates bounded in-memory queues (e.g., ring buffers) to decouple application execution threads from telemetry export pipelines.
• Metric Aggregation: Computes temporal aggregations (sums, gauges, explicit bucket histograms) across metric collection cycles.
• Batching & Network Export: Serializes telemetry into standard protocols (predominantly OTLP over gRPC or HTTP/Protobuf) and transmits data batches to an OpenTelemetry Collector or backend daemon.
• Resource Attribution: Automatically attaches static environmental metadata (such as service.name, service.version, k8s.pod.name, host.id) to all telemetry produced by the process.

Application Entrypoint Configuration

The OpenTelemetry SDK must be configured exclusively at the application entrypoint—such as the main() function, application bootstrap script, or container initialization hook. End-user applications (microservices, web servers, CLI tools) depend on both the API (to create custom business spans and metrics) and the SDK (to configure processors and exporters during startup).

+-------------------------------------------------------------------------+
|                        Application Entrypoint (main)                    |
|                                                                         |
|  1. Initialize Resource (service.name, environment)                     |
|  2. Configure Exporter (OTLP gRPC endpoint, credentials)                 |
|  3. Configure Span Processor (BatchSpanProcessor with queue limits)     |
|  4. Instantiate TracerProvider(Resource, Processor, Sampler)            |
|  5. Register TracerProvider as Global or inject via DI                  |
|  6. Register graceful shutdown hook (defer tracerProvider.Shutdown())   |
+-------------------------------------------------------------------------+

Graceful Teardown and Buffer Flushing

A critical SDK responsibility is graceful shutdown. Because production SDKs employ asynchronous batch processors (BatchSpanProcessor), spans and metrics reside in memory queues awaiting periodic export flushes (e.g., every 5,000 milliseconds). If an application process terminates abruptly upon receiving a SIGTERM or SIGINT without invoking TracerProvider.Shutdown() or TracerProvider.ForceFlush(), all telemetry currently buffered in memory is permanently lost.

---

Provider Architecture: Factories and Lifecycle Management

OpenTelemetry organizes signal instantiation through the Provider Pattern. For each observability signal, a central provider acts as an object factory:

1. TracerProvider: Factory that creates and manages named Tracer instances.
2. MeterProvider: Factory that creates and manages named Meter instances.
3. LoggerProvider: Factory that creates and manages named Logger instances.

Instrumentation Scopes

When code requests a Tracer or Meter from a provider, it passes an Instrumentation Scope consisting of a name (typically the fully qualified package or module name) and an optional version and schema URL:

# Requesting a tracer tagged with instrumentation scope
tracer = tracer_provider.get_tracer(
    instrumenting_module_name="com.example.billing.payment",
    instrumenting_library_version="1.4.2",
    schema_url="https://opentelemetry.io/schemas/1.24.0"
)

This scope metadata is automatically stamped onto every span and metric created by that tracer, allowing telemetry consumers to isolate spans produced by specific libraries or internal packages.

Global Providers vs. Explicit Dependency Injection

OpenTelemetry supports two primary architectural approaches for accessing providers:

---

API vs. SDK Architectural Comparison

The following table summarizes the division of responsibilities: