kcenon::network::tracing::span Class Reference

RAII span for distributed tracing. More...

#include <span.h>

Collaboration diagram for kcenon::network::tracing::span:

Classes
struct	impl
	Internal implementation structure for span. More...

Public Member Functions
	span (std::string_view name, trace_context ctx, span_kind kind=span_kind::internal)
	Construct a new span.
	~span ()
	Destructor - automatically ends the span if not ended.
	span (const span &)=delete
auto	operator= (const span &) -> span &=delete
	span (span &&other) noexcept
auto	operator= (span &&other) noexcept -> span &
auto	set_attribute (std::string_view key, std::string_view value) -> span &
	Set a string attribute.
auto	set_attribute (std::string_view key, const char *value) -> span &
	Set a string attribute (const char* overload)
auto	set_attribute (std::string_view key, int64_t value) -> span &
	Set an integer attribute.
auto	set_attribute (std::string_view key, double value) -> span &
	Set a double attribute.
auto	set_attribute (std::string_view key, bool value) -> span &
	Set a boolean attribute.
auto	add_event (std::string_view name) -> span &
	Add an event to the span.
auto	add_event (std::string_view name, const std::map< std::string, attribute_value > &attributes) -> span &
	Add an event with attributes.
auto	set_status (span_status status) -> span &
	Set the span status.
auto	set_status (span_status status, std::string_view description) -> span &
	Set the span status with description.
auto	set_error (std::string_view message) -> span &
	Set error status with message.
void	end ()
	Manually end the span.
auto	is_ended () const noexcept -> bool
	Check if the span has ended.
auto	context () const noexcept -> const trace_context &
	Get the trace context for this span.
auto	name () const noexcept -> const std::string &
	Get the span name.
auto	kind () const noexcept -> span_kind
	Get the span kind.
auto	status () const noexcept -> span_status
	Get the span status.
auto	status_description () const noexcept -> const std::string &
	Get the status description.
auto	attributes () const noexcept -> const std::map< std::string, attribute_value > &
	Get the span attributes.
auto	events () const noexcept -> const std::vector< span_event > &
	Get the span events.
auto	start_time () const noexcept -> std::chrono::steady_clock::time_point
	Get the span start time.
auto	end_time () const noexcept -> std::chrono::steady_clock::time_point
	Get the span end time.
auto	duration () const noexcept -> std::chrono::nanoseconds
	Get the span duration.

Private Attributes
std::unique_ptr< impl >	impl_

Detailed Description

RAII span for distributed tracing.

A span represents a single operation within a trace. It has a name, start and end time, attributes, and can have events recorded during its lifetime. The span automatically ends when destroyed (RAII).

Spans maintain the current trace context via thread-local storage, enabling automatic parent-child relationship tracking.

Example usage:

void process_request() {
    auto span = trace_context::create_span("process_request");
    span.set_attribute("request.id", "12345");
 
    // Do work...
    span.add_event("processing_started");
 
    if (error) {
        span.set_error("Failed to process request");
    }
    // span automatically ends on destruction
}

RAII Macro:

NETWORK_TRACE_SPAN("operation.name");
_span.set_attribute("key", "value");

See also

trace_context

Definition at line 102 of file span.h.

Constructor & Destructor Documentation

span() [1/3]

kcenon::network::tracing::span::span ( std::string_view name, trace_context ctx, span_kind kind = span_kind::internal )

explicit

Construct a new span.

Parameters

name	Span name (operation name)
ctx	Trace context for this span
kind	Kind of span (default: internal)

Definition at line 84 of file span.cpp.

    : impl_(std::make_unique<impl>(name, std::move(ctx), kind))
{
    impl_->owner = this;
}

References impl_, and kcenon::network::tracing::span::impl::owner.

~span()

kcenon::network::tracing::span::~span

(

)

Destructor - automatically ends the span if not ended.

Definition at line 90 of file span.cpp.

{
    // End span before impl_ destruction to ensure owner->impl_ is still valid
    if (impl_ && !impl_->ended)
    {
        impl_->do_end();
    }
}

References kcenon::network::tracing::span::impl::do_end(), kcenon::network::tracing::span::impl::ended, and impl_.

Here is the call graph for this function:

span() [2/3]

kcenon::network::tracing::span::span ( const span & )

delete

span() [3/3]

kcenon::network::tracing::span::span ( span && other )

noexcept

Definition at line 99 of file span.cpp.

    : impl_(std::move(other.impl_))
{
    if (impl_)
    {
        impl_->owner = this;
    }
}

Member Function Documentation

add_event() [1/2]

auto kcenon::network::tracing::span::add_event

(

std::string_view

name

)

-> span&

Add an event to the span.

Parameters

name	Event name

Returns

Reference to this span for chaining

