OpenTelemetry C++

Overview

The OpenTelemetry C++ API enables developers to instrument their applications and libraries in order to make them ready to create and emit telemetry data. The OpenTelemetry C++ API exclusively focuses on instrumentation and does not address concerns like exporting, sampling, and aggregating telemetry data. Those concerns are addressed by the OpenTelemetry C++ SDK. This architecture enables developers to instrument applications and libraries with the OpenTelemetry C++ API while being completely agnostic of how telemetry data is exported and processed.

Library design

The OpenTelemetry C++ API is provided as a header-only library and supports all recent versions of the C++ standard, down to C++11.

A single application might dynamically or statically link to different libraries that were compiled with different compilers, while several of the linked libraries are instrumented with OpenTelemetry. OpenTelemetry C++ supports those scenarios by providing a stable ABI. This is achieved by a careful API design, and most notably by providing ABI stable versions of classes from the standard library. All those classes are provided in the opentelemetry::nostd namespace.

Getting started

Tracing

When instrumenting libraries and applications, the most simple approach requires three steps.

Obtain a tracer

auto provider = opentelemetry::trace::Provider::GetTracerProvider();
auto tracer = provider->GetTracer("foo_library", "1.0.0");

The TracerProvider acquired in the first step is a singleton object that is usually provided by the OpenTelemetry C++ SDK. It is used to provide specific implementations for API interfaces. In case no SDK is used, the API provides a default no-op implementation of a TracerProvider.

The Tracer acquired in the second step is needed to create and start Spans.

Start a span

auto span = tracer->StartSpan("HandleRequest");

This creates a span, sets its name to "HandleRequest", and sets its start time to the current time. Refer to the API documentation for other operations that are available to enrich spans with additional data.

Mark a span as active

auto scope = tracer->WithActiveSpan(span);

This marks a span as active and returns a Scope object bound to the lifetime of the span. When the Scope object is destroyed, the related span is ended.

The concept of an active span is important, as any span that is created without explicitly specifying a parent is parented to the currently active span. A span without a parent is called root span.

Create nested Spans

auto outer_span = tracer->StartSpan("Outer operation");
auto outer_scope = tracer->WithActiveSpan(outer_span);
{
    auto inner_span = tracer->StartSpan("Inner operation");
    auto inner_scope = tracer->WithActiveSpan(inner_span);
    // ... perform inner operation
    inner_span->End();
}
// ... perform outer operation
outer_span->End();

Spans can be nested, and have a parent-child relationship with other spans. When a given span is active, the newly created span inherits the active span’s trace ID, and other context attributes.

Context Propagation

// set global propagator
opentelemetry::context::propagation::GlobalTextMapPropagator::SetGlobalPropagator(
    nostd::shared_ptr<opentelemetry::context::propagation::TextMapPropagator>(
        new opentelemetry::trace::propagation::HttpTraceContext()));

// get global propagator
HttpTextMapCarrier<opentelemetry::ext::http::client::Headers> carrier;
auto propagator =
    opentelemetry::context::propagation::GlobalTextMapPropagator::GetGlobalPropagator();

//inject context to headers
auto current_ctx = opentelemetry::context::RuntimeContext::GetCurrent();
propagator->Inject(carrier, current_ctx);

//Extract headers to context
auto current_ctx = opentelemetry::context::RuntimeContext::GetCurrent();
auto new_context = propagator->Extract(carrier, current_ctx);
auto remote_span = opentelemetry::trace::propagation::GetSpan(new_context);

Context contains the meta-data of the currently active Span including Span Id, Trace Id, and flags. Context Propagation is an important mechanism in distributed tracing to transfer this Context across service boundary often through HTTP headers. OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.

Reference documentation

Full API

Namespaces

Namespace opentelemetry::baggage
Classes

Classes and Structs

Struct EndSpanOptions
Struct Documentation
struct opentelemetry::trace::EndSpanOptions

StartEndOptions provides options to set properties of a Span when it is ended.

Public Members

common::SteadyTimestamp end_steady_time
Struct StartSpanOptions
Struct Documentation
struct opentelemetry::trace::StartSpanOptions

StartSpanOptions provides options to set properties of a Span at the time of its creation

Public Members

common::SystemTimestamp start_system_time
common::SteadyTimestamp start_steady_time
SpanContext parent = SpanContext::GetInvalid()
SpanKind kind = SpanKind::kInternal
Class Baggage
Class Documentation
class opentelemetry::baggage::Baggage

Public Functions

inline Baggage()
inline Baggage(size_t size)
template<class T>
inline Baggage(const T &keys_and_values)
inline bool GetValue(nostd::string_view key, std::string &value) const
inline nostd::shared_ptr<Baggage> Set(const nostd::string_view &key, const nostd::string_view &value)
inline bool GetAllEntries(nostd::function_ref<bool(nostd::string_view, nostd::string_view)> callback) const noexcept
inline nostd::shared_ptr<Baggage> Delete(nostd::string_view key)
inline std::string ToHeader() const

Public Static Functions

static inline nostd::shared_ptr<Baggage> GetDefault()
static inline nostd::shared_ptr<Baggage> FromHeader(nostd::string_view header)

Public Static Attributes

static constexpr size_t kMaxKeyValuePairs = 180
static constexpr size_t kMaxKeyValueSize = 4096
static constexpr size_t kMaxSize = 8192
static constexpr char kKeyValueSeparator = '='
static constexpr char kMembersSeparator = ','
static constexpr char kMetadataSeparator = ';'
Class BaggagePropagator
Inheritance Relationships
Base Type

  • public opentelemetry::context::propagation::TextMapPropagator

