Metrics¶

Use this page to publish metrics with Quill and export them through either a custom sink or the built-in PrometheusSink.

Quill’s metric API gives you a low-latency transport for publishing application metric samples to an external metrics backend (Prometheus, StatsD, OpenTelemetry, or any in-process collector) through the same asynchronous pipeline used for logs. Quill does not aggregate or expose metrics on its own — your sink hands samples off to the metrics backend, which is responsible for storage, aggregation, and exposition.

• Register once, publish cheaply — metric names and labels live in a stable MetricMetadata object; the hot path enqueues only a pointer and a double sample.

• Same backend worker as logs — no dedicated metrics thread, no extra context-switch cost, no duplicate formatting path on hot threads.

• Backend-agnostic transport — the metric API itself transports only (timestamp, MetricMetadata*, Logger*, double). Sinks decide where samples go.

• Ready-made Prometheus exporter — the built-in PrometheusSink handles counters, gauges, histograms, and summaries, including an optional HTTP exposer.

Metrics go through the same backend worker as logs. You register MetricMetadata once during setup, keep the returned pointer, and then publish double samples through a logger. The sink attached to that logger receives the samples on the backend thread through Sink::write_metric().

Registering Metrics¶

Create metric metadata during setup and store the returned pointer where the hot path can reuse it:

quill::MetricMetadata const* requests_total = quill::Frontend::create_metric(
  "requests_total_post_500", "requests_total", {{"method", "POST"}, {"status", "500"}});

quill::MetricMetadata const* request_latency = quill::Frontend::create_metric(
  "request_latency_post", "request_latency_seconds", {{"method", "POST"}});

The first argument is a unique metric_key used for lookup. The second is the metric name. The third is the set of static labels for that series.

If you want create-or-reuse semantics, use Frontend::create_or_get_metric() instead. It looks up by metric_key and returns the existing metadata pointer unchanged if one already exists.

The returned MetricMetadata* is a stable pointer that lives for the entire program duration, so you can safely cache it in globals, class members, or anywhere else the hot path can reach.

One MetricMetadata per Label Combination¶

Labels on MetricMetadata are fixed at registration time. Each distinct combination of label values is a separate time series and needs its own MetricMetadata pointer. This is intentional: the hot path stays a pointer plus a double, with no per-sample label lookup or string work.

If you have a known, bounded set of label values, register one MetricMetadata per combination up front and dispatch to the right pointer on the hot path:

// For an endpoint that can answer GET/POST and return 200/500, register all four series
// during setup and keep the pointers where the hot path can reach them.
std::unordered_map<std::pair<std::string, std::string>, quill::MetricMetadata const*, ...> by_method_status;

for (auto const& method : {"GET", "POST"})
{
  for (auto const& status : {"200", "500"})
  {
    std::string key = std::string{"requests_total_"} + method + "_" + status;
    by_method_status[{method, status}] = quill::Frontend::create_metric(
      key, "requests_total", {{"method", method}, {"status", status}});
  }
}

// Hot path: pick the right pre-registered metadata pointer, then publish.
METRIC(metrics_logger, by_method_status[{method, status}], 1.0);

Avoid creating MetricMetadata on the hot path. MetricMetadata objects live in a global manager for the entire program duration and are not freed; creating them per-request would leak memory and serialize on the manager’s lock.

If your label values are not known up front (for example, a label that takes user-provided strings), drive the registration of new series from a setup or admin path rather than from the request path.

Publishing Samples¶

Metrics are published through a logger that is bound to a sink implementing write_metric():

// CustomMetricSink derives from quill::Sink and implements write_metric().
auto metric_sink = quill::Frontend::create_or_get_sink<CustomMetricSink>("metric_sink");
quill::Logger* metrics_logger =
  quill::Frontend::create_or_get_logger("metrics", std::move(metric_sink));

// Using the macro, for symmetry with LOG_*.
METRIC(metrics_logger, requests_total, 1.0);

// Or the function form, if you prefer.
metrics_logger->publish_metric(request_latency, 0.0023);

Use METRIC(...) if you want a macro that mirrors the LOG_* APIs, or call Logger::publish_metric() directly.

