telemetry.hpp

Go to the documentation of this file.

// axiam telemetry hooks — CONTRACT.md §19.
//
// An optional callback surface so a caller can wire OpenTelemetry, Prometheus
// or a log line WITHOUT this library depending on any of them. Install one with
// `Client::Builder::telemetry_hook`; with none installed the cost is a single
// empty-std::function check per request.
//
// Two of §19.2's rules are enforced by the shape of this header rather than left
// to documentation:
//
//   * No secrets, ever (rule 3). `TelemetryEvent` is a `std::variant` over the
//     five structs below, each with a fixed member list and no map. The variant
//     is closed by construction — a caller cannot add a sixth alternative — so
//     "there is nowhere to put a token in a payload bound for a metrics backend"
//     is checkable by reading one declaration rather than trusting a review.
//   * No cost when uninstalled (rule 1). Nothing here allocates; building an
//     event is a handful of string copies taken only when a hook exists.
#pragma once
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <variant>
 
namespace axiam {
 
enum class Outcome {
    kSuccess,
    kFailure,
};
 
enum class RefreshRole {
    kLeader,
    kFollower,
};
 
struct RequestStartEvent {
    std::string operation;
    std::string method;
    std::string path_template;
    int attempt = 1;
};
 
struct RequestEndEvent {
    std::string operation;
    std::string method;
    std::string path_template;
    int attempt = 1;
    std::optional<long> status;
    std::chrono::milliseconds duration{0};
    Outcome outcome = Outcome::kSuccess;
};
 
struct RetryEvent {
    std::string operation;
    int attempt = 1;
    std::chrono::milliseconds delay{0};
    std::string reason;
};
 
struct RefreshEvent {
    RefreshRole role = RefreshRole::kLeader;
    std::chrono::milliseconds duration{0};
};
 
struct ConfigClampedEvent {
    std::string setting;
    std::string requested;
    std::string effective;
    std::string contract_reference;
};
 
using TelemetryEvent = std::variant<RequestStartEvent, RequestEndEvent, RetryEvent, RefreshEvent,
                                    ConfigClampedEvent>;
 
using TelemetryHook = std::function<void(const TelemetryEvent&)>;
 
}  // namespace axiam