Class Documentation
class opentelemetry::baggage::propagation::BaggagePropagator : public opentelemetry::context::propagation::TextMapPropagator

Public Functions

inline void Inject(context::propagation::TextMapCarrier &carrier, const context::Context &context) noexcept override
inline context::Context Extract(const context::propagation::TextMapCarrier &carrier, context::Context &context) noexcept override
Class KeyValueIterable
Class Documentation
class opentelemetry::common::KeyValueIterable

Supports internal iteration over a collection of key-value pairs.

Public Functions

virtual ~KeyValueIterable() = default
virtual bool ForEachKeyValue(nostd::function_ref<bool(nostd::string_view, common::AttributeValue)> callback) const noexcept = 0

Iterate over key-value pairs

Parameters

callback – a callback to invoke for each key-value. If the callback returns false, the iteration is aborted.

Returns

true if every key-value pair was iterated over

virtual size_t size() const noexcept = 0
Returns

the number of key-value pairs

Class SteadyTimestamp
Class Documentation
class opentelemetry::common::SteadyTimestamp

A timepoint relative to the monotonic clock epoch.

This is used for calculating the duration of an operation.

Public Functions

inline SteadyTimestamp() noexcept

Initializes a monotonic timestamp pointing to the start of the epoch.

template<class Rep, class Period>
inline explicit SteadyTimestamp(const std::chrono::duration<Rep, Period> &time_since_epoch) noexcept

Initializes a monotonic timestamp from a duration.

Parameters

time_since_epoch – Time elapsed since the beginning of the epoch.

inline SteadyTimestamp(const std::chrono::steady_clock::time_point &time_point) noexcept

Initializes a monotonic timestamp based on a point in time.

Parameters

time_point – A point in time.

inline operator std::chrono::steady_clock::time_point() const noexcept

Returns a time point for the time stamp.

Returns

A time point corresponding to the time stamp.

inline std::chrono::nanoseconds time_since_epoch() const noexcept

Returns the nanoseconds since the beginning of the epoch.

Returns

Elapsed nanoseconds since the beginning of the epoch for this timestamp.

inline bool operator==(const SteadyTimestamp &other) const noexcept

Compare two steady time stamps.

Returns

true if the two time stamps are equal.

inline bool operator!=(const SteadyTimestamp &other) const noexcept

Compare two steady time stamps for inequality.

Returns

true if the two time stamps are not equal.

Class SystemTimestamp
Class Documentation
class opentelemetry::common::SystemTimestamp

A timepoint relative to the system clock epoch.

This is used for marking the beginning and end of an operation.

Public Functions

inline SystemTimestamp() noexcept

Initializes a system timestamp pointing to the start of the epoch.

template<class Rep, class Period>
inline explicit SystemTimestamp(const std::chrono::duration<Rep, Period> &time_since_epoch) noexcept

Initializes a system timestamp from a duration.

Parameters

time_since_epoch – Time elapsed since the beginning of the epoch.

inline SystemTimestamp(const std::chrono::system_clock::time_point &time_point) noexcept

Initializes a system timestamp based on a point in time.

Parameters

time_point – A point in time.

inline operator std::chrono::system_clock::time_point() const noexcept

Returns a time point for the time stamp.

Returns

A time point corresponding to the time stamp.

inline std::chrono::nanoseconds time_since_epoch() const noexcept

Returns the nanoseconds since the beginning of the epoch.

Returns

Elapsed nanoseconds since the beginning of the epoch for this timestamp.

inline bool operator==(const SystemTimestamp &other) const noexcept

Compare two steady time stamps.

Returns

true if the two time stamps are equal.

inline bool operator!=(const SystemTimestamp &other) const noexcept

Compare two steady time stamps for inequality.

Returns

true if the two time stamps are not equal.

Class Context
Class Documentation
class opentelemetry::context::Context

Public Functions

Context() = default
template<class T>
inline Context(const T &keys_and_values)
inline Context(nostd::string_view key, ContextValue value)
template<class T>
inline Context SetValues(T &values) noexcept
inline Context SetValue(nostd::string_view key, ContextValue value) noexcept
inline context::ContextValue GetValue(const nostd::string_view key) const noexcept
inline bool HasKey(const nostd::string_view key) const noexcept
inline bool operator==(const Context &other) const noexcept
Class CompositePropagator
Inheritance Relationships
Base Type

  • public opentelemetry::context::propagation::TextMapPropagator

Class Documentation
class opentelemetry::context::propagation::CompositePropagator : public opentelemetry::context::propagation::TextMapPropagator

Public Functions

inline CompositePropagator(std::vector<std::unique_ptr<TextMapPropagator>> propagators)
inline void Inject(TextMapCarrier &carrier, const context::Context &context) noexcept override

Run each of the configured propagators with the given context and carrier. Propagators are run in the order they are configured, so if multiple propagators write the same carrier key, the propagator later in the list will “win”.

Parameters

  • carrier – Carrier into which context will be injected

  • context – Context to inject

inline context::Context Extract(const TextMapCarrier &carrier, context::Context &context) noexcept override

Run each of the configured propagators with the given context and carrier. Propagators are run in the order they are configured, so if multiple propagators write the same context key, the propagator later in the list will “win”.

Parameters

  • carrier – Carrier from which to extract context

  • context – Context to add values to

Class GlobalTextMapPropagator
Class Documentation
class opentelemetry::context::propagation::GlobalTextMapPropagator

Public Static Functions