The publish call only queues the sample. The sink receives it on the backend worker thread, together with the metric metadata, timestamp, thread information, process id, logger name, and the sample value.

Writing a Metric Sink¶

Metrics are delivered on the backend worker through the virtual method Sink::write_metric(). The default implementation is a no-op, so existing log sinks do not need any changes.

• Log-only sinks keep the default no-op write_metric() and ignore metric events.

• Metric-only sinks implement write_metric() and can leave write_log() as a no-op.

• Mixed sinks implement both methods and handle logs and metrics in the same sink.

This lets you export metrics to Prometheus, StatsD, Graphite, OpenTelemetry, or any other backend.

Using PrometheusSink¶

PrometheusSink is the built-in sink for Prometheus. After creating the sink, register each metric on it as a counter, gauge, histogram, or summary:

auto prom_sink = std::static_pointer_cast<quill::PrometheusSink>(
  quill::Frontend::create_or_get_sink<quill::PrometheusSink>("prometheus_sink", exposer_config));

prom_sink->register_counter(requests_total, "Total number of handled requests");
prom_sink->register_histogram(request_latency, "Request latency in seconds",
                              {0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0});

Quill itself only transports double samples. The Prometheus type is chosen when you register the metric on PrometheusSink.

Histogram Bucket Helpers¶

Prometheus histograms need a strictly increasing list of bucket boundaries. Quill ships small helpers so you don’t have to spell those out by hand. Quill has no opinion on the units, since some users measure in nanoseconds, others in milliseconds, seconds, bytes, dollars, etc.

• linear_buckets(start, width, count) — evenly-spaced boundaries.

  Each bucket is the previous one plus width.

  Example: linear_buckets(0.0, 5.0, 5) → {0, 5, 10, 15, 20}.

  start may be negative, which is useful when the metric can go below zero (for example, linear_buckets(-5.0, 1.0, 11) → {-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5}). width must be > 0.

• exponential_buckets(start, factor, count) — geometrically-spaced boundaries.

  Each bucket is the previous one multiplied by factor.

  Example: exponential_buckets(1.0, 2.0, 5) → {1, 2, 4, 8, 16}. Example: exponential_buckets(0.001, 10.0, 4) → {0.001, 0.01, 0.1, 1}.

  Use this when the metric spans several orders of magnitude (latencies, sizes). start must be > 0 and factor must be > 1. For signed quantities, construct the bucket vector by hand — a strictly-increasing list of doubles is all Prometheus requires.

Quick rule of thumb: pick linear when each step should differ by the same amount, and exponential when each step should differ by the same factor.

prom_sink->register_histogram(request_latency, "Request latency in seconds",
                              quill::PrometheusSink::exponential_buckets(0.001, 2.0, 10));

Full examples¶

Custom metric sink:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

#include "quill/Backend.h"
#include "quill/Frontend.h"
#include "quill/LogMacros.h"
#include "quill/Logger.h"
#include "quill/sinks/Sink.h"

#include <cstdint>
#include <iostream>
#include <string>
#include <string_view>
#include <utility>
#include <vector>

class MyMetricSink final : public quill::Sink
{
public:
  void write_log(quill::MacroMetadata const* /** log_metadata **/, uint64_t /** log_timestamp **/,
                 std::string_view /** thread_id **/, std::string_view /** thread_name **/,
                 std::string const& /** process_id **/, std::string_view /** logger_name **/,
                 quill::LogLevel /** log_level **/, std::string_view /** log_level_description **/,
                 std::string_view /** log_level_short_code **/,
                 std::vector<std::pair<std::string, std::string>> const* /** named_args **/,
                 std::string_view /** log_message **/, std::string_view /** log_statement **/) override
  {
  }

  void flush_sink() noexcept override {}

  // Called on the backend worker thread for every published sample.
  void write_metric(quill::MetricMetadata const* metric_metadata, uint64_t /** log_timestamp **/,
                    std::string_view /** thread_id **/, std::string_view /** thread_name **/,
                    std::string const& /** process_id **/, std::string_view /** logger_name **/, double value) override
  {
    // Export however you like: Prometheus, StatsD, OpenTelemetry, a socket...
    std::cout << metric_metadata->metric_name() << " = " << value << '\n';
  }
};

