Before touching OpenTelemetry itself, you need the vocabulary around observability that every other concept builds on.

OpenTelemetry is a free, open-source set of tools, APIs, and standards for generating and collecting telemetry data — traces, metrics, and logs — from applications, so developers can understand how their systems are behaving in production.

Observability is the ability to understand what’s happening inside a system just by examining the data it produces from the outside, without needing to add new code every time you have a new question about its behavior.

The three pillars are traces (the journey of a single request through a system), metrics (numeric measurements over time, like request count or error rate), and logs (timestamped text records of discrete events) — together they give a complete picture of system behavior.

Telemetry data is the general term for all the information a system emits about its own behavior — this includes traces, metrics, and logs collectively.

Instrumentation is the process of adding code (or using existing libraries) to an application so that it generates telemetry data as it runs — without instrumentation, an application produces no observability data at all.

Vendor-neutral means OpenTelemetry isn’t tied to any single company’s product — the same instrumented code can send its data to many different observability backends (like Jaeger, Prometheus, or a commercial vendor) without being rewritten.

The CNCF is the open-source organization that hosts OpenTelemetry (along with other well-known projects like Kubernetes), providing neutral governance so no single company controls its direction.

These are the handful of components you’ll see referenced constantly in OpenTelemetry documentation.

The API is the set of interfaces application code uses to create telemetry data (like starting a span), without needing to know the details of how that data is actually processed or sent anywhere.

The SDK is the actual implementation behind the API — it does the real work of processing, batching, and preparing telemetry data for export, and can be configured with different settings depending on your needs.

An exporter is the component responsible for sending collected telemetry data to a specific destination or backend, such as Jaeger for traces or Prometheus for metrics.

The Collector is a standalone service that can receive, process, and forward telemetry data, acting as a flexible middle layer between your applications and your observability backends.

A receiver is the part of the Collector that accepts incoming telemetry data, supporting different formats and protocols so data from many different sources can be gathered in one place.

A processor sits between receiving and exporting data inside the Collector, performing tasks like filtering, batching, or adding extra information to telemetry data before it’s sent onward.

A pipeline is the configured path telemetry data flows through — from receivers, through one or more processors, to one or more exporters — defining exactly how data moves from your application to its final destination.

Tracing is often the most powerful pillar of observability — this chapter covers the beginner vocabulary around it.

A trace represents the complete journey of a single request as it travels through a system, potentially passing through many different services along the way.

A span represents one unit of work within a trace, such as a single function call, database query, or an HTTP request to another service — a trace is made up of one or more spans.

Span context is the information (like the trace ID and span ID) that identifies a span and allows it to be connected correctly to the rest of its trace, especially when passing between different services.

When one operation causes another to happen (like a web request triggering a database call), the resulting spans form a parent-child relationship, showing which operation caused which, and in what order.

A trace ID is a unique identifier shared by every span belonging to the same trace, which is what allows all the individual pieces of one request’s journey to be grouped back together.

A span ID is a unique identifier for one specific span, distinguishing it from every other span, even other spans within the very same trace.

Span attributes are extra key-value pieces of information attached to a span, such as the HTTP status code or the specific database table queried, adding useful context for later analysis.

Span events are timestamped notes recorded within a span’s lifetime, marking something notable that happened during that operation, such as a retry attempt or a cache miss.

flowchart TB
    A["Trace: Checkout Request"] --> B["Span: API Gateway"]
    B --> C["Span: Inventory Service"]
    B --> D["Span: Payment Service"]
    D --> E["Span: Database Query"]
    

Metrics turn system behavior into numbers you can track, graph, and alert on over time.

A metric is a numeric measurement of some aspect of your system’s behavior over time, such as the number of requests handled per minute or the current memory usage.

A counter is a metric type that only ever goes up (or resets to zero), commonly used to track things like the total number of requests processed or errors encountered.

A gauge is a metric type that can go up or down freely, representing a current value at a point in time, such as the number of active connections or current CPU usage.

A histogram records the distribution of values (like request durations) into buckets, letting you see not just an average but how values are spread out — useful for understanding response time patterns.

An UpDownCounter is a metric type similar to a counter, but that can both increase and decrease, useful for tracking values like the number of items currently in a queue.

Metric attributes are extra labels attached to a metric value, such as which endpoint or region it applies to, allowing the same overall metric to be broken down and filtered in different ways.

