metrics.hpp

Go to the documentation of this file.

#pragma once
 
 
#include <prom/prom.hpp>
 
#include <memory>
 
namespace threadman::metrics {
 
inline std::shared_ptr<prom::Scope>& scope() {
    static std::shared_ptr<prom::Scope> sc =
        prom::scope("threadman", prom::ScopeConfig{.prefix = "tm_"});
    return sc;
}
 
// ---------------------------------------------------------------------------
// pool — `thread_pool.hpp`; series selected by the `pool` label (pool name).
// ---------------------------------------------------------------------------
 
inline prom::Counter& pool_tasks_submitted() {
    static prom::Counter m =
        scope()->counter({.name = "pool_tasks_submitted_total",
                          .help = "Tasks submitted to a thread pool (all submit variants)."});
    return m;
}
 
inline prom::Counter& pool_tasks_completed() {
    static prom::Counter m =
        scope()->counter({.name = "pool_tasks_completed_total",
                          .help = "Tasks that ran to completion on a pool worker."});
    return m;
}
 
inline prom::Counter& pool_tasks_failed() {
    static prom::Counter m = scope()->counter(
        {.name = "pool_tasks_failed_total", .help = "Tasks whose body threw an exception."});
    return m;
}
 
inline prom::Counter& pool_tasks_cancelled() {
    static prom::Counter m =
        scope()->counter({.name = "pool_tasks_cancelled_total",
                          .help = "Tasks cancelled before running (drained by shutdown_now)."});
    return m;
}
 
inline prom::Counter& pool_queue_rejected() {
    static prom::Counter m =
        scope()->counter({.name = "pool_queue_rejected_total",
                          .help = "Submissions rejected because a bounded queue was full."});
    return m;
}
 
inline prom::Counter& pool_submit_rejected() {
    static prom::Counter m = scope()->counter(
        {.name = "pool_submit_rejected_total",
         .help = "Submissions rejected because the pool was shutting down or terminated."});
    return m;
}
 
inline prom::Counter& pool_scale_ups() {
    static prom::Counter m = scope()->counter(
        {.name = "pool_scale_ups_total", .help = "Non-core workers spawned by a scale-up."});
    return m;
}
 
inline prom::Counter& pool_scale_downs() {
    static prom::Counter m = scope()->counter(
        {.name = "pool_scale_downs_total", .help = "Non-core workers retired after idling out."});
    return m;
}
 
inline prom::Gauge& pool_queue_depth() {
    static prom::Gauge m = scope()->gauge(
        {.name = "pool_queue_depth", .help = "Tasks currently waiting in a pool's queue."});
    return m;
}
 
inline prom::Gauge& pool_workers() {
    static prom::Gauge m =
        scope()->gauge({.name = "pool_workers", .help = "Live workers in a pool."});
    return m;
}
 
inline prom::Gauge& pool_workers_active() {
    static prom::Gauge m = scope()->gauge(
        {.name = "pool_workers_active", .help = "Workers currently executing a task."});
    return m;
}
 
inline prom::Gauge& pool_workers_idle() {
    static prom::Gauge m = scope()->gauge(
        {.name = "pool_workers_idle", .help = "Workers currently idle on the queue."});
    return m;
}
 
inline prom::Histogram& pool_task_execution_seconds() {
    static prom::Histogram m = scope()->histogram(
        {.name = "pool_task_execution_seconds",
         .help = "Wall-clock seconds a task body spent executing.",
         .buckets = {0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0}});
    return m;
}
 
inline prom::Histogram& pool_task_queue_wait_seconds() {
    static prom::Histogram m = scope()->histogram(
        {.name = "pool_task_queue_wait_seconds",
         .help = "Seconds a task waited in the queue before a worker picked it up.",
         .buckets = {0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0}});
    return m;
}
 
// ---------------------------------------------------------------------------
// thread — `thread.hpp`; no label.
// ---------------------------------------------------------------------------
 
inline prom::Counter& threads_created() {
    static prom::Counter m = scope()->counter(
        {.name = "threads_created_total", .help = "ManagedThread bodies that started running."});
    return m;
}
 
inline prom::Counter& threads_completed() {
    static prom::Counter m =
        scope()->counter({.name = "threads_completed_total",
                          .help = "ManagedThread bodies that returned normally."});
    return m;
}
 
inline prom::Counter& threads_failed() {
    static prom::Counter m = scope()->counter(
        {.name = "threads_failed_total", .help = "ManagedThread bodies that exited by throwing."});
    return m;
}
 
inline prom::Gauge& threads_live() {
    static prom::Gauge m =
        scope()->gauge({.name = "threads_live", .help = "ManagedThread bodies currently running."});
    return m;
}
 
// ---------------------------------------------------------------------------
// manager — `manager.hpp`; no label.
// ---------------------------------------------------------------------------
 
inline prom::Counter& manager_threads_registered() {
    static prom::Counter m =
        scope()->counter({.name = "manager_threads_registered_total",
                          .help = "Thread control blocks registered with the manager."});
    return m;
}
 
inline prom::Counter& manager_summaries_published() {
    static prom::Counter m =
        scope()->counter({.name = "manager_summaries_published_total",
                          .help = "Periodic ManagerSummary payloads published to listeners."});
    return m;
}
 
inline prom::Gauge& manager_pools_live() {
    static prom::Gauge m = scope()->gauge(
        {.name = "manager_pools_live", .help = "Pools currently registered with the manager."});
    return m;
}
 
// ---------------------------------------------------------------------------
// task / stuck — `manager.hpp`; `tasks_stuck_detected_total` labelled `pool_id`.
// ---------------------------------------------------------------------------
 
inline prom::Counter& tasks_stuck_detected() {
    static prom::Counter m = scope()->counter(
        {.name = "tasks_stuck_detected_total",
         .help = "Distinct tasks newly detected as stuck (running past the threshold)."});
    return m;
}
 
inline prom::Gauge& tasks_stuck_current() {
    static prom::Gauge m = scope()->gauge(
        {.name = "tasks_stuck_current", .help = "Tasks currently flagged as stuck."});
    return m;
}
 
// ---------------------------------------------------------------------------
// future — `future.hpp`; no label.
// ---------------------------------------------------------------------------
 
inline prom::Counter& futures_created() {
    static prom::Counter m = scope()->counter(
        {.name = "futures_created_total", .help = "Promise/Future pairs created."});
    return m;
}
 
inline prom::Counter& futures_satisfied_value() {
    static prom::Counter m = scope()->counter(
        {.name = "futures_satisfied_value_total", .help = "Futures satisfied with a value."});
    return m;
}
 
inline prom::Counter& futures_satisfied_exception() {
    static prom::Counter m = scope()->counter({.name = "futures_satisfied_exception_total",
                                               .help = "Futures satisfied with an exception."});
    return m;
}
 
inline prom::Counter& future_continuations_registered() {
    static prom::Counter m = scope()->counter(
        {.name = "future_continuations_registered_total",
         .help = "Continuations registered against a future (.then / .on_error)."});
    return m;
}
 
inline prom::Counter& future_continuations_dispatched() {
    static prom::Counter m =
        scope()->counter({.name = "future_continuations_dispatched_total",
                          .help = "Continuations dispatched through an executor."});
    return m;
}
 
inline void warm_up() {
    scope();
    // Force each metric's lazy bind now (a discarded empty-label child binds the
    // parent family without recording any value), so the first runtime `inc` /
    // `observe` / `set` — some of which sit on latency-sensitive paths such as
    // promise satisfaction — takes the fast path instead of paying a first-use
    // bind. Counter::labels is [[nodiscard]]; cast away.
    const prom::Labels none{};
    auto bind_counter = [&](const prom::Counter& c) { (void)c.labels(none); };
    auto bind_gauge = [&](const prom::Gauge& g) { (void)g.labels(none); };
    auto bind_histogram = [&](const prom::Histogram& h) { (void)h.labels(none); };
 
    bind_counter(pool_tasks_submitted());
    bind_counter(pool_tasks_completed());
    bind_counter(pool_tasks_failed());
    bind_counter(pool_tasks_cancelled());
    bind_counter(pool_queue_rejected());
    bind_counter(pool_submit_rejected());
    bind_counter(pool_scale_ups());
    bind_counter(pool_scale_downs());
    bind_gauge(pool_queue_depth());
    bind_gauge(pool_workers());
    bind_gauge(pool_workers_active());
    bind_gauge(pool_workers_idle());
    bind_histogram(pool_task_execution_seconds());
    bind_histogram(pool_task_queue_wait_seconds());
    bind_counter(threads_created());
    bind_counter(threads_completed());
    bind_counter(threads_failed());
    bind_gauge(threads_live());
    bind_counter(manager_threads_registered());
    bind_counter(manager_summaries_published());
    bind_gauge(manager_pools_live());
    bind_counter(tasks_stuck_detected());
    bind_gauge(tasks_stuck_current());
    bind_counter(futures_created());
    bind_counter(futures_satisfied_value());
    bind_counter(futures_satisfied_exception());
    bind_counter(future_continuations_registered());
    bind_counter(future_continuations_dispatched());
}
 
}  // namespace threadman::metrics