Explainer: Memory Cache Metrics API with Eviction Tracking

[rjmurillo]

Note

Polyfill Status: The .NET runtime is adding native cache metrics in .NET 11 via dotnet/runtime#124140 (API-approved, milestone 11.0.0). This library serves as a polyfill for .NET 8/9/10 applications until .NET 11 reaches GA in November 2026. The API surface intentionally mirrors the approved runtime design (meter name, instrument names, tag schema) to ensure a smooth migration path.

Items below marked strikethrough were not approved by the .NET API review board (bartonjs review). Items marked with ✅ are implemented in the current codebase.

Introduction/Overview

The Memory Cache Metrics API with Eviction Tracking addresses critical performance issues in containerized environments where memory pressure can cause cache thrashing, leading to degraded application performance. This feature modernizes cache usage patterns by providing visibility into cache behavior and enabling proactive memory pressure handling.

The primary goal is to prevent performance degradation by tracking cache evictions, providing comprehensive metrics, and supporting both global default caches and component-specific caches in a backward-compatible manner.

Goals

1. ✅ Provide eviction visibility: Track and report cache eviction counts with ~100ns acceptable overhead per operation
2. ✅ Enable proactive monitoring: Support comprehensive cache metrics (hits, misses, eviction reasons, memory usage)
3. ✅ Support modern deployment patterns: Design for container-friendly memory management with dynamic sizing capabilities
4. ✅ Maintain backward compatibility: Ensure existing applications using MemoryCacheStatistics continue to work without modification
5. ✅ Enable external integration: Support export to monitoring systems (Prometheus, Application Insights, OpenTelemetry)
6. ✅ Provide flexible registration: Support both automatic DI-based registration and explicit component-specific cache registration

Non-Goals (Out of Scope)

• Automatic cache size adjustment based on memory pressure (future enhancement)
• Custom eviction policy implementation
• Cache data persistence or recovery mechanisms
• Real-time alerting or notification systems
• Performance optimization beyond the ~100ns overhead target
• Migration tools for existing custom monitoring solutions
• Distributed, nested, or hierarchical cache; use HybridCache
• Recommendations for cache size limits based on container memory constraints

User Stories

1. ✅ As a service developer, I want to track eviction counts in my application's default memory cache so that I can identify when memory pressure is causing performance issues.
2. ✅ As a library author, I want to register my component's cache with a metrics system so that service owners can monitor my library's cache behavior alongside their application caches.
3. ✅ As a DevOps engineer, I want to export cache metrics to Prometheus so that I can create dashboards and alerts for cache performance in containerized environments.
4. ✅ As a performance engineer, I want to distinguish between different eviction reasons (memory pressure vs expiration) so that I can identify true performance problems versus normal cache operation.
5. As an application architect, I want to configure cache metrics collection with different sampling rates so that I can balance monitoring granularity with performance overhead. — Not approved. Observable instruments have zero hot-path overhead, making sampling unnecessary.

Functional Requirements