static inline nostd::shared_ptr<TextMapPropagator> GetGlobalPropagator() noexcept
static inline void SetGlobalPropagator(nostd::shared_ptr<TextMapPropagator> prop) noexcept
Class NoOpPropagator
Inheritance Relationships
Base Type

  • public opentelemetry::context::propagation::TextMapPropagator

Class Documentation
class opentelemetry::context::propagation::NoOpPropagator : public opentelemetry::context::propagation::TextMapPropagator

No-op implementation TextMapPropagator

Public Functions

inline context::Context Extract(const TextMapCarrier&, context::Context &context) noexcept override

Noop extract function does nothing and returns the input context

inline void Inject(TextMapCarrier&, const context::Context &context) noexcept override

Noop inject function does nothing

Class TextMapCarrier
Class Documentation
class opentelemetry::context::propagation::TextMapCarrier

Public Functions

virtual nostd::string_view Get(nostd::string_view key) const noexcept = 0
virtual void Set(nostd::string_view key, nostd::string_view value) noexcept = 0
Class TextMapPropagator
Inheritance Relationships
Derived Types
Class Documentation
class opentelemetry::context::propagation::TextMapPropagator

Subclassed by opentelemetry::baggage::propagation::BaggagePropagator, opentelemetry::context::propagation::CompositePropagator, opentelemetry::context::propagation::NoOpPropagator, opentelemetry::trace::propagation::B3PropagatorExtractor, opentelemetry::trace::propagation::HttpTraceContext, opentelemetry::trace::propagation::JaegerPropagator

Public Functions

virtual context::Context Extract(const TextMapCarrier &carrier, context::Context &context) noexcept = 0
virtual void Inject(TextMapCarrier &carrier, const context::Context &context) noexcept = 0
Class RuntimeContext
Class Documentation
class opentelemetry::context::RuntimeContext

Public Static Functions

static inline Context GetCurrent() noexcept
static inline nostd::unique_ptr<Token> Attach(const Context &context) noexcept
static inline bool Detach(Token &token) noexcept
static inline Context SetValue(nostd::string_view key, const ContextValue &value, Context *context = nullptr) noexcept
static inline ContextValue GetValue(nostd::string_view key, Context *context = nullptr) noexcept
static inline void SetRuntimeContextStorage(nostd::shared_ptr<RuntimeContextStorage> storage) noexcept

Provide a custom runtime context storage.

This provides a possibility to override the default thread-local runtime context storage. This has to be set before any spans are created by the application, otherwise the behavior is undefined.

Parameters

storage – a custom runtime context storage

Class RuntimeContextStorage
Inheritance Relationships
Derived Type
Class Documentation
class opentelemetry::context::RuntimeContextStorage

RuntimeContextStorage is used by RuntimeContext to store Context frames.

Custom context management strategies can be implemented by deriving from this class and passing an initialized RuntimeContextStorage object to RuntimeContext::SetRuntimeContextStorage.

Subclassed by opentelemetry::context::ThreadLocalContextStorage

Public Functions

virtual Context GetCurrent() noexcept = 0

Return the current context.

Returns

the current context

virtual nostd::unique_ptr<Token> Attach(const Context &context) noexcept = 0

Set the current context.

Parameters

the – new current context

Returns

a token for the new current context. This never returns a nullptr.

virtual bool Detach(Token &token) noexcept = 0

Detach the context related to the given token.

Parameters

token – a token related to a context

Returns

true if the context could be detached

inline virtual ~RuntimeContextStorage()

Protected Functions

inline nostd::unique_ptr<Token> CreateToken(const Context &context) noexcept
Class ThreadLocalContextStorage
Inheritance Relationships
Base Type
Class Documentation
class opentelemetry::context::ThreadLocalContextStorage : public opentelemetry::context::RuntimeContextStorage

Public Functions

ThreadLocalContextStorage() noexcept = default
inline Context GetCurrent() noexcept override
inline bool Detach(Token &token) noexcept override
inline nostd::unique_ptr<Token> Attach(const Context &context) noexcept override
Class Token
Class Documentation
class opentelemetry::context::Token

Public Functions

inline bool operator==(const Context &other) const noexcept
inline ~Token()
Class DefaultSpan
Inheritance Relationships
Base Type
Class Documentation
class opentelemetry::trace::DefaultSpan : public opentelemetry::trace::Span

Public Functions

inline trace::SpanContext GetContext() const noexcept
inline bool IsRecording() const noexcept
inline void SetAttribute(nostd::string_view, const common::AttributeValue&) noexcept
inline void AddEvent(nostd::string_view) noexcept
inline void AddEvent(nostd::string_view, common::SystemTimestamp) noexcept
inline void AddEvent(nostd::string_view, common::SystemTimestamp, const common::KeyValueIterable&) noexcept
inline void AddEvent(nostd::string_view name, const common::KeyValueIterable &attributes) noexcept
inline void SetStatus(StatusCode, nostd::string_view) noexcept
inline void UpdateName(nostd::string_view) noexcept
inline void End(const EndSpanOptions& = {}) noexcept
inline nostd::string_view ToString()
inline DefaultSpan(SpanContext span_context)
inline DefaultSpan(DefaultSpan &&spn)
inline DefaultSpan(const DefaultSpan &spn)

Public Static Functions

static inline DefaultSpan GetInvalid()
Class DefaultTracer
Inheritance Relationships
Base Type
Class Documentation
class opentelemetry::trace::DefaultTracer : public opentelemetry::trace::Tracer

Public Functions

~DefaultTracer() = default
inline nostd::unique_ptr< Span > StartSpan (nostd::string_view name, const common::KeyValueIterable &attributes, const StartSpanOptions &options={}) override noexcept

Starts a span.

