OpenTelemetry API: The Stable Interface for Your Code
The OpenTelemetry API provides stable interfaces for your code to generate telemetry. This lets you instrument your application once, while the SDK implementation handles the actual data processing and export, which can be swapped out later.
WHY IT EXISTS To decouple instrumentation from implementation. Before OpenTelemetry, if you instrumented your code for one monitoring vendor and wanted to switch to another, you had to rewrite all your instrumentation code. A stable, vendor-neutral API was needed to solve this vendor lock-in and make instrumentation portable.
THE MENTAL MODEL The OpenTelemetry API is like a universal electrical outlet standard. Your application (the appliance) is built to plug into this standard. The API defines the shape of the plug and the voltage, but provides no power itself. The OpenTelemetry SDK is the power plant and wiring behind the wall. You can change your electricity provider (the SDK and its configuration) without re-wiring your appliance (your application code).
HOW IT WORKS The API package in any language (e.g., opentelemetry-api in Java or Python) contains interfaces like Tracer and Meter. Your code calls methods on these interfaces to create spans or record metrics. By default, if no SDK is configured, these calls do nothing; they are "no-op". In your final application, you include and configure an SDK package (e.g., opentelemetry-sdk). The SDK provides the concrete implementations that process this data and send it to a configured backend like Jaeger, Prometheus, or a vendor platform.
WHEN TO USE IT Always depend ONLY on the API package when writing code within a shared library. This allows consumers of your library to use it with any OpenTelemetry-compatible backend they choose. Application code also uses the API to generate telemetry signals.
WHEN NOT TO USE IT You don't use the API alone if you actually want to export data. An executable service that needs to emit telemetry must also include and configure an SDK. The rule is: libraries depend on the API; executables depend on the API and configure an SDK.
ONE CANONICAL EXAMPLE A Python library author adds a dependency on opentelemetry-api. They add tracing to a function with tracer = trace.get_tracer(__name__) and with tracer.start_as_current_span("process_data"). They publish the library. An application developer then uses this library. In their main application, they add dependencies on opentelemetry-sdk and an exporter. Now, the library's tracing calls are activated and seamlessly integrated into the application's traces.
Read the original → opentelemetry.io
Get five bites like this every day.
Tezvyn delivers a daily feed of 60-second tech bites with quizzes to lock in what you learn.