telemetry_context Class Reference

Immutable context passed through the call chain for telemetry. More...

#include <telemetry_context.hpp>

Collaboration diagram for telemetry_context:

Public Member Functions
	telemetry_context (span_context ctx, std::shared_ptr< resource > res)
	Constructs a telemetry context.
const span_context &	context () const
	Gets the current span context.
const trace_id &	get_trace_id () const
	Gets the trace_id from the current context.
const span_id &	get_span_id () const
	Gets the span_id from the current context.
const resource &	get_resource () const
	Gets the resource associated with this context.
std::shared_ptr< resource >	resource_ptr () const
	Gets the shared pointer to the resource.
std::pair< telemetry_context, span >	start_span (std::string_view name, span_kind kind=span_kind::internal) const
	Creates a new child span within the same trace.
std::pair< telemetry_context, span >	start_linked_trace (std::string_view name, span_kind kind=span_kind::internal) const
	Creates a new trace linked to the current span.
bool	is_valid () const
	Checks if this context is valid.

Static Public Member Functions
static telemetry_context	create_root (std::shared_ptr< resource > res)
	Creates a root telemetry context for a new trace.

Detailed Description

Immutable context passed through the call chain for telemetry.

The telemetry_context is designed to be passed as an explicit parameter to all functions that participate in distributed tracing. This approach works well with coroutines and makes data flow explicit.

Usage:

awaitable<void> handle_request(const request& req,
                               const telemetry_context& ctx) {
    auto [child_ctx, child_span] = ctx.start_span("process_request");
    // ... do work, pass child_ctx to nested calls ...
    child_span.end_time = std::chrono::system_clock::now();
    // ... record child_span to storage ...
}

Constructor & Destructor Documentation

telemetry_context()

telemetry_context ( span_context  ctx, std::shared_ptr< resource >  res  )

explicit

Constructs a telemetry context.

Parameters

ctx	The span context identifying the current span.
res	The resource describing the entity producing telemetry.

Member Function Documentation

create_root()

telemetry_context create_root ( std::shared_ptr< resource >  res )

static

Creates a root telemetry context for a new trace.

This is used to start a new trace at the entry point of an application or service. The root context has a newly generated trace_id and span_id.

Parameters

res	The resource describing the entity producing telemetry.

Returns

A telemetry context with a new trace_id and span_id.

Here is the caller graph for this function:

start_span()

std::pair< telemetry_context, span > start_span	(	std::string_view	name,
		span_kind	kind = span_kind::internal
	)		const

Creates a new child span within the same trace.

The returned span has this context's span_id as its parent.

Parameters

name	The name of the new span.
kind	The kind of span (default: internal).

Returns

A pair of the new child context and the span to be recorded.

start_linked_trace()

std::pair< telemetry_context, span > start_linked_trace	(	std::string_view	name,
		span_kind	kind = span_kind::internal
	)		const

Creates a new trace linked to the current span.

This is used when starting independent work that should be correlated with the current trace but not as a child span. For example, when a grid engine picks up work triggered by a client request.

Parameters

name	The name of the new span.
kind	The kind of span (default: internal).

Returns

A pair of the new context (with new trace_id) and the span.