span.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 "trace_context.h"
 
#include <chrono>
#include <map>
#include <memory>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
namespace kcenon::network::tracing {
 
enum class span_status
{
    unset = 0, 
    ok = 1,    
    error = 2  
};
 
enum class span_kind
{
    internal = 0, 
    server = 1,   
    client = 2,   
    producer = 3, 
    consumer = 4  
};
 
using attribute_value = std::variant<std::string, int64_t, double, bool>;
 
struct span_event
{
    std::string name;
    std::chrono::steady_clock::time_point timestamp;
    std::map<std::string, attribute_value> attributes;
};
 
class span
{
public:
    explicit span(std::string_view name, trace_context ctx,
                  span_kind kind = span_kind::internal);
 
    ~span();
 
    // Non-copyable
    span(const span&) = delete;
    auto operator=(const span&) -> span& = delete;
 
    // Movable
    span(span&& other) noexcept;
    auto operator=(span&& other) noexcept -> span&;
 
    auto set_attribute(std::string_view key, std::string_view value) -> span&;
 
    auto set_attribute(std::string_view key, const char* value) -> span&;
 
    auto set_attribute(std::string_view key, int64_t value) -> span&;
 
    auto set_attribute(std::string_view key, double value) -> span&;
 
    auto set_attribute(std::string_view key, bool value) -> span&;
 
    auto add_event(std::string_view name) -> span&;
 
    auto add_event(std::string_view name,
                   const std::map<std::string, attribute_value>& attributes)
        -> span&;
 
    auto set_status(span_status status) -> span&;
 
    auto set_status(span_status status, std::string_view description) -> span&;
 
    auto set_error(std::string_view message) -> span&;
 
    void end();
 
    [[nodiscard]] auto is_ended() const noexcept -> bool;
 
    [[nodiscard]] auto context() const noexcept -> const trace_context&;
 
    [[nodiscard]] auto name() const noexcept -> const std::string&;
 
    [[nodiscard]] auto kind() const noexcept -> span_kind;
 
    [[nodiscard]] auto status() const noexcept -> span_status;
 
    [[nodiscard]] auto status_description() const noexcept -> const std::string&;
 
    [[nodiscard]] auto attributes() const noexcept
        -> const std::map<std::string, attribute_value>&;
 
    [[nodiscard]] auto events() const noexcept -> const std::vector<span_event>&;
 
    [[nodiscard]] auto start_time() const noexcept
        -> std::chrono::steady_clock::time_point;
 
    [[nodiscard]] auto end_time() const noexcept
        -> std::chrono::steady_clock::time_point;
 
    [[nodiscard]] auto duration() const noexcept -> std::chrono::nanoseconds;
 
private:
    struct impl;
    std::unique_ptr<impl> impl_;
};
 
#define NETWORK_TRACE_SPAN(name) \
    auto _span = ::kcenon::network::tracing::trace_context::create_span(name)
 
#define NETWORK_TRACE_CLIENT_SPAN(name)                                     \
    auto _span = ::kcenon::network::tracing::span(                          \
        name, ::kcenon::network::tracing::trace_context::current().is_valid() \
                  ? ::kcenon::network::tracing::trace_context::current()      \
                        .create_child_span(name)                              \
                        .context()                                            \
                  : ::kcenon::network::tracing::trace_context(),              \
        ::kcenon::network::tracing::span_kind::client)
 
#define NETWORK_TRACE_SERVER_SPAN(name)                                     \
    auto _span = ::kcenon::network::tracing::span(                          \
        name, ::kcenon::network::tracing::trace_context::current().is_valid() \
                  ? ::kcenon::network::tracing::trace_context::current()      \
                        .create_child_span(name)                              \
                        .context()                                            \
                  : ::kcenon::network::tracing::trace_context(),              \
        ::kcenon::network::tracing::span_kind::server)
 
} // namespace kcenon::network::tracing