How open-telemetry/opentelemetry-cpp works
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.