kcenon::network::tracing Namespace Reference

Classes
struct	batch_config
	Batch export configuration. More...
struct	otlp_config
	OTLP exporter configuration. More...
class	span
	RAII span for distributed tracing. More...
struct	span_event
	Span event (timestamped annotation) More...
class	trace_context
	Immutable trace context for distributed tracing. More...
struct	tracing_config
	Main configuration structure for tracing. More...

Typedefs
using	attribute_value = std::variant<std::string, int64_t, double, bool>
	Attribute value type (supports string, int64, double, bool)
using	trace_id_t = std::array<uint8_t, 16>
	Trace ID type (128-bit identifier)
using	span_id_t = std::array<uint8_t, 8>
	Span ID type (64-bit identifier)
using	span_processor_callback = std::function<void(const span&)>
	Span processor callback type.

Enumerations
enum class	span_status { unset = 0 , ok = 1 , error = 2 }
	Span status codes following OpenTelemetry conventions. More...
enum class	span_kind {   internal = 0 , server = 1 , client = 2 , producer = 3 ,   consumer = 4 }
	Span kind following OpenTelemetry conventions. More...
enum class	trace_flags : uint8_t { none = 0x00 , sampled = 0x01 }
	Trace flags (8-bit) More...
enum class	exporter_type {   none , console , otlp_grpc , otlp_http ,   jaeger , zipkin }
	Exporter types for trace data. More...
enum class	sampler_type { always_on , always_off , trace_id , parent_based }
	Sampler types for trace sampling decisions. More...

Functions
auto	generate_trace_id () -> trace_id_t
	Generate a random trace ID.
auto	generate_span_id () -> span_id_t
	Generate a random span ID.
auto	bytes_to_hex (const uint8_t *data, size_t size) -> std::string
	Convert bytes to lowercase hex string.
auto	hex_to_bytes (std::string_view hex, uint8_t *out, size_t size) -> bool
	Parse hex string to bytes.
void	configure_tracing (const tracing_config &config)
	Initialize the tracing system with configuration.
void	shutdown_tracing ()
	Shutdown the tracing system.
void	flush_tracing ()
	Force flush all pending spans.
auto	is_tracing_enabled () -> bool
	Check if tracing is enabled.
void	register_span_processor (span_processor_callback callback)
	Register a custom span processor.
void	export_span (const span &s)
	Export a completed span.

Typedef Documentation

attribute_value

using kcenon::network::tracing::attribute_value = std::variant<std::string, int64_t, double, bool>

Attribute value type (supports string, int64, double, bool)

Definition at line 55 of file span.h.

span_id_t

using kcenon::network::tracing::span_id_t = std::array<uint8_t, 8>

Span ID type (64-bit identifier)

Definition at line 39 of file trace_context.h.

span_processor_callback

using kcenon::network::tracing::span_processor_callback = std::function<void(const span&)>

Span processor callback type.

Called when a span ends. Can be used for custom export or processing.

Definition at line 283 of file tracing_config.h.

trace_id_t

using kcenon::network::tracing::trace_id_t = std::array<uint8_t, 16>

Trace ID type (128-bit identifier)

Definition at line 34 of file trace_context.h.

Enumeration Type Documentation

exporter_type

enum class kcenon::network::tracing::exporter_type

strong

Exporter types for trace data.

Enumerator
none	Tracing disabled.
console	Console/stdout output (for debugging)
otlp_grpc	OTLP over gRPC (OpenTelemetry Collector)
otlp_http	OTLP over HTTP (OpenTelemetry Collector)
jaeger	Jaeger native format.
zipkin	Zipkin format.

Definition at line 32 of file tracing_config.h.

{
    none,      
    console,   
    otlp_grpc, 
    otlp_http, 
    jaeger,    
    zipkin     
};

sampler_type

enum class kcenon::network::tracing::sampler_type

strong

Sampler types for trace sampling decisions.

Enumerator
always_on	Sample all traces.
always_off	Sample no traces.
trace_id	Sample based on trace ID ratio.
parent_based	Sample based on parent span's sampling decision.

Definition at line 45 of file tracing_config.h.

{
    always_on,    
    always_off,   
    trace_id,     
    parent_based  
};

span_kind

enum class kcenon::network::tracing::span_kind

strong

Span kind following OpenTelemetry conventions.

Enumerator
internal	Default, represents internal operations.
server	Server-side handling of a request.
client	Client-side request.
producer	Message producer (e.g., queue publisher)
consumer	Message consumer (e.g., queue subscriber)

Definition at line 43 of file span.h.

{
    internal = 0, 
    server = 1,   
    client = 2,   
    producer = 3, 
    consumer = 4  
};

span_status

enum class kcenon::network::tracing::span_status

strong

Span status codes following OpenTelemetry conventions.

