Implementation Plan: High-Performance C++23 Prometheus Client

[stigsb]

Overview

High-performance, header-only C++23 Prometheus client library optimized for metric update throughput. Values stored as int64_t atomics (LOCK XADD on x86) — not double (CAS loop). Doubles produced only at scrape time.

See ARCHITECTURE.md for full design.

Implementation Phases

Phase 1: Core Primitives

• include/prometheus/detail/assert.hpp — PROMETHEUS_ASSERT macro (debug vs release)
• include/prometheus/counter.hpp — Counter class (atomic<int64_t>, inc(), load(), to_double())
• include/prometheus/gauge.hpp — Gauge class (set(), inc(), dec(), load())
• tests/test_counter.cpp — unit tests incl. concurrent stress test
• tests/test_gauge.cpp — unit tests incl. concurrent stress test

Phase 2: Label System

• include/prometheus/label_mask.hpp — LabelMask<T> alias, make_mask() consteval helper
• include/prometheus/label_def.hpp — PROMETHEUS_DEFINE_LABELS macro generating:
  • Key enum (power-of-two values)
  • LabelSet struct with std::optional fields
  • key_name(), populated_mask(), format_value(), all_keys() constexpr functions
• tests/test_label_def.cpp — macro expansion, mask arithmetic, key name mapping

Phase 3: Histogram

• include/prometheus/histogram.hpp — Histogram class template
  • Power-of-two bucket boundaries (min + count)
  • observe() — binary search + single fetch_add
  • Non-cumulative storage, cumulative sums at scrape time
• tests/test_histogram.cpp — bucket assignment, sum, count, edge cases

Phase 4: Storage & Metric Family

• include/prometheus/detail/label_key.hpp — canonical key string from LabelSet + allowed mask
• include/prometheus/detail/metric_store.hpp — shared_mutex + unordered_map<string, unique_ptr<MetricT>>
• include/prometheus/metric_family.hpp — MetricFamily<LabelTraits, MetricT> with get() returning stable references
• include/prometheus/metric_family_builder.hpp — fluent builder with required(), optional(), const_label(), buckets(), build()
• tests/test_metric_family.cpp — builder API, required/optional/forbidden label validation, handle stability

Phase 5: Registry & Exposition

• include/prometheus/text_serializer.hpp — Prometheus text format 0.0.4 writer
• include/prometheus/registry.hpp — Registry with counter<T>(), gauge<T>(), histogram<T>() entry points, serialize()
• include/prometheus/prometheus.hpp — convenience all-in-one include
• tests/test_text_serializer.cpp — format correctness (counter, gauge, histogram, const labels, scale)
• tests/test_registry.cpp — end-to-end registration + serialization

Phase 6: Examples & Polish

• examples/basic_usage.cpp — minimal working example
• examples/http_server_example.cpp — with cpp-httplib integration
• Benchmark suite — measure inc/observe throughput vs prometheus-cpp (jupp0r)
• CI setup (GitHub Actions — Clang 17+, GCC 13+)
• .clang-format and .clang-tidy configs

Key Design Decisions

Decision	Choice	Why
Value type	int64_t	LOCK XADD (1 instruction) vs double CAS loop
Memory ordering	relaxed everywhere	Prometheus scraping is best-effort; no cross-metric ordering needed
Label keys	enum class (power-of-two)	Bitmask operations for required/optional/forbidden checks
Label values	std::optional in aggregate	C++20 designated initializers: {.service = "api", .method = "GET"}
Histogram observe	Single fetch_add per call	Cumulative sums computed at scrape time (off hot path)
Metric lookup	shared_mutex + unordered_map	Contention only on first-seen label combo; cached handles bypass map entirely
Build	Header-only, CMake	Zero dependencies at runtime; GoogleTest for tests only

Non-Goals (for v0.1)

• No built-in HTTP server (bring your own)
• No push gateway support
• No Summary metric type (rarely needed; histograms preferred)
• No OpenMetrics format (Prometheus text format only)
• No dynamic label registration (labels are fixed at compile time per app)