repository·main·Indexed 23 days ago
https://github.com/open-telemetry/opentelemetry-cppThe official C++ client implementation for OpenTelemetry, providing instrumentation capabilities for Logs, Metrics, and Traces. This documentation includes guides on building the library via Docker, implementing distributed tracing for HTTP and gRPC, configuring the Metrics SDK pipeline with Counters and Histograms, and managing runtime logger severity using LoggerConfigurator.
Tracer and exposes it as an OpenTracing-compatible Tracer. This is useful for migrating legacy codebases that rely on OpenTracing to OpenTelemetry without rewriting all tracing calls immediately.You can extend existing SDK classes by inheriting from them (e.g., class MyExporter : public OtlpGrpcExporter).
Warning: Extending SDK classes creates a strong dependency on the SDK's internal implementation. Because the implementation details are exposed in public headers to allow this pattern, using this approach with shared libraries is not recommended, as any change to the base class implementation will break the ABI and cause your extension to fail.
Entities defined in ABI-stable API headers—such as inline functions, templates, and inline/constexpr variables—must not change their definition or observable behavior within a stable ABI version.
If different libraries are compiled against different versions of the API, they may each carry a different definition of the same inline entity. This violates the C++ One Definition Rule and can lead to unpredictable behavior or linker errors. Any change impacting observable behavior must be guarded by the OPENTELEMETRY_ABI_VERSION_NO macro.
class Logger
{
public:
template <class... ArgumentType>
void EmitLogRecord(ArgumentType &&...args)
{
#if OPENTELEMETRY_ABI_VERSION_NO >= 2
// Behavior change added to the experimental ABI
const Severity arg_severity = detail::FindSeverityInArgs(args...);
if (arg_severity != Severity::kInvalid && !Enabled(arg_severity))
{
return;
}
nostd::unique_ptr<LogRecord> log_record = CreateLogRecord(/* context_or_span */);
#else
// Stable ABI behavior
nostd::unique_ptr<LogRecord> log_record = CreateLogRecord();
#endif
...
}
};To ensure that instrumented applications do not break when updating the library, opentelemetry-cpp uses Application Binary Interface (ABI) versioning. This allows the project to deliver breaking changes (like adding virtual methods to a class) while maintaining compatibility for older binaries.
opentelemetry::v1::...) to isolate different versions of the same symbols. This allows multiple versions of the same class to coexist in the same library.opentelemetry-cpp project. You cannot mix and match different ABI versions for different signals (traces, metrics, etc.) because of their internal interdependencies.Using clang-format is an optional way to ensure code conforms to the project style guide.
For modules that require an alternate coding style, you can place a .clang-format settings file within the local directory. A local .clang-format file takes precedence over the top-level project configuration file.
You can control the minimum severity level and the enabled/disabled state of specific loggers at runtime without restarting your application or recreating logger instances.
To do this, you must:
LoggerConfigurator on the LoggerProvider during its construction.LoggerProvider::UpdateLoggerConfigurator to apply new configurations. This method is thread-safe and automatically updates the LoggerConfig on all existing loggers.This is useful for dynamic debugging workflows, such as enabling Debug level logs for a specific library or application component only when an issue is reported, and then reverting to a Warn baseline once the issue is resolved.
To enable TLS authentication for the OtlpGrpcExporter, use SslCredentials. You can provide the client certificate via OtlpGrpcExporterOptions by specifying either:
.pem client certificate file.In the provided examples, the path to the .pem file can be passed as a command-line argument along with the collector endpoint.
The opentelemetry::plugin namespace and its associated framework for loading code from shared libraries are deprecated and will be removed after October 1st, 2026. This code was unused and is being removed to reduce maintenance costs.
There is no replacement for this API. If your code relies on opentelemetry/plugin/*.h or opentelemetry/plugin/detail/*.h, you must remove these dependencies.
OpenTelemetry C++ is designed to be portable across various platforms and supports multiple C++ standards.
Note: Supporting the C programming language is not a goal of this project.
The project is built and tested on:
OpenTelemetry C++ is designed around several core architectural principles to ensure ease of integration and flexibility:
To avoid surprises when upgrading opentelemetry-cpp, you can monitor ongoing changes through two primary artifacts:
DEPRECATED file: This file contains a list of all currently active deprecations. It is organized into sections such as Platforms, Compilers, Third party dependencies, Build tools, Build scripts, opentelemetry-cpp API, opentelemetry-cpp SDK, opentelemetry-cpp Exporter, and Documentation. You should check this file to see if any APIs you use have been marked for future removal.Deprecated label.Removal label.Note that the deprecation process primarily applies to stable parts of the code. Code marked as feature preview or experimental may change more rapidly and with little to no notice.