Enumerator
unset	Default status, span completed without explicit status.
ok	Operation completed successfully.
error	Operation failed.

Definition at line 33 of file span.h.

{
    unset = 0, 
    ok = 1,    
    error = 2  
};

trace_flags

enum class kcenon::network::tracing::trace_flags : uint8_t

strong

Trace flags (8-bit)

Enumerator
none
sampled

Definition at line 44 of file trace_context.h.

{
    none = 0x00,
    sampled = 0x01
};

Function Documentation

bytes_to_hex()

auto kcenon::network::tracing::bytes_to_hex ( const uint8_t * data, size_t size ) -> std::string

nodiscard

Convert bytes to lowercase hex string.

Parameters

data	Byte array
size	Number of bytes

Returns

Hex string representation

Definition at line 315 of file trace_context.cpp.

{
    std::string result;
    result.reserve(size * 2);
 
    for (size_t i = 0; i < size; ++i)
    {
        result.push_back(hex_chars[(data[i] >> 4) & 0x0F]);
        result.push_back(hex_chars[data[i] & 0x0F]);
    }
 
    return result;
}

Referenced by kcenon::network::tracing::trace_context::span_id_hex(), and kcenon::network::tracing::trace_context::trace_id_hex().

Here is the caller graph for this function:

configure_tracing()

void kcenon::network::tracing::configure_tracing

(

const tracing_config &

config

)

Initialize the tracing system with configuration.

Parameters

config

Tracing configuration

This function must be called before creating any spans. It initializes the tracing system with the specified configuration.

Example:

tracing_config config;
config.exporter = exporter_type::otlp_grpc;
config.otlp.endpoint = "http://localhost:4317";
config.service_name = "my-service";
 
configure_tracing(config);

Definition at line 599 of file exporters.cpp.

{
    const bool should_log = config.debug && config.exporter != exporter_type::none;
 
    {
        std::lock_guard<std::mutex> lock(g_tracing_state.mutex);
 
        g_tracing_state.config = config;
        g_tracing_state.enabled.store(config.exporter != exporter_type::none,
                                       std::memory_order_release);
    }
 
    if (should_log)
    {
        std::lock_guard<std::mutex> lock(g_console_mutex);
        std::cout << "[TRACING] Configured with exporter: ";
        switch (config.exporter)
        {
        case exporter_type::console:
            std::cout << "console";
            break;
        case exporter_type::otlp_grpc:
            std::cout << "otlp_grpc (" << config.otlp.endpoint << ")";
            break;
        case exporter_type::otlp_http:
            std::cout << "otlp_http (" << config.otlp.endpoint << ")";
            break;
        case exporter_type::jaeger:
            std::cout << "jaeger (" << config.jaeger_endpoint << ")";
            break;
        case exporter_type::zipkin:
            std::cout << "zipkin (" << config.zipkin_endpoint << ")";
            break;
        default:
            std::cout << "none";
            break;
        }
        std::cout << ", service: " << config.service_name
                  << ", sample_rate: " << config.sample_rate << "\n";
    }
}

References config, console, kcenon::network::tracing::tracing_config::debug, kcenon::network::tracing::otlp_config::endpoint, kcenon::network::tracing::tracing_config::exporter, jaeger, kcenon::network::tracing::tracing_config::jaeger_endpoint, none, kcenon::network::tracing::tracing_config::otlp, otlp_grpc, otlp_http, kcenon::network::tracing::tracing_config::sample_rate, kcenon::network::tracing::tracing_config::service_name, zipkin, and kcenon::network::tracing::tracing_config::zipkin_endpoint.

export_span()

void kcenon::network::tracing::export_span

(

const span &

s

)

Export a completed span.

Parameters

s	The span to export

This function is called automatically when a span ends. It exports the span according to the configured exporter.

Definition at line 701 of file exporters.cpp.

{
    process_span(s);
}

Referenced by kcenon::network::tracing::span::impl::do_end().

Here is the caller graph for this function:

flush_tracing()

void kcenon::network::tracing::flush_tracing

(

)

Force flush all pending spans.

Blocks until all pending spans are exported.

Definition at line 660 of file exporters.cpp.

{
    // Flush batch queue
    std::vector<std::string> batch;
    {
        std::lock_guard<std::mutex> lock(g_tracing_state.batch_mutex);
        if (!g_tracing_state.batch_queue.empty())
        {
            batch = std::move(g_tracing_state.batch_queue);
            g_tracing_state.batch_queue.clear();
            g_tracing_state.queued_count.store(0, std::memory_order_relaxed);
        }
    }
 
    if (!batch.empty())
    {
        export_otlp_http(batch);
    }
 
    {
        std::lock_guard<std::mutex> lock(g_console_mutex);
        std::cout << std::flush;
    }
}