1. ✅ The system must extend MemoryCacheStatistics to include TotalEvictedEntries property without breaking existing applications. Implemented via custom CacheStatistics class; the BCL MemoryCacheStatistics.TotalEvictions property is approved for .NET 11 in dotnet/runtime#124140.
2. The system must provide a MemoryCacheMetrics service that can register and track multiple named caches through dependency injection. — Not approved. The .NET API review rejected the IMemoryCacheMetrics registry pattern as "non-intuitive" in favor of native metrics on MemoryCache via IMeterFactory.
3. ✅ The system must support eviction tracking with configurable overhead allowing sampling rates from real-time to periodic (5-30 seconds). Implemented via observable instruments (polled, zero hot-path overhead).
4. ✅ The system must distinguish between eviction reasons including memory pressure, expiration, and manual removal. Implemented: EvictionReason.Removed and EvictionReason.Replaced are excluded from eviction counts.
5. The system must prevent duplicate cache registration by maintaining weak references to registered cache instances. — Not approved. Part of the rejected IMemoryCacheMetrics registry pattern.
6. The system must handle naming conflicts by either throwing exceptions for duplicates or using automatic resolution strategies. — Not approved. Part of the rejected IMemoryCacheMetrics registry pattern.
7. ✅ The system must integrate with OpenTelemetry/IMeterFactory to enable export to external monitoring systems. Implemented with 4 observable instruments: cache.requests, cache.evictions, cache.entries, cache.estimated_size.
8. ✅ The system must provide extension methods for easy service registration in ASP.NET Core applications. Implemented: AddNamedMeteredMemoryCache and DecorateMemoryCacheWithMetrics.
9. The system must implement circuit breaker functionality to reduce metrics collection if overhead exceeds configurable thresholds. — Not approved. Observable instruments are polled (not pushed), so hot-path overhead is already near-zero; circuit breakers are unnecessary with this architecture.
10. ✅ The system must support opt-in statistics tracking. Automatic discovery of DI-registered caches is not approved (part of the rejected registry pattern). Opt-in tracking implemented via MeteredMemoryCacheOptions and DI extension methods.
11. ✅ The system must provide comprehensive metrics including hit/miss ratios, cache size, item lifecycle data, and operation latency. Implemented: hits, misses, evictions, entry count, estimated size, and calculated hit ratio via CacheStatistics.
12. The system must use weak references to prevent memory leaks when clients forget to unregister caches. — Not approved. Part of the rejected IMemoryCacheMetrics registry pattern.

Design Considerations

• ✅ API Surface: Custom CacheStatistics class with TotalEvictions (polyfills the approved BCL MemoryCacheStatistics.TotalEvictions property)
• Registration Pattern: Use explicit registration for component-specific caches with potential future automatic discovery — Rejected by .NET API review
• ✅ Configuration Tiers: Provide no-config defaults, simple predefined profiles, and advanced fine-grained control
• Memory Safety: Implement weak reference patterns to prevent memory leaks from unregistered caches — Part of rejected registry pattern
• ✅ Performance: Design for minimal overhead with observable instruments (zero hot-path allocation)

Technical Considerations

• ✅ Integration with existing DI container: Leverage IMeterFactory for OpenTelemetry compatibility
• ✅ Thread safety: Ensure metrics collection is thread-safe for high-concurrency scenarios (implemented via Interlocked atomics)
• Weak reference management: Implement proper cleanup of disposed cache references — Part of rejected registry pattern
• Sampling strategies: Support configurable sampling rates to balance accuracy with performance — Not approved; unnecessary with observable instruments
• ✅ Export mechanisms: Design pluggable exporters for different monitoring backends (implemented via standard OpenTelemetry pipeline)

Success Metrics

1. ✅ Performance overhead: Maintain <100ns per cache operation when metrics are enabled — Validated via BenchmarkDotNet suites (CacheBenchmarks, MetricsOverheadBenchmarks, ContentionBenchmarks)
2. ✅ Adoption rate: Achieve integration in existing applications without requiring code changes (for basic scenarios)
3. ✅ Diagnostic value: Enable identification of cache thrashing patterns that were previously invisible
4. Container efficiency: Reduce memory-related performance issues in containerized deployments by 20% — Not yet measured
5. ✅ Monitoring integration: Support export to at least 3 major monitoring platforms (Prometheus, Application Insights, Data Dog) — Supported via standard OpenTelemetry exporter pipeline

Open Questions

1. Automatic cache sizing documentation: (future enhancement) Provide recommendations for cache configuration based on container memory constraints
2. Metric retention: How long should in-memory metrics be retained before aggregation/export, and should this be configurable? — Resolved: metrics use observable instruments polled by the OTel SDK; retention is controlled by the configured exporter, not by this library.
3. Performance testing scope: What specific performance benchmarks should be established to validate the <100ns overhead target across different cache usage patterns? — Resolved: three benchmark suites implemented — CacheBenchmarks (operation overhead), MetricsOverheadBenchmarks (instrumentation cost), ContentionBenchmarks (concurrent contention).
4. Migration documentation: What level of detail is needed in migration guides for applications migrating from this polyfill to native .NET 11 MemoryCache metrics?

