> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenTelemetry API
> Overview of the OpenTelemetry API, a language agnostic contract for generating traces metrics and logs, contrasts with SDK, and offers instrumentation best practices and examples
Hello, OTel architecture experts.
In this lesson/article we'll take a focused look at the OpenTelemetry API: what it is, how it differs from the SDK, and best practices for instrumenting applications and libraries. This article preserves the original diagrams and their order so you can follow the architecture visually as you read.
Why a language-agnostic telemetry API?
Modern systems are polyglot: Java, Go, Python, PHP, Ruby, Swift, JavaScript and more all produce telemetry. Language-specific approaches (for example, print statements or ad-hoc logging) are not portable across ecosystems. OpenTelemetry provides a vendor-neutral, cross-language standard API so you can generate traces, metrics, and logs without coupling instrumentation to a particular backend or SDK.
What is the OpenTelemetry API?
The OpenTelemetry API is the language-agnostic specification for generating telemetry data—traces, metrics, and logs. It defines the interfaces and data types (the contract) that application code and libraries call. Each supported language exposes an idiomatic API that implements that contract.
Specification vs implementation
The OpenTelemetry specification describes the data model and operations for telemetry and can evolve to include additional signals (such as profiling). Language-specific APIs and SDKs implement the spec; find the current status and releases in the project documentation.
Quick Python example (install + basic tracer provider)
To try OpenTelemetry in Python, install the API and SDK packages, configure a tracer provider, and add a span processor/exporter:
```bash theme={null}
pip install opentelemetry-api
pip install opentelemetry-sdk
```
```python theme={null}
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
BatchSpanProcessor,
ConsoleSpanExporter,
)
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
# Set global tracer provider (application-level configuration)
trace.set_tracer_provider(provider)
# Create a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
```
The above shows how the API is used by application code. The SDK is the component that provides batching, sampling, and exporting behavior you configure at deployment time.
Key characteristics of the OpenTelemetry API
Your application and third-party libraries call the OpenTelemetry API to record telemetry without needing knowledge of how it will be processed or where it will be sent. The API provides:
* Standardized contracts (tracer, meter, logger interfaces).
* A minimal no-op (NOP) implementation so instrumentation is safe even if no SDK is installed.
* The ability to plug in a full SDK later for sampling, processing, and exporting—without changing instrumented code.
Runtime behavior when no SDK is present
If only the API artifacts are available, calls like `trace.get_tracer()` or `meter.get_meter()` succeed and return functional objects. Spans and metrics created in this state are no-op (silently discarded). This design makes library and framework instrumentation safe: instrumentation remains present but harmless if the application never configures an SDK.
API vs SDK — responsibilities comparison
* API: defines the "what" — interfaces for creating and managing spans, metrics, logs, and context propagation.
* SDK: defines the "how" — sampling, batching, exporting, and advanced processing.
Common SDK responsibilities:
* Sampling policies to limit telemetry volume.
* Batching spans and metrics for efficient export.
* Exporters that send telemetry to collectors or observability backends.
Binding contract and portability
The API + SDK form a binding contract between application code and the telemetry implementation. As long as SDK implementations follow the API contract, instrumented code remains unchanged when switching SDKs or backends. This enables consistent instrumentation across languages and flexible backend choices.
Practical benefits
* Instrumentation patterns remain similar across languages while staying idiomatic.
* Exporters or SDK implementations can be swapped without touching instrumentation code.
* Application owners choose SDK configuration (exporters, samplers, processors) at deployment time.
Guidelines for library authors
Most apps rely on third-party libraries (DB clients, HTTP clients, messaging libraries). Library authors should instrument using only the OpenTelemetry API (not the SDK) so applications remain free to choose the SDK and configuration.
Do:
* Depend only on the OpenTelemetry API.
* Obtain tracer/meter from the global provider (safe when SDK is absent).
* Propagate and respect context across call paths.
* Use official semantic conventions for spans and attributes: [https://opentelemetry.io/docs/reference/specification/semantic\_conventions/](https://opentelemetry.io/docs/reference/specification/semantic_conventions/)
Don't:
* Leak SDK classes or types in public library signatures.
* Configure exporters, samplers, or processors inside library code.
Library authors: prefer API-only instrumentation. This ensures your instrumented library works regardless of which SDK or exporter the application selects.
Do not configure SDK components (exporters, processors, samplers) inside libraries. SDK setup belongs to the application or deployment environment.
Instrumenting libraries — a small Python example
Instrument libraries with API-only calls so the host application decides the SDK:
```python theme={null}
from opentelemetry import trace
tracer = trace.get_tracer(__name__) # API-only
def handler(req):
# Start a span (API usage only)
with tracer.start_as_current_span("lib.operation") as span:
span.set_attribute("http.route", "/items/{id}")
# perform library work...
```
Language-neutral specification and idiomatic APIs
The specification is language-neutral and does not mandate exact method names. Each language provides idiomatic APIs:
* Python: `start_as_current_span()`
* Java: `SpanBuilder().startSpan()`
* JavaScript: `tracer.startSpan()`
* Go: language-idiomatic start functions
The core principle: use the OpenTelemetry API for spans, metrics, and context propagation; method names are idiomatic per language.
Roles and responsibilities
OpenTelemetry encourages clear role separation so the system remains modular:
* Instrumentation authors: use the API to generate telemetry (spans, metrics, logs). API stability minimizes churn for authors.
* Application owners: configure the SDK at deployment time—choose sampling, exporters, and processing strategies.
* Plugin/SDK authors: implement exporters, processors, and samplers to connect telemetry to backends or to transform/filter data.
Together these roles let developers add telemetry, operators decide how to handle it, and plugin authors extend the platform to integrate with backends.
Knowledge check
Use these quick questions to verify your understanding.
1. What is the primary purpose of the OpenTelemetry API?
* Options: Export telemetry to backends; provide language-specific SDKs; define the interface for creating telemetry; collect and store telemetry locally.
* Correct: Define the interface for creating telemetry data (traces, metrics, logs). Exporting is handled by SDKs/plugins.
2. In OpenTelemetry, what does a tracer object do?
* Options: Collect metrics; export spans; create and manage spans; aggregate logs.
* Correct: Create and manage spans to trace operations. Exporting is done by SDK/exporters.
3. Which statement about OpenTelemetry API and SDK is correct?
* Options: API and SDK are tightly coupled; Applications only use the SDK directly; The API is designed to be used independently of the SDK; The API requires a specific backend at compile time.
* Correct: The API is designed to be used independently of the SDK. It is no-op-safe.
4. What happens if an application only uses the OpenTelemetry API and no SDK is configured?
* Options: Application fails to start; Telemetry is generated and exported by default; The API operates in no-op mode without errors; The API throws runtime exceptions for missing SDKs.
* Correct: The API operates in a no-op mode without errors; telemetry is discarded unless an SDK is configured.
That’s it for this lesson/article.
Links and references
* OpenTelemetry documentation: [https://opentelemetry.io/docs/](https://opentelemetry.io/docs/)
* Python instrumentation guide: [https://opentelemetry.io/docs/instrumentation/python/](https://opentelemetry.io/docs/instrumentation/python/)
* Semantic conventions: [https://opentelemetry.io/docs/reference/specification/semantic\_conventions/](https://opentelemetry.io/docs/reference/specification/semantic_conventions/)