# 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 `Measurement`s, 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](logs/data-model.md) 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 `Span`s and `Baggage`.

The Propagators API currently defines one `Propagator` type:

- `TextMapPropagator` injects 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)