Parent Tasks for Memory Cache Metrics API with Eviction Tracking

1. ✅ Extend MemoryCacheStatistics with Eviction Tracking

• Enhance Microsoft's MemoryCacheStatistics to include TotalEvictedEntries property while maintaining backward compatibility. Implemented via custom CacheStatistics class in MeteredMemoryCache.

Sub-tasks:

• Create CacheStatistics class with TotalEvictions property (polyfills BCL MemoryCacheStatistics.TotalEvictions)
• Implement backward-compatible statistics via MeteredMemoryCache.GetCurrentStatistics()
• Add thread-safe eviction counting mechanism (via Interlocked atomics)
• Create mapping between PostEvictionReason and eviction categories (excludes Removed/Replaced)
• Add validation and error handling for statistics collection
• Write comprehensive unit tests for statistics extensions
• Add integration tests with existing cache implementations
• Create performance benchmarks to validate <100ns overhead target
• Update API documentation and usage examples

2. Create MemoryCacheMetrics Service Infrastructure

• Develop a centralized service for registering and tracking multiple named caches with weak reference management and conflict resolution — Not approved by .NET API review. The registry pattern (IMemoryCacheMetrics) was rejected as "non-intuitive." The approved approach uses native IMeterFactory on MemoryCache directly.

Sub-tasks:

• Design IMemoryCacheMetrics interface with registration and tracking methods
• Implement MemoryCacheMetrics service with weak reference management
• Create cache registration system with naming conflict resolution
• Implement automatic cleanup of disposed cache references
• Add thread-safe concurrent access patterns for multi-cache scenarios
• Create cache discovery mechanism for DI-registered caches
• Implement metrics aggregation across multiple named caches
• Add cache lifecycle management (registration, tracking, cleanup)
• Write comprehensive unit tests for service functionality
• Create integration tests for multi-cache scenarios
• Add service registration extensions for dependency injection
• Document service usage patterns and best practices

3. Implement Circuit Breaker and Sampling Mechanisms

• ~~Add configurable overhead protection with circuit breaker functionality and sampling rates to maintain the ~100ns performance target~~ — Not approved. Observable instruments are polled (not pushed), so hot-path overhead is already near-zero. Circuit breakers and sampling are unnecessary with this architecture.

Sub-tasks:

• Design circuit breaker threshold configuration
• Implement sampling rate controls
• Add overhead monitoring and adaptive throttling
• Write tests for circuit breaker behavior
• Document sampling configuration options

4. Add Advanced Cache Management Features

• Implement component-specific cache registration, automatic discovery of DI-registered caches, and enhanced export mechanisms — Not approved. Component-specific registration and automatic discovery are part of the rejected IMemoryCacheMetrics registry pattern.

Sub-tasks:

• Implement component-specific cache registration
• Add automatic discovery of DI-registered caches
• Create enhanced export mechanisms for cache metrics
• Write integration tests for advanced scenarios
• Document advanced cache management patterns

5. Integrate OpenTelemetry and External Monitoring

• Enhance existing OpenTelemetry integration with support for multiple monitoring backends (Prometheus, Application Insights) and comprehensive metrics export

Sub-tasks:

• Enhance existing OpenTelemetry integration with new metrics
• Create Prometheus metrics exporter with proper label handling
• Implement Application Insights integration with custom metrics
• Add support for Grafana dashboard configuration
• Create pluggable exporter architecture for extensibility (via standard OTel pipeline)
• Create configuration system for multiple export destinations
• Write integration tests for all supported monitoring backends
• Create example configurations for popular monitoring setups
• Document monitoring setup and troubleshooting guides

