feat(telemetry): add fluent API for meter telemetry configuration

Author: BenjaminAbt

README.md

@@ -159,7 +159,7 @@ public void ConfigureServices(IServiceCollection services)
 Core (`MyCSharp.HttpUserAgentParser`)
 
 - `parse-requests`
-- `parse-duration` (ms)
+- `parse-duration` (s)
 - `cache-concurrentdictionary-hit`
 - `cache-concurrentdictionary-miss`
 - `cache-concurrentdictionary-size`
@@ -185,6 +185,92 @@ dotnet-counters monitor --process-id <pid> MyCSharp.HttpUserAgentParser.MemoryCa
 dotnet-counters monitor --process-id <pid> MyCSharp.HttpUserAgentParser.AspNetCore
 ```
 
+## Telemetry (Meters)
+
+Native `System.Diagnostics.Metrics` instruments are **opt-in** per package.
+
+### Enable meters (Fluent API)
+
+Core parser meters:
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services
+        .AddHttpUserAgentParser()
+        .WithMeterTelemetry();
+}
+```
+
+MemoryCache meters:
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services
+        .AddHttpUserAgentMemoryCachedParser()
+        .WithMeterTelemetry() // core meters (optional)
+        .WithMemoryCacheMeterTelemetry();
+}
+```
+
+ASP.NET Core meters:
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services
+        .AddHttpUserAgentMemoryCachedParser()
+        .AddHttpUserAgentParserAccessor()
+        .WithAspNetCoreMeterTelemetry();
+}
+```
+
+### Meter names and instruments
+
+Core meter (default: `mycsharp.http_user_agent_parser`)
+
+- `parse.requests` (counter, `{call}`)
+- `parse.duration` (histogram, `s`)
+- `cache.hit` (counter, `{call}`)
+- `cache.miss` (counter, `{call}`)
+- `cache.size` (observable gauge, `{entry}`)
+
+MemoryCache meter (default: `mycsharp.http_user_agent_parser.memorycache`)
+
+- `cache.hit` (counter, `{call}`)
+- `cache.miss` (counter, `{call}`)
+- `cache.size` (observable gauge, `{entry}`)
+
+ASP.NET Core meter (default: `mycsharp.http_user_agent_parser.aspnetcore`)
+
+- `user_agent.present` (counter, `{call}`)
+- `user_agent.missing` (counter, `{call}`)
+
+### Meter prefix configuration
+
+The default prefix is `mycsharp.`. The prefix can be configured via DI:
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services
+        .AddHttpUserAgentParser()
+        .WithMeterTelemetryPrefix("acme.");
+}
+```
+
+Rules:
+
+- `""` (empty) is allowed and removes the prefix.
+- Otherwise the prefix must be **alphanumeric** and **end with `.`**.
+
+Example results:
+
+- Prefix `"mycsharp."` -> `mycsharp.http_user_agent_parser`
+- Prefix `""` -> `http_user_agent_parser`
+- Prefix `"acme."` -> `acme.http_user_agent_parser`
+
 ### Export to OpenTelemetry
 
 You can collect these EventCounters via OpenTelemetry metrics.

src/HttpUserAgentParser.AspNetCore/DependencyInjection/HttpUserAgentParserDependencyInjectionOptionsTelemetryExtensions.cs

@@ -31,4 +31,19 @@ public static HttpUserAgentParserDependencyInjectionOptions WithAspNetCoreMeterT
         HttpUserAgentParserAspNetCoreTelemetry.EnableMeters(meter);
         return options;
     }
+
+    /// <summary>
+    /// Enables native System.Diagnostics.Metrics telemetry for the AspNetCore package using a custom meter prefix.
+    /// </summary>
+    /// <param name="options">The options container.</param>
+    /// <param name="meterPrefix">The prefix to use for the meter name.</param>
+    /// <exception cref="ArgumentException">Thrown when the prefix is not empty and does not match the required format.</exception>
+    public static HttpUserAgentParserDependencyInjectionOptions WithAspNetCoreMeterTelemetryPrefix(
+        this HttpUserAgentParserDependencyInjectionOptions options,
+        string meterPrefix)
+    {
+        Meter meter = new(HttpUserAgentParserAspNetCoreMeters.GetMeterName(meterPrefix));
+        HttpUserAgentParserAspNetCoreTelemetry.EnableMeters(meter);
+        return options;
+    }
 }

src/HttpUserAgentParser.AspNetCore/HttpUserAgentParser.AspNetCore.csproj

@@ -24,4 +24,8 @@
         <ProjectReference Include="..\HttpUserAgentParser\HttpUserAgentParser.csproj" />
     </ItemGroup>
 
+    <ItemGroup>
+        <InternalsVisibleTo Include="MyCSharp.HttpUserAgentParser.AspNetCore.UnitTests" PublicKey="$(PublicKey)" />
+    </ItemGroup>
+
 </Project>

src/HttpUserAgentParser.AspNetCore/Telemetry/HttpUserAgentParserAspNetCoreMeters.cs

@@ -20,7 +20,51 @@ internal static class HttpUserAgentParserAspNetCoreMeters
     /// <summary>
     /// Name of the meter used to publish AspNetCore User-Agent metrics.
     /// </summary>
-    public const string MeterName = "mycsharp.http_user_agent_parser.aspnetcore";
+    private const string MeterNameSuffix = "http_user_agent_parser.aspnetcore";
+
+    /// <summary>
+    /// Name of the meter used to publish AspNetCore User-Agent metrics.
+    /// </summary>
+    public const string MeterName = "mycsharp." + MeterNameSuffix;
+
+    /// <summary>
+    /// Builds a meter name from a custom prefix.
+    /// </summary>
+    /// <param name="meterPrefix">
+    /// The prefix to use. When null, the default prefix is used. When empty,
+    /// no prefix is applied. Otherwise, the prefix must be alphanumeric and end with '.'.
+    /// </param>
+    /// <returns>The full meter name.</returns>
+    /// <exception cref="ArgumentException">Thrown when the prefix is not empty and does not match the required format.</exception>
+    public static string GetMeterName(string? meterPrefix)
+    {
+        if (meterPrefix is null)
+        {
+            return MeterName;
+        }
+
+        meterPrefix = meterPrefix.Trim();
+        if (meterPrefix.Length == 0)
+        {
+            return MeterNameSuffix;
+        }
+
+        if (!meterPrefix.EndsWith('.'))
+        {
+            throw new ArgumentException("Meter prefix must end with '.'.", nameof(meterPrefix));
+        }
+
+        for (int i = 0; i < meterPrefix.Length - 1; i++)
+        {
+            char c = meterPrefix[i];
+            if (!char.IsLetterOrDigit(c))
+            {
+                throw new ArgumentException("Meter prefix must be alphanumeric.", nameof(meterPrefix));
+            }
+        }
+
+        return meterPrefix + MeterNameSuffix;
+    }
 
     /// <summary>
     /// Indicates whether the meter and its instruments have been initialized.
@@ -91,4 +135,16 @@ public static void UserAgentPresent()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static void UserAgentMissing()
         => s_userAgentMissing?.Add(1);
+
+    /// <summary>
+    /// Resets static state to support isolated unit tests.
+    /// </summary>
+    public static void ResetForTests()
+    {
+        Volatile.Write(ref s_initialized, 0);
+
+        s_meter = null;
+        s_userAgentPresent = null;
+        s_userAgentMissing = null;
+    }
 }

src/HttpUserAgentParser.AspNetCore/Telemetry/HttpUserAgentParserAspNetCoreTelemetry.cs

@@ -125,4 +125,13 @@ public static void UserAgentMissing()
             HttpUserAgentParserAspNetCoreMeters.UserAgentMissing();
         }
     }
+
+    /// <summary>
+    /// Resets telemetry state for unit tests.
+    /// </summary>
+    public static void ResetForTests()
+    {
+        Volatile.Write(ref s_enabledFlags, 0);
+        HttpUserAgentParserAspNetCoreMeters.ResetForTests();
+    }
 }

src/HttpUserAgentParser.MemoryCache/DependencyInjection/HttpUserAgentParserDependencyInjectionOptionsTelemetryExtensions.cs

@@ -31,4 +31,19 @@ public static HttpUserAgentParserDependencyInjectionOptions WithMemoryCacheMeter
         HttpUserAgentParserMemoryCacheTelemetry.EnableMeters(meter);
         return options;
     }
+
+    /// <summary>
+    /// Enables native System.Diagnostics.Metrics telemetry for the MemoryCache provider using a custom meter prefix.
+    /// </summary>
+    /// <param name="options">The options container.</param>
+    /// <param name="meterPrefix">The prefix to use for the meter name.</param>
+    /// <exception cref="ArgumentException">Thrown when the prefix is not empty and does not match the required format.</exception>
+    public static HttpUserAgentParserDependencyInjectionOptions WithMemoryCacheMeterTelemetryPrefix(
+        this HttpUserAgentParserDependencyInjectionOptions options,
+        string meterPrefix)
+    {
+        Meter meter = new(HttpUserAgentParserMemoryCacheMeters.GetMeterName(meterPrefix));
+        HttpUserAgentParserMemoryCacheTelemetry.EnableMeters(meter);
+        return options;
+    }
 }

src/HttpUserAgentParser.MemoryCache/HttpUserAgentParser.MemoryCache.csproj

@@ -25,4 +25,8 @@
         <ProjectReference Include="..\HttpUserAgentParser\HttpUserAgentParser.csproj" />
     </ItemGroup>
 
+    <ItemGroup>
+        <InternalsVisibleTo Include="MyCSharp.HttpUserAgentParser.MemoryCache.UnitTests" PublicKey="$(PublicKey)" />
+    </ItemGroup>
+
 </Project>

src/HttpUserAgentParser.MemoryCache/Telemetry/HttpUserAgentParserMemoryCacheMeters.cs

@@ -12,7 +12,48 @@ namespace MyCSharp.HttpUserAgentParser.MemoryCache.Telemetry;
 [ExcludeFromCodeCoverage]
 internal static class HttpUserAgentParserMemoryCacheMeters
 {
-    public const string MeterName = HttpUserAgentParserMemoryCachedProvider.MeterName;
+    private const string MeterNameSuffix = "http_user_agent_parser.memorycache";
+
+    public const string MeterName = "mycsharp." + MeterNameSuffix;
+
+    /// <summary>
+    /// Builds a meter name from a custom prefix.
+    /// </summary>
+    /// <param name="meterPrefix">
+    /// The prefix to use. When null, the default prefix is used. When empty,
+    /// no prefix is applied. Otherwise, the prefix must be alphanumeric and end with '.'.
+    /// </param>
+    /// <returns>The full meter name.</returns>
+    /// <exception cref="ArgumentException">Thrown when the prefix is not empty and does not match the required format.</exception>
+    public static string GetMeterName(string? meterPrefix)
+    {
+        if (meterPrefix is null)
+        {
+            return MeterName;
+        }
+
+        meterPrefix = meterPrefix.Trim();
+        if (meterPrefix.Length == 0)
+        {
+            return MeterNameSuffix;
+        }
+
+        if (!meterPrefix.EndsWith('.'))
+        {
+            throw new ArgumentException("Meter prefix must end with '.'.", nameof(meterPrefix));
+        }
+
+        for (int i = 0; i < meterPrefix.Length - 1; i++)
+        {
+            char c = meterPrefix[i];
+            if (!char.IsLetterOrDigit(c))
+            {
+                throw new ArgumentException("Meter prefix must be alphanumeric.", nameof(meterPrefix));
+            }
+        }
+
+        return meterPrefix + MeterNameSuffix;
+    }
 
     private static int s_initialized;
 
@@ -54,4 +95,14 @@ public static void Enable(Meter? meter = null)
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static void CacheMiss() => s_cacheMiss?.Add(1);
+
+    public static void ResetForTests()
+    {
+        Volatile.Write(ref s_initialized, 0);
+
+        s_meter = null;
+        s_cacheHit = null;
+        s_cacheMiss = null;
+        s_cacheSize = null;
+    }
 }

src/HttpUserAgentParser.MemoryCache/Telemetry/HttpUserAgentParserMemoryCacheTelemetry.cs

@@ -120,4 +120,14 @@ public static void CacheSizeIncrement()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static void CacheSizeDecrement()
         => HttpUserAgentParserMemoryCacheTelemetryState.CacheSizeDecrement();
+
+    /// <summary>
+    /// Resets telemetry state for unit tests.
+    /// </summary>
+    public static void ResetForTests()
+    {
+        Volatile.Write(ref s_enabledFlags, 0);
+        HttpUserAgentParserMemoryCacheTelemetryState.ResetForTests();
+        HttpUserAgentParserMemoryCacheMeters.ResetForTests();
+    }
 }

src/HttpUserAgentParser.MemoryCache/Telemetry/HttpUserAgentParserMemoryCacheTelemetryState.cs

@@ -39,4 +39,9 @@ internal static class HttpUserAgentParserMemoryCacheTelemetryState
     /// Uses an atomic operation to remain safe in concurrent scenarios.
     /// </remarks>
     public static void CacheSizeDecrement() => Interlocked.Decrement(ref s_cacheSize);
+
+    /// <summary>
+    /// Resets the cache size for unit tests.
+    /// </summary>
+    public static void ResetForTests() => Volatile.Write(ref s_cacheSize, 0);
 }