Add performance note to header

Also improve implementation comments

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