Definition at line 162 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        span_event event;
        event.name = std::string(name);
        event.timestamp = std::chrono::steady_clock::now();
        impl_->events.push_back(std::move(event));
    }
    return *this;
}

References kcenon::network::tracing::span_event::name.

add_event() [2/2]

auto kcenon::network::tracing::span::add_event	(	std::string_view	name,
		const std::map< std::string, attribute_value > &	attributes ) -> span&

Add an event with attributes.

Parameters

name	Event name
attributes	Event attributes

Returns

Reference to this span for chaining

Definition at line 174 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        span_event event;
        event.name = std::string(name);
        event.timestamp = std::chrono::steady_clock::now();
        event.attributes = attributes;
        impl_->events.push_back(std::move(event));
    }
    return *this;
}

References kcenon::network::tracing::span_event::name.

attributes()

auto kcenon::network::tracing::span::attributes ( ) const -> const std::map<std::string, attribute_value>&

nodiscardnoexcept

Get the span attributes.

Returns

Map of attributes

Definition at line 263 of file span.cpp.

{
    static const std::map<std::string, attribute_value> empty_attrs;
    return impl_ ? impl_->attributes : empty_attrs;
}

References kcenon::network::tracing::span::impl::attributes, and impl_.

context()

auto kcenon::network::tracing::span::context ( ) const -> const trace_context&

nodiscardnoexcept

Get the trace context for this span.

Returns

Trace context

Definition at line 235 of file span.cpp.

{
    static const trace_context empty_context;
    return impl_ ? impl_->context : empty_context;
}

References kcenon::network::tracing::span::impl::context, and impl_.

duration()

auto kcenon::network::tracing::span::duration ( ) const -> std::chrono::nanoseconds

nodiscardnoexcept

Get the span duration.

Returns

Duration in nanoseconds

Definition at line 286 of file span.cpp.

{
    if (!impl_)
    {
        return std::chrono::nanoseconds::zero();
    }
 
    auto end = impl_->ended ? impl_->end_time : std::chrono::steady_clock::now();
    return std::chrono::duration_cast<std::chrono::nanoseconds>(end - impl_->start_time);
}

References end(), kcenon::network::tracing::span::impl::end_time, kcenon::network::tracing::span::impl::ended, impl_, and kcenon::network::tracing::span::impl::start_time.

Here is the call graph for this function:

end()

void kcenon::network::tracing::span::end

(

)

Manually end the span.

After calling end(), the span will not be ended again in destructor.

Definition at line 222 of file span.cpp.

{
    if (impl_)
    {
        impl_->do_end();
    }
}

References kcenon::network::tracing::span::impl::do_end(), and impl_.

Referenced by duration().

Here is the call graph for this function:

Here is the caller graph for this function:

end_time()

auto kcenon::network::tracing::span::end_time ( ) const -> std::chrono::steady_clock::time_point

nodiscardnoexcept

Get the span end time.

Returns

End timestamp (start_time if not ended)

Definition at line 281 of file span.cpp.

{
    return impl_ ? impl_->end_time : std::chrono::steady_clock::time_point{};
}

References kcenon::network::tracing::span::impl::end_time, and impl_.

events()

auto kcenon::network::tracing::span::events ( ) const -> const std::vector<span_event>&

nodiscardnoexcept

Get the span events.

Returns

Vector of events

Definition at line 270 of file span.cpp.

{
    static const std::vector<span_event> empty_events;
    return impl_ ? impl_->events : empty_events;
}

References kcenon::network::tracing::span::impl::events, and impl_.

is_ended()

auto kcenon::network::tracing::span::is_ended ( ) const -> bool

nodiscardnoexcept

Check if the span has ended.

Returns

true if the span has ended

Definition at line 230 of file span.cpp.

{
    return impl_ ? impl_->ended : true;
}

References kcenon::network::tracing::span::impl::ended, and impl_.

kind()

auto kcenon::network::tracing::span::kind ( ) const -> span_kind

nodiscardnoexcept

Get the span kind.

Returns

Span kind

Definition at line 247 of file span.cpp.

{
    return impl_ ? impl_->kind : span_kind::internal;
}

References impl_, kcenon::network::tracing::internal, and kcenon::network::tracing::span::impl::kind.

name()

auto kcenon::network::tracing::span::name ( ) const -> const std::string&

nodiscardnoexcept

Get the span name.

Returns

Span name

Definition at line 241 of file span.cpp.

{
    static const std::string empty_name;
    return impl_ ? impl_->name : empty_name;
}

References impl_, and kcenon::network::tracing::span::impl::name.

operator=() [1/2]

auto kcenon::network::tracing::span::operator= ( const span & ) -> span &=delete

delete

operator=() [2/2]

auto kcenon::network::tracing::span::operator= ( span && other ) -> span&

noexcept

Definition at line 108 of file span.cpp.