[traycerai]

Plan

Observations

The core MeteredMemoryCache implementation is complete and solid — four observable instruments (cache.requests, cache.evictions, cache.entries, cache.estimated_size), thread-safe atomics, IMeterFactory integration, and DI extensions (AddNamedMeteredMemoryCache, DecorateMemoryCacheWithMetrics) are all in place. docs/OpenTelemetryIntegration.md already documents Prometheus, OTLP, Azure Monitor, DataDog, and GCP at a prose level. The examples/AspNetCore project already wires up AddPrometheusExporter(). The remaining open sub-tasks in Task 5 are: a Prometheus example project, Application Insights integration, Grafana dashboard config, a multi-exporter configuration helper, integration tests for monitoring backends, monitoring/troubleshooting docs, and the .NET 11 migration guide (Open Question 4).

Approach

Focus exclusively on the unchecked Task 5 sub-tasks and Open Question 4. The standard OTel pipeline already provides the pluggable exporter architecture, so no new abstractions are needed — the work is example projects, a Grafana dashboard JSON, a thin multi-exporter configuration helper in ServiceCollectionExtensions, integration tests using the existing OpenTelemetry.Exporter.InMemory pattern, and two new doc files. All new code follows the existing patterns (xunit, HostApplicationBuilder, OpenTelemetry.Extensions.Hosting, Directory.Packages.props for package versions).

---

Implementation Steps

1. Prometheus Example Project

Create examples/Prometheus/ as a minimal console/worker app that demonstrates end-to-end Prometheus scraping.

• Add examples/Prometheus/Prometheus.csproj referencing OpenTelemetry.Extensions.Hosting, OpenTelemetry.Exporter.Prometheus.AspNetCore, Microsoft.Extensions.Hosting, and CacheImplementations.
• In examples/Prometheus/Program.cs:
  • Register AddNamedMeteredMemoryCache with cache.name = "prometheus-demo" and additional tags environment = "demo".
  • Wire AddOpenTelemetry().WithMetrics(m => m.AddMeter(MeteredMemoryCache.MeterName).AddPrometheusExporter()).
  • Call app.UseOpenTelemetryPrometheusScrapingEndpoint() (or app.MapPrometheusScrapingEndpoint() for minimal API).
  • Add a background loop that performs cache hits/misses to generate live metric data.
• Add examples/Prometheus/README.md explaining how to run and verify output at /metrics.

2. Application Insights Example Project

Create examples/ApplicationInsights/ demonstrating Azure Monitor export via the standard OTel pipeline.

• Add examples/ApplicationInsights/ApplicationInsights.csproj referencing Azure.Monitor.OpenTelemetry.AspNetCore (check Directory.Packages.props — add a <PackageVersion> entry for it) and CacheImplementations.
• In examples/ApplicationInsights/Program.cs:
  • Register AddNamedMeteredMemoryCache("ai-demo").
  • Wire AddOpenTelemetry().WithMetrics(m => m.AddMeter(MeteredMemoryCache.MeterName)).UseAzureMonitor().
  • Read the connection string from IConfiguration (APPLICATIONINSIGHTS_CONNECTION_STRING).
• Add examples/ApplicationInsights/README.md with setup instructions (connection string, managed identity note).

3. Grafana Dashboard Configuration

Create docs/grafana/ with a ready-to-import Grafana dashboard JSON.

• Create docs/grafana/cache-metrics-dashboard.json — a Grafana dashboard JSON containing panels for:
  • Cache Hit Rate — PromQL: sum(rate(cache_requests_total{cache_request_type="hit"}[5m])) by (cache_name) / sum(rate(cache_requests_total[5m])) by (cache_name)
  • Cache Operations/sec — sum(rate(cache_requests_total[5m])) by (cache_name, cache_request_type)
  • Eviction Rate — sum(rate(cache_evictions_total[5m])) by (cache_name)
  • Current Entry Count — cache_entries gauge
  • Estimated Size — cache_estimated_size_bytes gauge
  • Miss Rate Alert threshold line at 50%