int main()
{
  quill::Backend::start();

  auto sink = quill::Frontend::create_or_get_sink<MyMetricSink>("my_metric_sink");
  quill::Logger* logger = quill::Frontend::create_or_get_logger("metrics", std::move(sink));

  // Register metric metadata once. The returned pointer is stable for the program lifetime.
  quill::MetricMetadata const* requests_total = quill::Frontend::create_metric(
    "requests_total_post_200", "requests_total", {{"method", "POST"}, {"status", "200"}});

  // Publish samples from the hot path.
  logger->publish_metric(requests_total, 1.0);
}

Prometheus integration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

#include "quill/Backend.h"
#include "quill/Frontend.h"
#include "quill/LogMacros.h"
#include "quill/Logger.h"
#include "quill/sinks/ConsoleSink.h"
#include "quill/sinks/metrics/PrometheusSink.h"

#include <iostream>
#include <string>
#include <utility>

/**
 * This example shows regular logging to a ConsoleSink and metric publishing to a real
 * prometheus-cpp registry through `quill::PrometheusSink`.
 *
 * Quill keeps metric metadata generic. The Prometheus-specific registration happens on the sink:
 * the sink decides whether a metric is exported as a counter, gauge, histogram, or summary.
 * `PrometheusSink` infers the Prometheus type from how the caller registered the metric
 * (register_counter / register_gauge / register_histogram / register_summary).
 */
int main()
{
  // Start the backend worker before creating loggers and publishing metrics.
  quill::Backend::start();

  // Regular application logs go to the console.
  auto console_sink = quill::Frontend::create_or_get_sink<quill::ConsoleSink>("sink_id_1");
  quill::Logger* logger = quill::Frontend::create_or_get_logger("root", std::move(console_sink));

  // Regular logs use the normal logging API.
  LOG_INFO(logger, "{} Set up metrics example {}", "===", "===");

  // Register Quill metric metadata once and keep the returned pointers for the hot path.
  quill::MetricMetadata const* requests_total_metric = quill::Frontend::create_metric(
    "requests_total", "requests_total", {{"method", "POST"}, {"status", "500"}});

  quill::MetricMetadata const* in_flight_requests_metric =
    quill::Frontend::create_metric("in_flight_requests", "in_flight_requests");

  quill::MetricMetadata const* request_latency_metric = quill::Frontend::create_metric(
    "request_latency_seconds", "request_latency_seconds", {{"method", "POST"}});

  // The sink owns the prometheus-cpp registry and can optionally start an HTTP exposer.
  quill::PrometheusSink::ExposerConfiguration exposer_config;
  exposer_config.bind_address = "127.0.0.1:45165";
  exposer_config.num_threads = 1;

  // Create Prometheus Sink
  auto prom_sink = std::static_pointer_cast<quill::PrometheusSink>(
    quill::Frontend::create_or_get_sink<quill::PrometheusSink>("prometheus_sink", exposer_config));

  // Prometheus-specific registration lives on the sink.
  prom_sink->register_counter(requests_total_metric, "Total number of handled requests");

  prom_sink->register_gauge(in_flight_requests_metric, "Current in-flight request count",
                            quill::PrometheusSink::GaugeUpdateMode::Add);

  prom_sink->register_histogram(request_latency_metric, "Request latency in seconds",
                                {0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0});

  LOG_INFO(logger, "scrape_endpoint: {}", prom_sink->exposer_scrape_endpoint());

  // Create metrics logger to sink
  quill::Logger* metrics_logger = quill::Frontend::create_or_get_logger("metrics", std::move(prom_sink));

  int32_t requests_total{0};
  while (true)
  {
    std::this_thread::sleep_for(std::chrono::seconds{20});

    // update metrics - macros for consistency
    METRIC(metrics_logger, requests_total_metric, ++requests_total);
    METRIC(metrics_logger, in_flight_requests_metric, 1);

    // or the as function
    metrics_logger->publish_metric(request_latency_metric, 3.0);
    metrics_logger->publish_metric(requests_total_metric, 1.0);
  }
}