{
    if (this != &other)
    {
        impl_ = std::move(other.impl_);
        if (impl_)
        {
            impl_->owner = this;
        }
    }
    return *this;
}

set_attribute() [1/5]

auto kcenon::network::tracing::span::set_attribute	(	std::string_view	key,
		bool	value ) -> span&

Set a boolean attribute.

Parameters

key	Attribute key
value	Attribute value

Returns

Reference to this span for chaining

Definition at line 153 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->attributes[std::string(key)] = value;
    }
    return *this;
}

set_attribute() [2/5]

auto kcenon::network::tracing::span::set_attribute	(	std::string_view	key,
		const char *	value ) -> span&

Set a string attribute (const char* overload)

Parameters

key	Attribute key
value	Attribute value

Returns

Reference to this span for chaining

This overload prevents implicit conversion of const char* to bool.

Definition at line 130 of file span.cpp.

{
    return set_attribute(key, std::string_view(value));
}

set_attribute() [3/5]

auto kcenon::network::tracing::span::set_attribute	(	std::string_view	key,
		double	value ) -> span&

Set a double attribute.

Parameters

key	Attribute key
value	Attribute value

Returns

Reference to this span for chaining

Definition at line 144 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->attributes[std::string(key)] = value;
    }
    return *this;
}

set_attribute() [4/5]

auto kcenon::network::tracing::span::set_attribute	(	std::string_view	key,
		int64_t	value ) -> span&

Set an integer attribute.

Parameters

key	Attribute key
value	Attribute value

Returns

Reference to this span for chaining

Definition at line 135 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->attributes[std::string(key)] = value;
    }
    return *this;
}

set_attribute() [5/5]

auto kcenon::network::tracing::span::set_attribute	(	std::string_view	key,
		std::string_view	value ) -> span&

Set a string attribute.

Parameters

key	Attribute key
value	Attribute value

Returns

Reference to this span for chaining

Definition at line 121 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->attributes[std::string(key)] = std::string(value);
    }
    return *this;
}

set_error()

auto kcenon::network::tracing::span::set_error

(

std::string_view

message

)

-> span&

Set error status with message.

Parameters

message

Error message

Returns

Reference to this span for chaining

Definition at line 207 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->status = span_status::error;
        impl_->status_description = std::string(message);
 
        // Also add an exception event following OpenTelemetry conventions
        std::map<std::string, attribute_value> event_attrs;
        event_attrs["exception.message"] = std::string(message);
        add_event("exception", event_attrs);
    }
    return *this;
}

References kcenon::network::tracing::error, and kcenon::network::message.

set_status() [1/2]

auto kcenon::network::tracing::span::set_status

(

span_status

status

)

-> span&

Set the span status.

Parameters

status

Status code

Returns

Reference to this span for chaining

Definition at line 188 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->status = status;
    }
    return *this;
}

set_status() [2/2]

auto kcenon::network::tracing::span::set_status	(	span_status	status,
		std::string_view	description ) -> span&

Set the span status with description.

Parameters

status	Status code
description	Status description

Returns

Reference to this span for chaining

Definition at line 197 of file span.cpp.

{
    if (impl_ && !impl_->ended)
    {
        impl_->status = status;
        impl_->status_description = std::string(description);
    }
    return *this;
}

start_time()

auto kcenon::network::tracing::span::start_time ( ) const -> std::chrono::steady_clock::time_point

nodiscardnoexcept

Get the span start time.

Returns

Start timestamp

Definition at line 276 of file span.cpp.

{
    return impl_ ? impl_->start_time : std::chrono::steady_clock::time_point{};
}

References impl_, and kcenon::network::tracing::span::impl::start_time.

status()

auto kcenon::network::tracing::span::status ( ) const -> span_status

nodiscardnoexcept

Get the span status.

Returns

Span status

Definition at line 252 of file span.cpp.

{
    return impl_ ? impl_->status : span_status::unset;
}

References impl_, kcenon::network::tracing::span::impl::status, and kcenon::network::tracing::unset.

status_description()

auto kcenon::network::tracing::span::status_description ( ) const -> const std::string&

nodiscardnoexcept

Get the status description.

Returns

Status description (empty if not set)

Definition at line 257 of file span.cpp.

{
    static const std::string empty_description;
    return impl_ ? impl_->status_description : empty_description;
}

References impl_, and kcenon::network::tracing::span::impl::status_description.

Member Data Documentation

impl_

std::unique_ptr<impl> kcenon::network::tracing::span::impl_

private

Definition at line 286 of file span.h.

Referenced by attributes(), context(), duration(), end(), end_time(), events(), is_ended(), kind(), name(), span(), start_time(), status(), status_description(), and ~span().

---

The documentation for this class was generated from the following files:

• include/kcenon/network/detail/tracing/span.h
• src/tracing/span.cpp