• Create docs/grafana/README.md explaining how to import the dashboard and configure the Prometheus data source.

4. Multi-Exporter Configuration Helper

Add a AddMeteredMemoryCacheOpenTelemetry extension method in file:src/CacheImplementations/ServiceCollectionExtensions.cs (or a new OpenTelemetryExtensions.cs in the same project) that encapsulates the common OTel setup pattern:

• The method signature: AddMeteredMemoryCacheOpenTelemetry(this IServiceCollection services, Action<MeterProviderBuilder> configureMetrics).
• Internally calls services.AddOpenTelemetry().WithMetrics(m => { m.AddMeter(MeteredMemoryCache.MeterName); configureMetrics(m); }).
• This removes the need for callers to know MeteredMemoryCache.MeterName and ensures the meter is always registered.
• No new package dependencies — OpenTelemetry.Extensions.Hosting is already in Directory.Packages.props.
• Add XML doc comments following the existing style in ServiceCollectionExtensions.

5. Integration Tests for Monitoring Backends

Add tests to file:tests/Integration/OpenTelemetryIntegrationTests.cs (or a new MonitoringBackendIntegrationTests.cs in tests/Integration/) covering:

• Prometheus label format: Verify that metric names emitted by MeteredMemoryCache conform to Prometheus naming conventions (dots replaced with underscores, _total suffix on counters). Use the existing InMemoryExporter pattern — no live Prometheus server needed; assert on Metric.Name and tag key/value shapes.
• Multi-exporter pipeline: Verify that two InMemoryExporter instances both receive the same metric data when chained via AddInMemoryExporter twice (simulates multiple export destinations).
• AddMeteredMemoryCacheOpenTelemetry helper: Verify that calling the new helper correctly registers the MeteredMemoryCache.MeterName meter and that cache operations produce metrics in the exported list.

All tests follow the existing ExecuteWithHostAsync / FlushMetricsAsync / FindMetric helper pattern already established in OpenTelemetryIntegrationTests.

6. Monitoring Setup and Troubleshooting Documentation

Update file:docs/OpenTelemetryIntegration.md:

• Add a "Configuration System for Multiple Export Destinations" section showing the new AddMeteredMemoryCacheOpenTelemetry helper alongside the manual AddOpenTelemetry() approach.
• Add a "Grafana Dashboard" section referencing docs/grafana/cache-metrics-dashboard.json with import instructions.
• Add a "Application Insights" section cross-referencing the new example project.
• Expand the Troubleshooting section with:
  • "Prometheus metrics show _total suffix but dashboard expects no suffix" — explain OTel SDK counter naming.
  • "Azure Monitor metrics delayed" — explain the ~2-5 minute ingestion lag.
  • "Multiple exporters receiving duplicate data" — explain that this is expected behavior.

7. .NET 11 Migration Guide (Open Question 4)

Create docs/DotNet11MigrationGuide.md:

• Overview section: Explain that this library is a polyfill for .NET 8/9/10 targeting the approved API surface from dotnet/runtime#124140, and that .NET 11 (GA November 2026) will include native MemoryCache metrics via IMeterFactory.

• API Mapping table:

  This library	.NET 11 native
  MeteredMemoryCache (decorator)	MemoryCache with built-in metrics
  CacheStatistics.TotalEvictions	MemoryCacheStatistics.TotalEvictions
  AddNamedMeteredMemoryCache(name)	AddMemoryCache() + IMeterFactory
  MeteredMemoryCache.MeterName	Same meter name (intentional alignment)