Referenced by shutdown_tracing().

Here is the caller graph for this function:

generate_span_id()

auto kcenon::network::tracing::generate_span_id ( ) -> span_id_t

nodiscard

Generate a random span ID.

Returns

Randomly generated 64-bit span ID

Definition at line 308 of file trace_context.cpp.

{
    span_id_t id{};
    get_random_bytes(id.data(), id.size());
    return id;
}

Referenced by kcenon::network::tracing::trace_context::create_child_span(), and kcenon::network::tracing::trace_context::create_span().

Here is the caller graph for this function:

generate_trace_id()

auto kcenon::network::tracing::generate_trace_id ( ) -> trace_id_t

nodiscard

Generate a random trace ID.

Returns

Randomly generated 128-bit trace ID

Definition at line 301 of file trace_context.cpp.

{
    trace_id_t id{};
    get_random_bytes(id.data(), id.size());
    return id;
}

Referenced by kcenon::network::tracing::trace_context::create_child_span(), and kcenon::network::tracing::trace_context::create_span().

Here is the caller graph for this function:

hex_to_bytes()

auto kcenon::network::tracing::hex_to_bytes ( std::string_view hex, uint8_t * out, size_t size ) -> bool

nodiscard

Parse hex string to bytes.

Parameters

hex	Hex string
out	Output byte array
size	Expected number of bytes

Returns

true if parsing succeeded

Definition at line 329 of file trace_context.cpp.

{
    if (hex.size() != size * 2)
    {
        return false;
    }
 
    for (size_t i = 0; i < size; ++i)
    {
        int high = hex_char_to_value(hex[i * 2]);
        int low = hex_char_to_value(hex[i * 2 + 1]);
 
        if (high < 0 || low < 0)
        {
            return false;
        }
 
        out[i] = static_cast<uint8_t>((high << 4) | low);
    }
 
    return true;
}

Referenced by kcenon::network::tracing::trace_context::from_traceparent().

Here is the caller graph for this function:

is_tracing_enabled()

auto kcenon::network::tracing::is_tracing_enabled ( ) -> bool

nodiscard

Check if tracing is enabled.

Returns

true if tracing is configured and enabled

Definition at line 685 of file exporters.cpp.

{
    return g_tracing_state.enabled.load(std::memory_order_acquire);
}

Referenced by kcenon::network::protocols::grpc::grpc_client::impl::call_raw(), kcenon::network::protocols::quic::connection::close(), kcenon::network::protocols::quic::connection::close_application(), kcenon::network::protocols::grpc::grpc_client::impl::connect(), kcenon::network::protocols::http2::http2_client::connect(), kcenon::network::protocols::quic::connection::init_server_handshake(), kcenon::network::core::messaging_server::on_accept(), kcenon::network::protocols::quic::connection::receive_packet(), kcenon::network::core::messaging_quic_client::send_on_stream(), kcenon::network::core::messaging_client::send_packet(), kcenon::network::core::messaging_quic_client::send_packet(), kcenon::network::protocols::http2::http2_client::send_request(), kcenon::network::protocols::grpc::grpc_server::impl::start(), kcenon::network::core::messaging_client::start_client(), kcenon::network::core::messaging_quic_client::start_client(), kcenon::network::protocols::quic::connection::start_handshake(), and kcenon::network::core::messaging_server::start_server().

Here is the caller graph for this function:

register_span_processor()

void kcenon::network::tracing::register_span_processor

(

span_processor_callback

callback

)

Register a custom span processor.

Parameters

callback

Callback function called when spans end

Can be used to implement custom export logic or additional processing.

Definition at line 690 of file exporters.cpp.

{
    if (!callback)
    {
        return;
    }
 
    std::lock_guard<std::mutex> lock(g_tracing_state.mutex);
    g_tracing_state.processors.push_back(std::move(callback));
}

shutdown_tracing()

void kcenon::network::tracing::shutdown_tracing

(

)

Shutdown the tracing system.

Flushes any pending spans and releases resources. Should be called before application exit.

Example:

// At application shutdown
shutdown_tracing();

Definition at line 641 of file exporters.cpp.

{
    // Flush any pending spans before shutdown
    flush_tracing();
 
    std::lock_guard<std::mutex> lock(g_tracing_state.mutex);
 
    g_tracing_state.enabled.store(false, std::memory_order_release);
    g_tracing_state.processors.clear();
    g_tracing_state.config = tracing_config{};
 
    // Clear batch queue
    {
        std::lock_guard<std::mutex> batch_lock(g_tracing_state.batch_mutex);
        g_tracing_state.batch_queue.clear();
        g_tracing_state.queued_count.store(0, std::memory_order_relaxed);
    }
}

References flush_tracing().

Here is the call graph for this function: