5.3 KiB
OpenTelemetry Overview
Source: https://raw.githubusercontent.com/open-telemetry/opentelemetry-specification/main/specification/overview.md Downloaded: 2026-06-07
This document provides an overview of the OpenTelemetry project and defines important fundamental terms.
OpenTelemetry Client Architecture
At the highest architectural level, OpenTelemetry clients are organized into signals. Each signal provides a specialized form of observability. For example, tracing, metrics, and baggage are three separate signals. Signals share a common subsystem – context propagation – but they function independently from each other.
Each signal consists of four types of packages: API, SDK, Semantic Conventions, and Contrib.
API
API packages consist of the cross-cutting public interfaces used for instrumentation. Any portion of an OpenTelemetry client which is imported into third-party libraries and application code is considered part of the API.
SDK
The SDK is the implementation of the API provided by the OpenTelemetry project. Within an application, the SDK is installed and managed by the application owner.
Semantic Conventions
The Semantic Conventions define the keys and values which describe commonly observed concepts, protocols, and operations used by applications.
Semantic Conventions are now located in their own repository: https://github.com/open-telemetry/semantic-conventions
Contrib Packages
The OpenTelemetry project maintains integrations with popular OSS projects. API Contrib refers to packages which depend solely upon the API; SDK Contrib refers to packages which also depend upon the SDK.
Tracing Signal
A distributed trace is a set of events, triggered as a result of a single logical operation, consolidated across various components of an application.
Traces
Traces in OpenTelemetry are defined implicitly by their Spans. A Trace can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship.
Causal relationships between Spans in a single Trace
[Span A] (the root span)
|
+------+------+
| |
[Span B] [Span C]
| |
[Span D] +---+-------+
| |
[Span E] [Span F]
Spans
A span represents an operation within a transaction. Each Span encapsulates:
- An operation name
- A start and finish timestamp
- Attributes: A list of key-value pairs
- A set of zero or more Events
- Parent's Span identifier
- Links to zero or more causally-related Spans
- SpanContext information
SpanContext
Represents all the information that identifies Span in the Trace:
- TraceId - 16 randomly generated bytes, worldwide unique
- SpanId - 8 randomly generated bytes, globally unique
- TraceFlags - 1 byte bitmap (includes sampling bit)
- Tracestate - tracing-system specific context in key-value pairs
Metric Signal
OpenTelemetry allows recording raw measurements or metrics with predefined aggregations and a set of attributes.
Instruments
Instruments are used to report Measurements, identified by a name, kind, description, and unit of values. Types include counters, gauges, and histograms. Instruments can be synchronous or asynchronous.
Log Signal
Data model
Log Data Model defines how logs and events are understood by OpenTelemetry.
Baggage Signal
OpenTelemetry provides a simple mechanism for propagating name/value pairs, called Baggage. Baggage is intended for indexing observability events in one service with attributes provided by a prior service in the same transaction.
Resources
Resource captures information about the entity for which telemetry is recorded. For example, metrics exposed by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name.
Context Propagation
All of OpenTelemetry cross-cutting concerns share an underlying Context mechanism for storing state and accessing data across the lifespan of a distributed transaction.
Propagators
OpenTelemetry uses Propagators to serialize and deserialize cross-cutting concern values such as Spans and Baggage.
The Propagators API currently defines one Propagator type:
TextMapPropagatorinjects values into and extracts values from carriers as text.
Collector
The OpenTelemetry Collector is a set of components that can collect traces, metrics and other telemetry data from processes instrumented by OpenTelemetry or other monitoring/tracing libraries (Jaeger, Prometheus, etc.), do aggregation and smart sampling, and export traces and metrics to one or more monitoring/tracing backends.
The OpenTelemetry Collector has two primary modes of operation: Agent (a daemon running locally with the application) and Collector (a standalone running service).
Instrumentation Libraries
A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.
For instrumentation hosted in OpenTelemetry repositories, the recommendation is to prefix packages with "opentelemetry-instrumentation", followed by the instrumented library name. Examples:
- opentelemetry-instrumentation-flask (Python)
- @opentelemetry/instrumentation-grpc (JavaScript)