trace_context.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include <array>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace kcenon::network::tracing {
 
// Forward declarations
class span;
 
using trace_id_t = std::array<uint8_t, 16>;
 
using span_id_t = std::array<uint8_t, 8>;
 
enum class trace_flags : uint8_t
{
    none = 0x00,
    sampled = 0x01
};
 
class trace_context
{
public:
    trace_context() = default;
 
    trace_context(trace_id_t trace_id, span_id_t span_id, trace_flags flags,
                  std::optional<span_id_t> parent_span_id = std::nullopt);
 
    [[nodiscard]] static auto current() -> trace_context;
 
    [[nodiscard]] static auto create_span(std::string_view name) -> span;
 
    [[nodiscard]] auto create_child_span(std::string_view name) const -> span;
 
    [[nodiscard]] auto to_traceparent() const -> std::string;
 
    [[nodiscard]] auto to_headers() const
        -> std::vector<std::pair<std::string, std::string>>;
 
    [[nodiscard]] static auto from_traceparent(std::string_view traceparent)
        -> trace_context;
 
    [[nodiscard]] static auto from_headers(
        const std::vector<std::pair<std::string, std::string>>& headers)
        -> trace_context;
 
    [[nodiscard]] auto is_valid() const noexcept -> bool;
 
    [[nodiscard]] auto is_sampled() const noexcept -> bool;
 
    [[nodiscard]] auto trace_id() const noexcept -> const trace_id_t&;
 
    [[nodiscard]] auto span_id() const noexcept -> const span_id_t&;
 
    [[nodiscard]] auto parent_span_id() const noexcept
        -> const std::optional<span_id_t>&;
 
    [[nodiscard]] auto flags() const noexcept -> trace_flags;
 
    [[nodiscard]] auto trace_id_hex() const -> std::string;
 
    [[nodiscard]] auto span_id_hex() const -> std::string;
 
    [[nodiscard]] auto operator==(const trace_context& other) const noexcept
        -> bool;
 
    [[nodiscard]] auto operator!=(const trace_context& other) const noexcept
        -> bool;
 
private:
    trace_id_t trace_id_{};
    span_id_t span_id_{};
    std::optional<span_id_t> parent_span_id_;
    trace_flags flags_{trace_flags::none};
    bool valid_{false};
 
    static void set_current(const trace_context& ctx);
 
    static void clear_current();
 
    // span class needs access to set_current
    friend class span;
};
 
[[nodiscard]] auto generate_trace_id() -> trace_id_t;
 
[[nodiscard]] auto generate_span_id() -> span_id_t;
 
[[nodiscard]] auto bytes_to_hex(const uint8_t* data, size_t size) -> std::string;
 
[[nodiscard]] auto hex_to_bytes(std::string_view hex, uint8_t* out, size_t size)
    -> bool;
 
} // namespace kcenon::network::tracing