Optionally sets attributes at Span creation from the given key/value pairs.

Attributes will be processed in order, previous attributes with the same key will be overwritten.

inline void ForceFlushWithMicroseconds (uint64_t timeout) override noexcept
inline void CloseWithMicroseconds (uint64_t timeout) override noexcept
Class NoopSpan
Inheritance Relationships
Base Type
Class Documentation
class opentelemetry::trace::NoopSpan : public opentelemetry::trace::Span

No-op implementation of Span. This class should not be used directly.

Public Functions

inline explicit NoopSpan(const std::shared_ptr<Tracer> &tracer) noexcept
inline virtual void SetAttribute(nostd::string_view, const common::AttributeValue&) noexcept override
inline virtual void AddEvent(nostd::string_view) noexcept override
inline virtual void AddEvent(nostd::string_view, common::SystemTimestamp) noexcept override
inline virtual void AddEvent(nostd::string_view, common::SystemTimestamp, const common::KeyValueIterable&) noexcept override
inline virtual void SetStatus(StatusCode, nostd::string_view) noexcept override
inline virtual void UpdateName(nostd::string_view) noexcept override
inline virtual void End(const EndSpanOptions&) noexcept override

Mark the end of the Span. Only the timing of the first End call for a given Span will be recorded, and implementations are free to ignore all further calls.

Parameters

options – can be used to manually define span properties like the end timestamp

inline virtual bool IsRecording() const noexcept override
inline virtual SpanContext GetContext() const noexcept override
Class NoopTracer
Inheritance Relationships
Base Types

  • public opentelemetry::trace::Tracer (Class Tracer)

  • public std::enable_shared_from_this< NoopTracer >

Class Documentation
class opentelemetry::trace::NoopTracer : public opentelemetry::trace::Tracer, public std::enable_shared_from_this<NoopTracer>

No-op implementation of Tracer.

Public Functions

inline virtual nostd::shared_ptr<Span> StartSpan(nostd::string_view, const common::KeyValueIterable&, const SpanContextKeyValueIterable&, const StartSpanOptions&) noexcept override

Starts a span.

Optionally sets attributes at Span creation from the given key/value pairs.

Attributes will be processed in order, previous attributes with the same key will be overwritten.

inline virtual void ForceFlushWithMicroseconds(uint64_t) noexcept override
inline virtual void CloseWithMicroseconds(uint64_t) noexcept override
Class NoopTracerProvider
Inheritance Relationships
Base Type
Class Documentation
class opentelemetry::trace::NoopTracerProvider : public opentelemetry::trace::TracerProvider

No-op implementation of a TracerProvider.

Public Functions

inline NoopTracerProvider()
inline virtual nostd::shared_ptr<opentelemetry::trace::Tracer> GetTracer(nostd::string_view library_name, nostd::string_view library_version) override

Gets or creates a named tracer instance.

Optionally a version can be passed to create a named and versioned tracer instance.

Class NullSpanContext
Inheritance Relationships
Base Type
Class Documentation
class opentelemetry::trace::NullSpanContext : public opentelemetry::trace::SpanContextKeyValueIterable

Null Span context that does not carry any information.

Public Functions

inline virtual bool ForEachKeyValue(nostd::function_ref<bool(SpanContext, const opentelemetry::common::KeyValueIterable&)>) const noexcept override

Iterate over SpanContext/key-value pairs

Parameters

callback – a callback to invoke for each key-value for each SpanContext. If the callback returns false, the iteration is aborted.

Returns

true if every SpanContext/key-value pair was iterated over

inline virtual size_t size() const noexcept override
Returns

the number of key-value pairs

Class B3Propagator
Inheritance Relationships
Base Type

  • public opentelemetry::trace::propagation::B3PropagatorExtractor

Class Documentation
class opentelemetry::trace::propagation::B3Propagator : public opentelemetry::trace::propagation::B3PropagatorExtractor

Public Functions

inline void Inject(opentelemetry::context::propagation::TextMapCarrier &carrier, const context::Context &context) noexcept override
Class B3PropagatorExtractor
Inheritance Relationships
Base Type

  • public opentelemetry::context::propagation::TextMapPropagator

Derived Types
Class Documentation
class opentelemetry::trace::propagation::B3PropagatorExtractor : public opentelemetry::context::propagation::TextMapPropagator

Subclassed by opentelemetry::trace::propagation::B3Propagator, opentelemetry::trace::propagation::B3PropagatorMultiHeader

Public Functions

inline context::Context Extract(const opentelemetry::context::propagation::TextMapCarrier &carrier, context::Context &context) noexcept override

Public Static Functions

static inline TraceId TraceIdFromHex(nostd::string_view trace_id)
static inline SpanId SpanIdFromHex(nostd::string_view span_id)
static inline TraceFlags TraceFlagsFromHex(nostd::string_view trace_flags)
Class B3PropagatorMultiHeader
Inheritance Relationships
Base Type

  • public opentelemetry::trace::propagation::B3PropagatorExtractor

Class Documentation
class opentelemetry::trace::propagation::B3PropagatorMultiHeader : public opentelemetry::trace::propagation::B3PropagatorExtractor

Public Functions

inline void Inject(opentelemetry::context::propagation::TextMapCarrier &carrier, const context::Context &context) noexcept override
Class HttpTraceContext
Inheritance Relationships
Base Type

  • public opentelemetry::context::propagation::TextMapPropagator

Class Documentation
class opentelemetry::trace::propagation::HttpTraceContext : public opentelemetry::context::propagation::TextMapPropagator

Public Functions