• Migration steps:

  1. Upgrade target framework to net11.0.
  2. Replace AddNamedMeteredMemoryCache(name) with AddMemoryCache() and configure MemoryCacheOptions with TrackStatistics = true.
  3. Replace MeteredMemoryCache.GetCurrentStatistics() calls with MemoryCache.GetCurrentStatistics() — property names are identical.
  4. Remove the CacheImplementations project reference.
  5. Keep the OpenTelemetry pipeline unchanged — meter name and instrument names are identical by design.
  6. Replace DecorateMemoryCacheWithMetrics usages with the native MemoryCache registration (no decorator needed).

• Zero-downtime migration note: Because the meter name (Microsoft.Extensions.Caching.Memory.MemoryCache) and all instrument names (cache.requests, cache.evictions, cache.entries, cache.estimated_size) are intentionally identical, Prometheus/Grafana dashboards and OTel pipelines require no changes when migrating.

• Checklist (markdown task list) mirroring the existing migration checklist style in docs/MigrationGuide.md.

---

Sequence of Changes

sequenceDiagram
    participant Dev as Developer
    participant Src as src/CacheImplementations
    participant Examples as examples/
    participant Docs as docs/
    participant Tests as tests/Integration

    Dev->>Src: Add AddMeteredMemoryCacheOpenTelemetry helper
    Dev->>Examples: Create Prometheus example project
    Dev->>Examples: Create ApplicationInsights example project
    Dev->>Docs: Create docs/grafana/cache-metrics-dashboard.json
    Dev->>Docs: Update OpenTelemetryIntegration.md
    Dev->>Docs: Create DotNet11MigrationGuide.md
    Dev->>Tests: Add MonitoringBackendIntegrationTests
    Tests-->>Src: Validates new helper method
    Tests-->>Examples: Validates metric name/label conventions

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The core `MeteredMemoryCache` implementation is complete and solid — four observable instruments (`cache.requests`, `cache.evictions`, `cache.entries`, `cache.estimated_size`), thread-safe atomics, `IMeterFactory` integration, and DI extensions (`AddNamedMeteredMemoryCache`, `DecorateMemoryCacheWithMetrics`) are all in place. `docs/OpenTelemetryIntegration.md` already documents Prometheus, OTLP, Azure Monitor, DataDog, and GCP at a prose level. The `examples/AspNetCore` project already wires up `AddPrometheusExporter()`. The remaining open sub-tasks in Task 5 are: a Prometheus example project, Application Insights integration, Grafana dashboard config, a multi-exporter configuration helper, integration tests for monitoring backends, monitoring/troubleshooting docs, and the .NET 11 migration guide (Open Question 4).

## Approach

Focus exclusively on the unchecked Task 5 sub-tasks and Open Question 4. The standard OTel pipeline already provides the pluggable exporter architecture, so no new abstractions are needed — the work is example projects, a Grafana dashboard JSON, a thin multi-exporter configuration helper in `ServiceCollectionExtensions`, integration tests using the existing `OpenTelemetry.Exporter.InMemory` pattern, and two new doc files. All new code follows the existing patterns (xunit, `HostApplicationBuilder`, `OpenTelemetry.Extensions.Hosting`, `Directory.Packages.props` for package versions).

---

## Implementation Steps

### 1. Prometheus Example Project

Create `examples/Prometheus/` as a minimal console/worker app that demonstrates end-to-end Prometheus scraping.

- Add `examples/Prometheus/Prometheus.csproj` referencing `OpenTelemetry.Extensions.Hosting`, `OpenTelemetry.Exporter.Prometheus.AspNetCore`, `Microsoft.Extensions.Hosting`, and `CacheImplementations`.
- In `examples/Prometheus/Program.cs`:
  - Register `AddNamedMeteredMemoryCache` with `cache.name` = `"prometheus-demo"` and additional tags `environment` = `"demo"`.
  - Wire `AddOpenTelemetry().WithMetrics(m => m.AddMeter(MeteredMemoryCache.MeterName).AddPrometheusExporter())`.
  - Call `app.UseOpenTelemetryPrometheusScrapingEndpoint()` (or `app.MapPrometheusScrapingEndpoint()` for minimal API).
  - Add a background loop that performs cache hits/misses to generate live metric data.