Logs are the most familiar pillar of observability to most developers — here’s how OpenTelemetry approaches them.

A log is a timestamped text record describing a specific event that happened in an application, such as “user logged in” or “failed to connect to database.”

A log record is OpenTelemetry’s structured representation of a single log entry, including the message, timestamp, severity level, and any additional attributes.

Structured logging means writing logs as organized data (like key-value pairs) instead of plain free-form text, which makes them much easier to search, filter, and analyze automatically.

Correlating logs with traces means attaching the relevant trace ID and span ID to each log entry, so you can jump directly from a specific log message to the exact request journey it happened during.

This chapter covers how telemetry data actually gets generated from your application code in the first place.

Auto-instrumentation automatically adds telemetry generation to common libraries and frameworks (like a web server or database client) without requiring you to manually write any tracing code yourself.

Manual instrumentation is when a developer explicitly writes code to create spans, record metrics, or emit logs at specific points in their application, giving fine control over exactly what gets captured.

An instrumentation library is a pre-built package that adds OpenTelemetry support to a specific, popular piece of software (like a particular web framework or HTTP client), so you don’t have to instrument it by hand.

Context propagation is the mechanism that carries trace information (like the trace ID) along as a request moves from one service to another, which is what allows spans in different services to be linked into one single trace.

Baggage is a way to pass custom key-value data alongside a request as it travels through a system, similar to context propagation, but meant for application-specific information rather than just trace identifiers.

The Collector deserves its own chapter — it’s the piece that connects your applications to wherever your data actually ends up.

Without a Collector, every application would need to know exactly which backend to send data to directly. The Collector centralizes that responsibility, so applications just send data to one place, and the Collector decides where it goes from there.

In agent mode, a Collector instance runs close to the application (often on the same host), collecting data locally before forwarding it onward, reducing the direct load on the application itself.

In gateway mode, a centralized Collector (or cluster of them) receives data from many agents or applications at once, applying shared processing rules before forwarding data to one or more backends.

OTLP is the standard data format and network protocol OpenTelemetry uses to send telemetry data between applications, Collectors, and backends, ensuring everything in the ecosystem can communicate consistently.

Batching groups multiple pieces of telemetry data together before sending them onward, which is more efficient than sending each individual piece of data in its own separate network request.

flowchart LR
    App1["Service A"] --> Agent1["Collector - Agent"]
    App2["Service B"] --> Agent2["Collector - Agent"]
    Agent1 --> GW["Collector - Gateway"]
    Agent2 --> GW
    GW --> Backend["Observability Backend"]
    

OpenTelemetry generates and moves data — but you still need somewhere to view and analyze it. This chapter introduces that ecosystem.

An observability backend is the system where telemetry data is stored, visualized, and analyzed — OpenTelemetry itself doesn’t provide dashboards; it focuses purely on generating and transporting the data.

Jaeger is a popular open-source backend specifically designed for storing and visualizing distributed traces, commonly used as a destination for trace data generated by OpenTelemetry.

Prometheus is a widely used open-source system for storing and querying metrics data, often used as the metrics backend in an OpenTelemetry-based observability setup.

Grafana is a visualization tool that builds dashboards and graphs from data stored in backends like Prometheus or Jaeger, giving teams a visual way to explore their telemetry data.

Vendor exporters are exporters built specifically to send OpenTelemetry data to a particular commercial observability product, letting teams use OpenTelemetry’s standard instrumentation while still sending data to their vendor of choice.

Sampling means only keeping a portion of all the traces generated, rather than every single one, which helps control data volume and cost in high-traffic systems while still preserving a representative picture of behavior.

Not strictly — an application can export data directly to a backend. However, using a Collector is generally recommended, since it decouples your application from any specific backend and centralizes processing logic.

No — OpenTelemetry generates and transports telemetry data, while tools like Jaeger and Prometheus store and visualize it. They work together rather than compete with each other.

The API is what your application code calls to create telemetry; the SDK is the actual implementation that processes and exports that data. This separation lets libraries depend only on the lightweight API without pulling in a full SDK.

Auto-instrumentation covers common libraries well, but manual instrumentation is often still needed to capture business-specific logic and custom operations that generic libraries can’t know about.

OpenTelemetry provides official SDKs for most major programming languages (including Java, Python, Go, JavaScript, and more), all following the same core concepts described in this guide.