inline void Inject(opentelemetry::context::propagation::TextMapCarrier &carrier, const context::Context &context) noexcept override
inline context::Context Extract(const opentelemetry::context::propagation::TextMapCarrier &carrier, context::Context &context) noexcept override

Public Static Functions

static inline TraceId TraceIdFromHex(nostd::string_view trace_id)
static inline SpanId SpanIdFromHex(nostd::string_view span_id)
static inline TraceFlags TraceFlagsFromHex(nostd::string_view trace_flags)
Class JaegerPropagator
Inheritance Relationships
Base Type

  • public opentelemetry::context::propagation::TextMapPropagator

Class Documentation
class opentelemetry::trace::propagation::JaegerPropagator : public opentelemetry::context::propagation::TextMapPropagator

Public Functions

inline void Inject(context::propagation::TextMapCarrier &carrier, const context::Context &context) noexcept override
inline context::Context Extract(const context::propagation::TextMapCarrier &carrier, context::Context &context) noexcept override
Class Provider
Class Documentation
class opentelemetry::trace::Provider

Stores the singleton global TracerProvider.

Public Static Functions

static inline nostd::shared_ptr<TracerProvider> GetTracerProvider() noexcept

Returns the singleton TracerProvider.

By default, a no-op TracerProvider is returned. This will never return a nullptr TracerProvider.

static inline void SetTracerProvider(nostd::shared_ptr<TracerProvider> tp) noexcept

Changes the singleton TracerProvider.

Class Scope
Class Documentation
class opentelemetry::trace::Scope

Controls how long a span is active.

On creation of the Scope object, the given span is set to the currently active span. On destruction, the given span is ended and the previously active span will be the currently active span again.

Public Functions

inline Scope(const nostd::shared_ptr<Span> &span) noexcept

Initialize a new scope.

Parameters

span – the given span will be set as the currently active span.

Class Span
Inheritance Relationships
Derived Types
Class Documentation
class opentelemetry::trace::Span

A Span represents a single operation within a Trace.

Subclassed by opentelemetry::trace::DefaultSpan, opentelemetry::trace::NoopSpan

Public Functions

Span() = default
virtual ~Span() = default
Span(const Span&) = delete
Span(Span&&) = delete
Span &operator=(const Span&) = delete
Span &operator=(Span&&) = delete
virtual void SetAttribute(nostd::string_view key, const common::AttributeValue &value) noexcept = 0
virtual void AddEvent(nostd::string_view name) noexcept = 0
virtual void AddEvent(nostd::string_view name, common::SystemTimestamp timestamp) noexcept = 0
virtual void AddEvent(nostd::string_view name, common::SystemTimestamp timestamp, const common::KeyValueIterable &attributes) noexcept = 0
inline virtual void AddEvent(nostd::string_view name, const common::KeyValueIterable &attributes) noexcept
template<class T, nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value>* = nullptr>
inline void AddEvent(nostd::string_view name, common::SystemTimestamp timestamp, const T &attributes) noexcept
template<class T, nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value>* = nullptr>
inline void AddEvent(nostd::string_view name, const T &attributes) noexcept
inline void AddEvent(nostd::string_view name, common::SystemTimestamp timestamp, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes) noexcept
inline void AddEvent(nostd::string_view name, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes) noexcept
virtual void SetStatus(StatusCode code, nostd::string_view description = "") noexcept = 0
virtual void UpdateName(nostd::string_view name) noexcept = 0
virtual void End(const EndSpanOptions &options = {}) noexcept = 0

Mark the end of the Span. Only the timing of the first End call for a given Span will be recorded, and implementations are free to ignore all further calls.

Parameters

options – can be used to manually define span properties like the end timestamp

virtual trace::SpanContext GetContext() const noexcept = 0
virtual bool IsRecording() const noexcept = 0
Class SpanContext
Class Documentation
class opentelemetry::trace::SpanContext

Public Functions

inline SpanContext(bool sampled_flag, bool is_remote)
inline SpanContext(TraceId trace_id, SpanId span_id, TraceFlags trace_flags, bool is_remote, nostd::shared_ptr<TraceState> trace_state = TraceState::GetDefault()) noexcept
SpanContext(const SpanContext &ctx) = default
inline bool IsValid() const noexcept
inline const trace_api::TraceFlags &trace_flags() const noexcept
inline const trace_api::TraceId &trace_id() const noexcept
inline const trace_api::SpanId &span_id() const noexcept
inline const nostd::shared_ptr<trace_api::TraceState> trace_state() const noexcept
inline bool operator==(const SpanContext &that) const noexcept
SpanContext &operator=(const SpanContext &ctx) = default
inline bool IsRemote() const noexcept
inline bool IsSampled() const noexcept

Public Static Functions

static inline SpanContext GetInvalid()
Class SpanContextKeyValueIterable
Inheritance Relationships
Derived Type
Class Documentation
class opentelemetry::trace::SpanContextKeyValueIterable

Supports internal iteration over a collection of SpanContext/key-value pairs.

Subclassed by opentelemetry::trace::NullSpanContext

Public Functions

virtual ~SpanContextKeyValueIterable() = default
virtual bool ForEachKeyValue(nostd::function_ref<bool(SpanContext, const opentelemetry::common::KeyValueIterable&)> callback) const noexcept = 0

Iterate over SpanContext/key-value pairs

Parameters

callback – a callback to invoke for each key-value for each SpanContext. If the callback returns false, the iteration is aborted.

Returns

true if every SpanContext/key-value pair was iterated over

virtual size_t size() const noexcept = 0
Returns

the number of key-value pairs

Class SpanId
Class Documentation
class opentelemetry::trace::SpanId

