feat(telemetry): enhance telemetry documentation and add meters support

Author: BenjaminAbt

src/HttpUserAgentParser/Telemetry/HttpUserAgentParserMeters.cs

@@ -10,6 +10,10 @@ namespace MyCSharp.HttpUserAgentParser.Telemetry;
 /// System.Diagnostics.Metrics instruments emitted by MyCSharp.HttpUserAgentParser.
 /// This is opt-in and designed to keep overhead negligible unless a listener is enabled.
 /// </summary>
+/// <remarks>
+/// Instruments are created once on first enablement and emit no data unless observed
+/// by an active listener.
+/// </remarks>
 [ExcludeFromCodeCoverage]
 internal static class HttpUserAgentParserMeters
 {
@@ -40,8 +44,11 @@ internal static class HttpUserAgentParserMeters
     public static bool IsParseDurationEnabled => s_parseDurationMs?.Enabled ?? false;
 
     /// <summary>
-    /// Initializes the meter and creates the instruments (idempotent).
+    /// Initializes the meter and creates all metric instruments.
     /// </summary>
+    /// <remarks>
+    /// Initialization is performed at most once. Subsequent calls are ignored.
+    /// </remarks>
     public static void Enable(Meter? meter = null)
     {
         if (Interlocked.Exchange(ref s_initialized, 1) == 1)

src/HttpUserAgentParser/Telemetry/HttpUserAgentParserTelemetry.cs

@@ -61,7 +61,17 @@ public static bool IsCacheSizeEnabled
     /// Enables core EventCounter telemetry for the parser.
     /// </summary>
     public static void Enable() => Interlocked.Or(ref s_enabledFlags, EventCountersFlag);
-/// <summary>
+
+    /// <summary>
+    /// Enables native System.Diagnostics.Metrics telemetry for the parser.
+    /// </summary>
+    public static void EnableMeters(Meter? meter = null)
+    {
+        HttpUserAgentParserMeters.Enable(meter);
+        Interlocked.Or(ref s_enabledFlags, MetersFlag);
+    }
+
+    /// <summary>
     /// Records a parse request event.
     /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -144,18 +154,8 @@ public static void ConcurrentCacheSizeSet(int size)
 
 #if DEBUG
     /// <summary>
-    /// Resets telemetry state for unit testing.
-    /// </summary>f ((flags & MetersFlag) != 0)
-        {
-            HttpUserAgentParserMeters.ConcurrentCacheMiss();
-        }
-    }
-
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public static void ConcurrentCacheSizeSet(int size)
-        => HttpUserAgentParserTelemetryState.SetConcurrentCacheSize(size);
-
-#if DEBUG
+    /// Resets static state to support isolated unit tests.
+    /// </summary>
     public static void ResetForTests()
     {
         Volatile.Write(ref s_enabledFlags, 0);

src/HttpUserAgentParser/Telemetry/HttpUserAgentParserTelemetryState.cs

@@ -4,16 +4,37 @@
 
 namespace MyCSharp.HttpUserAgentParser.Telemetry;
 
+/// <summary>
+/// Holds shared telemetry state for the concurrent dictionary cache.
+/// </summary>
+/// <remarks>
+/// The state is updated independently of whether telemetry is currently enabled
+/// so that polling-based instruments can report correct values once a listener
+/// attaches.
+/// </remarks>
 [ExcludeFromCodeCoverage]
 internal static class HttpUserAgentParserTelemetryState
 {
     private static long s_concurrentCacheSize;
 
-    public static long ConcurrentCacheSize => Volatile.Read(ref s_concurrentCacheSize);
+    /// <summary>
+    /// Gets the current size of the concurrent dictionary cache.
+    /// </summary>
+    public static long ConcurrentCacheSize
+        => Volatile.Read(ref s_concurrentCacheSize);
 
-    public static void SetConcurrentCacheSize(int size) => Volatile.Write(ref s_concurrentCacheSize, size);
+    /// <summary>
+    /// Updates the current size of the concurrent dictionary cache.
+    /// </summary>
+    /// <param name="size">Current number of entries in the cache.</param>
+    public static void SetConcurrentCacheSize(int size)
+        => Volatile.Write(ref s_concurrentCacheSize, size);
 
 #if DEBUG
-    public static void ResetForTests() => Volatile.Write(ref s_concurrentCacheSize, 0);
+    /// <summary>
+    /// Resets the telemetry state for unit tests.
+    /// </summary>
+    public static void ResetForTests()
+        => Volatile.Write(ref s_concurrentCacheSize, 0);
 #endif
 }