- Add `examples/Prometheus/README.md` explaining how to run and verify output at `/metrics`.

### 2. Application Insights Example Project

Create `examples/ApplicationInsights/` demonstrating Azure Monitor export via the standard OTel pipeline.

- Add `examples/ApplicationInsights/ApplicationInsights.csproj` referencing `Azure.Monitor.OpenTelemetry.AspNetCore` (check `Directory.Packages.props` — add a `<PackageVersion>` entry for it) and `CacheImplementations`.
- In `examples/ApplicationInsights/Program.cs`:
  - Register `AddNamedMeteredMemoryCache("ai-demo")`.
  - Wire `AddOpenTelemetry().WithMetrics(m => m.AddMeter(MeteredMemoryCache.MeterName)).UseAzureMonitor()`.
  - Read the connection string from `IConfiguration` (`APPLICATIONINSIGHTS_CONNECTION_STRING`).
- Add `examples/ApplicationInsights/README.md` with setup instructions (connection string, managed identity note).

### 3. Grafana Dashboard Configuration

Create `docs/grafana/` with a ready-to-import Grafana dashboard JSON.

- Create `docs/grafana/cache-metrics-dashboard.json` — a Grafana dashboard JSON containing panels for:
  - **Cache Hit Rate** — PromQL: `sum(rate(cache_requests_total{cache_request_type="hit"}[5m])) by (cache_name) / sum(rate(cache_requests_total[5m])) by (cache_name)`
  - **Cache Operations/sec** — `sum(rate(cache_requests_total[5m])) by (cache_name, cache_request_type)`
  - **Eviction Rate** — `sum(rate(cache_evictions_total[5m])) by (cache_name)`
  - **Current Entry Count** — `cache_entries` gauge
  - **Estimated Size** — `cache_estimated_size_bytes` gauge
  - **Miss Rate Alert threshold** line at 50%
- Create `docs/grafana/README.md` explaining how to import the dashboard and configure the Prometheus data source.

### 4. Multi-Exporter Configuration Helper

Add a `AddMeteredMemoryCacheOpenTelemetry` extension method in `file:src/CacheImplementations/ServiceCollectionExtensions.cs` (or a new `OpenTelemetryExtensions.cs` in the same project) that encapsulates the common OTel setup pattern:

- The method signature: `AddMeteredMemoryCacheOpenTelemetry(this IServiceCollection services, Action<MeterProviderBuilder> configureMetrics)`.
- Internally calls `services.AddOpenTelemetry().WithMetrics(m => { m.AddMeter(MeteredMemoryCache.MeterName); configureMetrics(m); })`.
- This removes the need for callers to know `MeteredMemoryCache.MeterName` and ensures the meter is always registered.
- No new package dependencies — `OpenTelemetry.Extensions.Hosting` is already in `Directory.Packages.props`.
- Add XML doc comments following the existing style in `ServiceCollectionExtensions`.

### 5. Integration Tests for Monitoring Backends

Add tests to `file:tests/Integration/OpenTelemetryIntegrationTests.cs` (or a new `MonitoringBackendIntegrationTests.cs` in `tests/Integration/`) covering:

- **Prometheus label format**: Verify that metric names emitted by `MeteredMemoryCache` conform to Prometheus naming conventions (dots replaced with underscores, `_total` suffix on counters). Use the existing `InMemoryExporter` pattern — no live Prometheus server needed; assert on `Metric.Name` and tag key/value shapes.
- **Multi-exporter pipeline**: Verify that two `InMemoryExporter` instances both receive the same metric data when chained via `AddInMemoryExporter` twice (simulates multiple export destinations).
- **`AddMeteredMemoryCacheOpenTelemetry` helper**: Verify that calling the new helper correctly registers the `MeteredMemoryCache.MeterName` meter and that cache operations produce metrics in the exported list.