Public Functions

inline SpanId() noexcept
inline explicit SpanId(nostd::span<const uint8_t, kSize> id) noexcept
inline void ToLowerBase16(nostd::span<char, 2 * kSize> buffer) const noexcept
inline nostd::span<const uint8_t, kSize> Id() const noexcept
inline bool operator==(const SpanId &that) const noexcept
inline bool operator!=(const SpanId &that) const noexcept
inline bool IsValid() const noexcept
inline void CopyBytesTo(nostd::span<uint8_t, kSize> dest) const noexcept

Public Static Attributes

static constexpr int kSize = 8
Class TraceFlags
Class Documentation
class opentelemetry::trace::TraceFlags

Public Functions

inline TraceFlags() noexcept
inline explicit TraceFlags(uint8_t flags) noexcept
inline bool IsSampled() const noexcept
inline void ToLowerBase16(nostd::span<char, 2> buffer) const noexcept
inline uint8_t flags() const noexcept
inline bool operator==(const TraceFlags &that) const noexcept
inline bool operator!=(const TraceFlags &that) const noexcept
inline void CopyBytesTo(nostd::span<uint8_t, 1> dest) const noexcept

Public Static Attributes

static constexpr uint8_t kIsSampled = 1
Class TraceId
Class Documentation
class opentelemetry::trace::TraceId

Public Functions

inline TraceId() noexcept
inline explicit TraceId(nostd::span<const uint8_t, kSize> id) noexcept
inline void ToLowerBase16(nostd::span<char, 2 * kSize> buffer) const noexcept
inline nostd::span<const uint8_t, kSize> Id() const noexcept
inline bool operator==(const TraceId &that) const noexcept
inline bool operator!=(const TraceId &that) const noexcept
inline bool IsValid() const noexcept
inline void CopyBytesTo(nostd::span<uint8_t, kSize> dest) const noexcept

Public Static Attributes

static constexpr int kSize = 16
Class Tracer
Inheritance Relationships
Derived Types
Class Documentation
class opentelemetry::trace::Tracer

Handles span creation and in-process context propagation.

This class provides methods for manipulating the context, creating spans, and controlling spans’ lifecycles.

Subclassed by opentelemetry::trace::DefaultTracer, opentelemetry::trace::NoopTracer

Public Functions

virtual ~Tracer() = default
virtual nostd::shared_ptr<Span> StartSpan(nostd::string_view name, const common::KeyValueIterable &attributes, const SpanContextKeyValueIterable &links, const StartSpanOptions &options = {}) noexcept = 0

Starts a span.

Optionally sets attributes at Span creation from the given key/value pairs.

Attributes will be processed in order, previous attributes with the same key will be overwritten.

inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, const StartSpanOptions &options = {}) noexcept
template<class T, nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value>* = nullptr>
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, const T &attributes, const StartSpanOptions &options = {}) noexcept
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, const common::KeyValueIterable &attributes, const StartSpanOptions &options = {}) noexcept
template<class T, class U, nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value>* = nullptr, nostd::enable_if_t<detail::is_span_context_kv_iterable<U>::value>* = nullptr>
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, const T &attributes, const U &links, const StartSpanOptions &options = {}) noexcept
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes, const StartSpanOptions &options = {}) noexcept
template<class T, nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value>* = nullptr>
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, const T &attributes, std::initializer_list<std::pair<SpanContext, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>> links, const StartSpanOptions &options = {}) noexcept
template<class T, nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value>* = nullptr>
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes, const T &links, const StartSpanOptions &options = {}) noexcept
inline nostd::shared_ptr<Span> StartSpan(nostd::string_view name, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes, std::initializer_list<std::pair<SpanContext, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>> links, const StartSpanOptions &options = {}) noexcept
template<class Rep, class Period>
inline void ForceFlush(std::chrono::duration<Rep, Period> timeout) noexcept

Force any buffered spans to flush.

Parameters

timeout – to complete the flush

virtual void ForceFlushWithMicroseconds(uint64_t timeout) noexcept = 0
template<class Rep, class Period>
inline void Close(std::chrono::duration<Rep, Period> timeout) noexcept

ForceFlush any buffered spans and stop reporting spans.

Parameters

timeout – to complete the flush

virtual void CloseWithMicroseconds(uint64_t timeout) noexcept = 0

Public Static Functions

static inline Scope WithActiveSpan(nostd::shared_ptr<Span> &span) noexcept

Set the active span. The span will remain active until the returned Scope object is destroyed.

Parameters

span – the span that should be set as the new active span.

Returns

a Scope that controls how long the span will be active.

static inline nostd::shared_ptr<Span> GetCurrentSpan() noexcept

Get the currently active span.

Returns

the currently active span, or an invalid default span if no span is active.

Class TracerProvider
Inheritance Relationships
Derived Type
Class Documentation
class opentelemetry::trace::TracerProvider

Creates new Tracer instances.

Subclassed by opentelemetry::trace::NoopTracerProvider

Public Functions

virtual ~TracerProvider() = default
virtual nostd::shared_ptr<Tracer> GetTracer(nostd::string_view library_name, nostd::string_view library_version = "") = 0

Gets or creates a named tracer instance.

Optionally a version can be passed to create a named and versioned tracer instance.

Class TraceState
Class Documentation
class opentelemetry::trace::TraceState

TraceState carries tracing-system specific context in a list of key-value pairs. TraceState allows different vendors to propagate additional information and inter-operate with their legacy id formats.

For more information, see the W3C Trace Context specification: https://www.w3.org/TR/trace-context

Public Functions

inline std::string ToHeader()

