Add performance note to header

Also improve implementation comments

src/metric.cpp

@@ -1405,8 +1405,7 @@ Family<Gauge> create_gauge(std::string_view name, std::string_view help) {
   auto name_view = arena_copy_string(name, global_arena);
   auto &familyPtr = Metric::get_gauge_families()[name_view];
   if (!familyPtr) {
-    // NOTE: Family<T>::State instances are never destroyed - this is fine
+    // Family<T>::State instances use ArenaAllocator::Ptr for automatic cleanup
-    // because the number of metric families is bounded by application design
     familyPtr = global_arena.construct<Family<Gauge>::State>(global_arena);
     familyPtr->name = name_view;
     familyPtr->help = arena_copy_string(help, global_arena);
@@ -1430,8 +1429,7 @@ Family<Histogram> create_histogram(std::string_view name, std::string_view help,
   auto name_view = arena_copy_string(name, global_arena);
   auto &family_ptr = Metric::get_histogram_families()[name_view];
   if (!family_ptr) {
-    // NOTE: Family<T>::State instances are never destroyed - this is fine
+    // Family<T>::State instances use ArenaAllocator::Ptr for automatic cleanup
-    // because the number of metric families is bounded by application design
     family_ptr = global_arena.construct<Family<Histogram>::State>(global_arena);
     family_ptr->name = name_view;
     family_ptr->help = arena_copy_string(help, global_arena);

src/metric.hpp

@@ -20,6 +20,14 @@
 // typical Prometheus client libraries that support multiple registries.
 // This design choice prioritizes simplicity and performance over flexibility.
 //
+// PERFORMANCE NOTE:
+// Family registration operations (create_counter/gauge/histogram), metric
+// instance creation (.create()), and render() use a global mutex for thread
+// safety. Registration operations should be performed during application
+// initialization, not in performance-critical paths. Metric update operations
+// (inc/dec/set/observe) are designed for high-frequency use and do not contend
+// on the global mutex.
+//
 // METRIC LIFECYCLE:
 // Metrics are created once and persist for the application lifetime. There is
 // no unregistration mechanism - this prevents accidental metric loss and