# open-telemetry/opentelemetry-cpp architecture

> Architecture diagram of the GitHub repository open-telemetry/opentelemetry-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-telemetry/opentelemetry-cpp
- Repository: https://github.com/open-telemetry/opentelemetry-cpp

## Overview

##### Project type and purpose
- This is a language-library project: the official C++ implementation of the OpenTelemetry client.
- Purpose: provide a set of APIs (for traces, metrics, and logs), an SDK implementation, and pluggable exporters/extensions so that instrumented applications can record telemetry and send it somewhere.

##### File structure
- Top-level “api” directory: public, header-only API definitions (interfaces for traces, metrics, logs, baggage, context propagation).
- Top-level “sdk” directory: fully featured SDK implementation of those APIs (in-memory data structures, processors, samplers, readers).
- “exporters” directory: multiple folders (otlp, zipkin, prometheus, memory, ostream, elasticsearch, etw) each implementing a concrete Exporter interface.
- “ext”: protocol-specific and platform-specific clients (e.g., HTTP curl, in-process DLL hooks).
- “opentracing-shim”: adapter layer that implements the OpenTracing interfaces on top of OpenTelemetry.
- “examples” and “functional”: demo apps illustrating how to wire API→SDK→exporter.
- “build” directories (CMakeLists.txt, Bazel BUILD files, devcontainer, docker, CI, tools): orchestrate build/test across platforms.
- “docs”: design docs, dependency and usage guides.
- “test_common”, “api/test”, “sdk/test”, “exporters/*/test”, “ext/test”: unit and integration tests validating each component.

##### README for additional insights
- Confirms three signals (logs, metrics, traces).
- Highlights support for C++14/17/20 and multi-platform builds.
- Links to examples/simple showing the common wiring: Application → API → SDK pipeline (processor + exporter) → backend.

##### Main components and their interactions
a. Components
- Application code (instrumented)
- Public API layer (header-only, namespaces: opentelemetry::trace, ::metrics, ::logs, ::baggage, ::context)
- SDK core (classes under sdk/src, factories, providers, processors, samplers, readers)
- Exporters (pluggable: OTLP gRPC/HTTP, Zipkin, Prometheus, OStream, In-Memory, ETW, Elasticsearch)
- Extensions (HTTP client, DLL instrumentation)
- Compatibility shim (OpenTracing shim)
- Build/Test/CI infrastructure (CMake/Bazel, Docker, CI workflows)

b. Relationships & data flow
1. App calls API tracer/meter/logger →
2. API delegates to SDK provider (configured via sdk_config.h or builder pattern) →
3. SDK spans/instruments/records buffered data in processors/readers →
4. Processors schedule export via Exporter interface →
5. Exporter serializes and ships telemetry over chosen protocol/format →
6. Optional Extensions support specialized transports (e.g., CURL HTTP, ETW)
7. OpenTracing-based code can route through the shim to the API layer above.

c. Architectural patterns & design principles
- Provider pattern: global tracer/meter/log provider singletons supply concrete SDK implementations.
- Pluggable exporter factory: uses factory registry to construct exporters at runtime.
- Separation of concerns: distinct layers for API, SDK, data processing, network/IO.
- Dependency inversion: SDK depends on abstract Exporter interface.
- Modularization: each exporter, extension, and test is isolated in its own sub-project.

d. Key technologies
- CMake & Bazel build systems
- gRPC & HTTP (via CURL) for OTLP exporters
- Protobuf definitions (in third_party/opentelemetry-proto)
- Native C++14+/17+/20
- Docker/CI for multi-platform testing

##### Detail amplification
- Within SDK Core, you may sub-divide:
- Trace pipeline: TracerProvider → Samplers → SpanProcessors → Exporter
- Metrics pipeline: MeterProvider → MetricReaders → Exporter
- Logs pipeline: LoggerProvider → LogProcessors → Exporter
- Around Exporter Interface, show factory registration and dynamic load in plugin cases.
- For Extensions, illustrate that HTTP exporter may call curl-based client under the hood.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application and Shim
    app["Instrumented Application"]:::external
    shim["OpenTracing Shim"]:::public
    api["API Layer\n(opentelemetry::trace/metrics/logs)"]:::public

    app -->|"calls API"| api
    shim -->|"translates OT calls"| api

    %% SDK Core
    subgraph "SDK Core" 
        direction TB
        tp["TracerProvider"]:::sdk
        sampler["Sampler"]:::sdk
        spanproc["SpanProcessor"]:::sdk
        mp["MeterProvider"]:::sdk
        mreader["MetricReader"]:::sdk
        lp["LoggerProvider"]:::sdk
        lproc["LogProcessor"]:::sdk
    end

    api -->|"get TracerProvider"| tp
    tp -->|"sample and create spans"| sampler
    sampler -->|"process spans"| spanproc
    api -->|"get MeterProvider"| mp
    mp -->|"read metrics"| mreader
    api -->|"get LoggerProvider"| lp
    lp -->|"process logs"| lproc

    %% Exporter Interfaces
    subgraph "Exporter Interfaces" 
        direction TB
        teif["Trace Exporter IF"]:::interface
        meif["Metric Reader IF"]:::interface
        leif["Log Exporter IF"]:::interface
    end

    spanproc -->|"SpanData"| teif
    mreader -->|"MetricData"| meif
    lproc -->|"LogRecord"| leif

    %% Concrete Exporters
    subgraph "Concrete Exporters & Backends" 
        direction TB
        otlp["OTLP Exporter"]:::exporter
        zipkin["Zipkin Exporter"]:::exporter
        prometheus["Prometheus Exporter"]:::exporter
        ostream["OStream Exporter"]:::exporter
        memory["In-Memory Exporter"]:::exporter
        elastic["Elasticsearch Exporter"]:::exporter
        etw["ETW Exporter"]:::exporter
        backend["Telemetry Backend\n(Collector/Server)"]:::external
    end

    teif -->|"serialize/ship"| otlp
    teif -->|"serialize/ship"| zipkin
    teif -->|"serialize/ship"| ostream
    teif -->|"serialize/ship"| memory
    teif -->|"serialize/ship"| elastic
    teif -->|"serialize/ship"| etw

    meif -->|"export metrics"| prometheus
    leif -->|"export logs"| otlp

    otlp -->|"gRPC/HTTP"| backend
    zipkin -->|"HTTP"| backend
    prometheus -->|"scrape"| backend
    ostream -->|"stdout"| backend
    memory -->|"in-memory view"| backend
    elastic -->|"HTTP"| backend
    etw -->|"ETW trace"| backend

    %% Extensions
    ext["Extensions\n(HTTP/CURL, DLL)"]:::exporter
    ext -->|"provides transport"| otlp
    ext -->|"provides transport"| zipkin

    %% Build and CI
    subgraph "Build/Test/CI Infrastructure" 
        direction TB
        build["CMake & Build Tools"]:::infra
        ci["CI Workflows & Scripts"]:::infra
    end
    build --> ci

    %% Legend
    subgraph Legend
        direction TB
        A["Blue: Public API/Shim"]:::public
        B["Green: SDK Core"]:::sdk
        C["Orange: Exporters/Extensions"]:::exporter
        D["Gray: Infra"]:::infra
    end

    %% Click Events
    click api "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/api/"
    click shim "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/opentracing-shim/"
    click tp "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/sdk/src/"
    click teif "https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/exporter.h"
    click meif "https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/metrics/export/metric_reader.h"
    click leif "https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/logs/exporter.h"
    click otlp "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/otlp/"
    click zipkin "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/zipkin/"
    click prometheus "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/prometheus/"
    click ostream "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/ostream/"
    click memory "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/memory/"
    click elastic "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/elasticsearch/"
    click etw "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/exporters/etw/"
    click ext "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/ext/"
    click build "https://github.com/open-telemetry/opentelemetry-cpp/blob/main/CMakeLists.txt"
    click ci "https://github.com/open-telemetry/opentelemetry-cpp/tree/main/.github/workflows/"

    %% Styles
    classDef public fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef sdk fill:#90EE90,stroke:#000,stroke-width:1px
    classDef interface fill:#FFD700,stroke:#000,stroke-width:1px
    classDef exporter fill:#FFA500,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