Creates a w3c tracestate header from TraceState object

inline bool Get(nostd::string_view key, std::string &value) const noexcept

Returns value associated with key passed as argument Returns empty string if key is invalid or not found

inline nostd::shared_ptr<TraceState> Set(const nostd::string_view &key, const nostd::string_view &value)

Returns shared_ptr of new TraceState object with following mutations applied to the existing instance: Update Key value: The updated value must be moved to beginning of List Add : The new key-value pair SHOULD be added to beginning of List

If the provided key-value pair is invalid, or results in transtate that violates the tracecontext specification, empty TraceState instance will be returned.

If the existing object has maximum list members, it’s copy is returned.

inline nostd::shared_ptr<TraceState> Delete(const nostd::string_view &key)

Returns shared_ptr to a new TraceState object after removing the attribute with given key ( if present )

Returns

empty TraceState object if key is invalid

Returns

copy of original TraceState object if key is not present (??)

inline bool Empty() const noexcept
inline bool GetAllEntries(nostd::function_ref<bool(nostd::string_view, nostd::string_view)> callback) const noexcept

Public Static Functions

static inline nostd::shared_ptr<TraceState> GetDefault()
static inline nostd::shared_ptr<TraceState> FromHeader(nostd::string_view header)

Returns shared_ptr to a newly created TraceState parsed from the header provided.

Parameters

header – Encoding of the tracestate header defined by the W3C Trace Context specification https://www.w3.org/TR/trace-context/

Returns

TraceState A new TraceState instance or DEFAULT

static inline bool IsValidKey(nostd::string_view key)

Returns whether key is a valid key. See https://www.w3.org/TR/trace-context/#key Identifiers MUST begin with a lowercase letter or a digit, and can only contain lowercase letters (a-z), digits (0-9), underscores (_), dashes (-), asterisks (*), and forward slashes (/). For multi-tenant vendor scenarios, an at sign (@) can be used to prefix the vendor name.

static inline bool IsValidValue(nostd::string_view value)

Returns whether value is a valid value. See https://www.w3.org/TR/trace-context/#value The value is an opaque string containing up to 256 printable ASCII (RFC0020) characters ((i.e., the range 0x20 to 0x7E) except comma , and equal =)

Public Static Attributes

static constexpr int kKeyMaxSize = 256
static constexpr int kValueMaxSize = 256
static constexpr int kMaxKeyValuePairs = 32
static constexpr auto kKeyValueSeparator = '='
static constexpr auto kMembersSeparator = ','

Enums

Enum CanonicalCode
Enum Documentation
enum opentelemetry::trace::CanonicalCode

Values:

enumerator OK

The operation completed successfully.

enumerator CANCELLED

The operation was cancelled (typically by the caller).

enumerator UNKNOWN

Unknown error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.

enumerator INVALID_ARGUMENT

Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).

enumerator DEADLINE_EXCEEDED

Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

enumerator NOT_FOUND

Some requested entity (e.g., file or directory) was not found.

enumerator ALREADY_EXISTS

Some entity that we attempted to create (e.g., file or directory) already exists.

enumerator PERMISSION_DENIED

The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller cannot be identified (use UNAUTHENTICATED instead for those errors).

enumerator RESOURCE_EXHAUSTED

Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.

enumerator FAILED_PRECONDITION

Operation was rejected because the system is not in a state required for the operation’s execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc.