All tests follow the existing `ExecuteWithHostAsync` / `FlushMetricsAsync` / `FindMetric` helper pattern already established in `OpenTelemetryIntegrationTests`.

### 6. Monitoring Setup and Troubleshooting Documentation

Update `file:docs/OpenTelemetryIntegration.md`:

- Add a **"Configuration System for Multiple Export Destinations"** section showing the new `AddMeteredMemoryCacheOpenTelemetry` helper alongside the manual `AddOpenTelemetry()` approach.
- Add a **"Grafana Dashboard"** section referencing `docs/grafana/cache-metrics-dashboard.json` with import instructions.
- Add a **"Application Insights"** section cross-referencing the new example project.
- Expand the **Troubleshooting** section with:
  - "Prometheus metrics show `_total` suffix but dashboard expects no suffix" — explain OTel SDK counter naming.
  - "Azure Monitor metrics delayed" — explain the ~2-5 minute ingestion lag.
  - "Multiple exporters receiving duplicate data" — explain that this is expected behavior.

### 7. .NET 11 Migration Guide (Open Question 4)

Create `docs/DotNet11MigrationGuide.md`:

- **Overview section**: Explain that this library is a polyfill for .NET 8/9/10 targeting the approved API surface from [dotnet/runtime#124140](https://github.com/dotnet/runtime/issues/124140), and that .NET 11 (GA November 2026) will include native `MemoryCache` metrics via `IMeterFactory`.
- **API Mapping table**:

  | This library | .NET 11 native |
  |---|---|
  | `MeteredMemoryCache` (decorator) | `MemoryCache` with built-in metrics |
  | `CacheStatistics.TotalEvictions` | `MemoryCacheStatistics.TotalEvictions` |
  | `AddNamedMeteredMemoryCache(name)` | `AddMemoryCache()` + `IMeterFactory` |
  | `MeteredMemoryCache.MeterName` | Same meter name (intentional alignment) |

- **Migration steps**:
  1. Upgrade target framework to `net11.0`.
  2. Replace `AddNamedMeteredMemoryCache(name)` with `AddMemoryCache()` and configure `MemoryCacheOptions` with `TrackStatistics = true`.
  3. Replace `MeteredMemoryCache.GetCurrentStatistics()` calls with `MemoryCache.GetCurrentStatistics()` — property names are identical.
  4. Remove the `CacheImplementations` project reference.
  5. Keep the OpenTelemetry pipeline unchanged — meter name and instrument names are identical by design.
  6. Replace `DecorateMemoryCacheWithMetrics` usages with the native `MemoryCache` registration (no decorator needed).
- **Zero-downtime migration note**: Because the meter name (`Microsoft.Extensions.Caching.Memory.MemoryCache`) and all instrument names (`cache.requests`, `cache.evictions`, `cache.entries`, `cache.estimated_size`) are intentionally identical, Prometheus/Grafana dashboards and OTel pipelines require **no changes** when migrating.
- **Checklist** (markdown task list) mirroring the existing migration checklist style in `docs/MigrationGuide.md`.

---

## Sequence of Changes

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Src as src/CacheImplementations
    participant Examples as examples/
    participant Docs as docs/
    participant Tests as tests/Integration

    Dev->>Src: Add AddMeteredMemoryCacheOpenTelemetry helper
    Dev->>Examples: Create Prometheus example project
    Dev->>Examples: Create ApplicationInsights example project
    Dev->>Docs: Create docs/grafana/cache-metrics-dashboard.json
    Dev->>Docs: Update OpenTelemetryIntegration.md
    Dev->>Docs: Create DotNet11MigrationGuide.md
    Dev->>Tests: Add MonitoringBackendIntegrationTests
    Tests-->>Src: Validates new helper method
    Tests-->>Examples: Validates metric name/label conventions
```

---

Execution Information

Branch: main
Commit: e2b28e6

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.