From 8b828be0a993cab0490aa82d9a0e3916eb9ee6ec Mon Sep 17 00:00:00 2001
From: Andrew Noyes <andrew@weaselab.dev>
Date: Sun, 31 Aug 2025 14:43:34 -0400
Subject: [PATCH] Advise to cache Metric instance

---
 src/metric.hpp | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/metric.hpp b/src/metric.hpp
index c00e300..3811653 100644
--- a/src/metric.hpp
+++ b/src/metric.hpp
@@ -123,10 +123,14 @@ template <class T> struct Family {
   static_assert(std::is_same_v<T, Counter> || std::is_same_v<T, Gauge> ||
                 std::is_same_v<T, Histogram>);
 
-  // Create metric instance with specific labels
-  // Labels are sorted by key for Prometheus compatibility
-  // ERROR: Will abort if labels already registered via register_callback()
-  // OK: Multiple calls with same labels return same instance (idempotent)
+  // Create metric instance with specific labels.
+  // For performance, it is recommended to create instances once and cache them
+  // for reuse, rather than calling .create() repeatedly in
+  // performance-critical paths.
+  //
+  // Labels are sorted by key for Prometheus compatibility.
+  // ERROR: Will abort if labels already registered via register_callback().
+  // OK: Multiple calls with same labels return same instance (idempotent).
   T create(std::initializer_list<std::pair<std::string_view, std::string_view>>
                labels) {
     return create(