A litmus test that may help a service implementor in deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher-level (e.g., restarting a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an “rmdir” fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless they have first fixed up the directory by deleting files from it.

enumerator ABORTED

The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.

See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.

enumerator OUT_OF_RANGE

Operation was attempted past the valid range. E.g., seeking or reading past end of file.

Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size.

There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.

enumerator UNIMPLEMENTED

Operation is not implemented or not supported/enabled in this service.

enumerator INTERNAL

Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.

enumerator UNAVAILABLE

The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff.

See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.

enumerator DATA_LOSS

Unrecoverable data loss or corruption.

enumerator UNAUTHENTICATED

The request does not have valid authentication credentials for the operation.

Enum SpanKind
Enum Documentation
enum opentelemetry::trace::SpanKind

Values:

enumerator kInternal
enumerator kServer
enumerator kClient
enumerator kProducer
enumerator kConsumer
Enum StatusCode
Enum Documentation
enum opentelemetry::trace::StatusCode

Values:

enumerator kUnset
enumerator kOk
enumerator kError

Functions

Function opentelemetry::baggage::propagation::GetBaggage
Function Documentation
inline nostd::shared_ptr<baggage::Baggage> opentelemetry::baggage::propagation::GetBaggage(const context::Context &context)
Function opentelemetry::baggage::propagation::SetBaggage
Function Documentation
inline context::Context opentelemetry::baggage::propagation::SetBaggage(context::Context &context, nostd::shared_ptr<baggage::Baggage> baggage)
Function opentelemetry::context::GetDefaultStorage
Function Documentation

Warning

doxygenfunction: Unable to resolve function “opentelemetry::context::GetDefaultStorage” with arguments () in doxygen xml output for project “OpenTelemetry C++ API” from directory: ../../api/docs/doxyoutput/xml. Potential matches: 

- RuntimeContextStorage *GetDefaultStorage() noexcept
Function opentelemetry::trace::propagation::detail::HexToBinary
Function Documentation
inline bool opentelemetry::trace::propagation::detail::HexToBinary(nostd::string_view hex, uint8_t *buffer, size_t buffer_size)

Converts a hexadecimal to binary format if the hex string will fit the buffer. Smaller hex strings are left padded with zeroes.

Function opentelemetry::trace::propagation::detail::HexToInt
Function Documentation
inline int8_t opentelemetry::trace::propagation::detail::HexToInt(char c)
Function opentelemetry::trace::propagation::detail::IsValidHex
Function Documentation
inline bool opentelemetry::trace::propagation::detail::IsValidHex(nostd::string_view s)
Function opentelemetry::trace::propagation::detail::SplitString
Function Documentation
inline size_t opentelemetry::trace::propagation::detail::SplitString(nostd::string_view s, char separator, nostd::string_view *results, size_t count)

Splits a string by separator, up to given buffer count words. Returns the amount of words the input was split into.

Function opentelemetry::trace::propagation::GetSpan
Function Documentation
inline nostd::shared_ptr<trace::Span> opentelemetry::trace::propagation::GetSpan(const context::Context &context)
Function opentelemetry::trace::propagation::SetSpan
Function Documentation
inline context::Context opentelemetry::trace::propagation::SetSpan(context::Context &context, nostd::shared_ptr<trace::Span> span)
Template Function opentelemetry::trace::to_span_ptr
Function Documentation
template<class SpanType, class TracerType>
nostd::shared_ptr<trace::Span> opentelemetry::trace::to_span_ptr(TracerType *objPtr, nostd::string_view name, const trace::StartSpanOptions &options)

Variables

Variable opentelemetry::baggage::propagation::kBaggageHeader
Variable Documentation
static const nostd::string_view opentelemetry::baggage::propagation::kBaggageHeader = "baggage"
Variable opentelemetry::trace::kSpanKey
Variable Documentation
constexpr char opentelemetry::trace::kSpanKey[] = "active_span"
Variable opentelemetry::trace::propagation::detail::kHexDigits
Variable Documentation
constexpr int8_t opentelemetry::trace::propagation::detail::kHexDigits[256] = {-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, -1, -1, -1, -1, -1, -1, -1, 10, 11, 12, 13, 14, 15, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 10, 11, 12, 13, 14, 15, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,}
Variable opentelemetry::trace::propagation::kB3CombinedHeader
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kB3CombinedHeader = "b3"
Variable opentelemetry::trace::propagation::kB3SampledHeader
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kB3SampledHeader = "X-B3-Sampled"
Variable opentelemetry::trace::propagation::kB3SpanIdHeader
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kB3SpanIdHeader = "X-B3-SpanId"
Variable opentelemetry::trace::propagation::kB3TraceIdHeader
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kB3TraceIdHeader = "X-B3-TraceId"
Variable opentelemetry::trace::propagation::kSpanIdHexStrLength
Variable Documentation
static const int opentelemetry::trace::propagation::kSpanIdHexStrLength = 16
Variable opentelemetry::trace::propagation::kSpanIdSize
Variable Documentation
static const size_t opentelemetry::trace::propagation::kSpanIdSize = 16
Variable opentelemetry::trace::propagation::kTraceFlagsSize
Variable Documentation
static const size_t opentelemetry::trace::propagation::kTraceFlagsSize = 2
Variable opentelemetry::trace::propagation::kTraceHeader
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kTraceHeader = "uber-trace-id"
Variable opentelemetry::trace::propagation::kTraceIdHexStrLength
Variable Documentation
static const int opentelemetry::trace::propagation::kTraceIdHexStrLength = 32
Variable opentelemetry::trace::propagation::kTraceIdSize
Variable Documentation
static const size_t opentelemetry::trace::propagation::kTraceIdSize = 32
Variable opentelemetry::trace::propagation::kTraceParent
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kTraceParent = "traceparent"
Variable opentelemetry::trace::propagation::kTraceParentSize
Variable Documentation
static const size_t opentelemetry::trace::propagation::kTraceParentSize = 55
Variable opentelemetry::trace::propagation::kTraceState
Variable Documentation
static const nostd::string_view opentelemetry::trace::propagation::kTraceState = "tracestate"
Variable opentelemetry::trace::propagation::kVersionSize
Variable Documentation
static const size_t opentelemetry::trace::propagation::kVersionSize = 2

Defines

Define HAVE_WORKING_REGEX
Define Documentation
HAVE_WORKING_REGEX

Typedefs

Typedef opentelemetry::common::AttributeValue
Typedef Documentation
using opentelemetry::common::AttributeValue = nostd::variant<bool, int32_t, int64_t, uint32_t, double, nostd::string_view, nostd::span<const bool>, nostd::span<const int32_t>, nostd::span<const int64_t>, nostd::span<const uint32_t>, nostd::span<const double>, nostd::span<const nostd::string_view>, uint64_t, nostd::span<const uint64_t>, nostd::span<const uint8_t>>

OpenTelemetry signals can be enriched by adding attributes. The AttributeValue type is defined as a variant of all attribute value types the OpenTelemetry C++ API supports.

The following attribute value types are supported by the OpenTelemetry specification:

  • Primitive types: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer.

  • Homogenous arrays of primitive type values.

Warning

The OpenTelemetry C++ API currently supports several attribute value types that are not covered by the OpenTelemetry specification:

  • uint64_t

  • nostd::span<const uint64_t>

  • nostd::span<uint8_t>

Those types are reserved for future use and currently should not be used. There are no guarantees around how those values are handled by exporters.

Typedef opentelemetry::context::ContextValue
Typedef Documentation
using opentelemetry::context::ContextValue = nostd::variant<nostd::monostate, bool, int64_t, uint64_t, double, nostd::shared_ptr<trace::Span>, nostd::shared_ptr<trace::SpanContext>, nostd::shared_ptr<baggage::Baggage>>

Getting help