OpenTelemetry API - KodeKloud

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.

The image illustrates how OpenTelemetry acts as a cross-language bridge, supporting multiple programming languages like C++, Python, and JavaScript, and connecting them to a standard telemetry API.

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.

The image explains the OpenTelemetry API as a vendor-neutral tool for handling traces, metrics, and logs, with standardized specifications for language-specific APIs.

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.

The image shows a section of the OpenTelemetry documentation focusing on "Status and Releases" with a table listing various programming languages and their component statuses. The sidebar features a menu with links to related documentation sections.

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:

pip install opentelemetry-api
pip install opentelemetry-sdk

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.

The image describes the OpenTelemetry API, highlighting its role in defining standardized interfaces for creating and managing traces, metrics, logs, and propagating context across service boundaries. It enables telemetry generation without relying on a specific backend or SDK implementation.

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.

The image outlines three API key characteristics: self-sufficient dependency, no telemetry output by default, and minimal default implementation, with brief descriptions of each.

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.

The image explains the roles of OpenTelemetry API and SDK, highlighting the API's focus on defining the creation and management of spans, metrics, and logs, and the SDK's role in managing context propagation, sampling, batching, and exporting data to 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.

The image illustrates the benefits of separating APIs and SDKs, showing app code interfacing with an API layer that includes language-specific APIs (Java, Python, Node.js, Go) and a language-agnostic core specification. It highlights consistent instrumentation across languages and the ability to swap or update SDKs without changing code.

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.

The image illustrates the OpenTelemetry API benefits, highlighting consistent code instrumentation across different environments and the ability to update SDKs without changing instrumentation logic.

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/

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.

The image provides guidelines for using the OpenTelemetry API, recommending library authors to use the API for its advantages and application developers to choose the SDK while listing "do" and "avoid" practices.

Instrumenting libraries — a small Python example Instrument libraries with API-only calls so the host application decides the SDK:

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...

The image is a guide on using the OpenTelemetry API for instrumenting libraries, suggesting that library authors use the API to maintain self-sufficiency and portability, while applications should choose the SDK for components like exporters and processors. It includes a "Do" list for using OpenTelemetry effectively.

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.

The image is a flowchart showing how different roles interact with the OpenTelemetry SDK, including Instrumentation Authors using API, Application Owners for setup, and Plugin Authors with plugin interfaces.

The image illustrates how different roles, such as instrumentation authors, application owners, and plugin authors, interact with the OpenTelemetry SDK through various components like API, setup, and plugin interfaces. It highlights interactions involving traces, metrics, configurations, exporters, and processors.

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.

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.

The image is a "Knowledge Check" slide asking about the primary purpose of the OpenTelemetry API, with three options listed as answers.

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.

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.

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.

The image is a knowledge check slide asking what happens if an application uses the OpenTelemetry API without configuring an SDK, with three possible answers provided.

That’s it for this lesson/article. Links and references

OpenTelemetry documentation: https://opentelemetry.io/docs/
Python instrumentation guide: https://opentelemetry.io/docs/instrumentation/python/
Semantic conventions: https://opentelemetry.io/docs/reference/specification/semantic_conventions/

Watch Video

OpenTelemetry End to End Architecture

OpenTelemetry Client Design Principles