Skip to content

πŸ“Š ObservabilityΒΆ

CoreSystem.Cache includes observability support based on OpenTelemetry Metrics.

The cache registers its own observability contributor and exposes cache hit and miss metrics through the cache pipeline.


❓ Why Observability MattersΒΆ

Cache metrics help monitor whether cache reads are finding the requested entries.

The current implementation provides metrics for:

  • Cache hits.
  • Cache misses.

These metrics are generated by MetricsBehavior from cache contexts that implement ICacheMetricContext.


πŸ—οΈ ArchitectureΒΆ

flowchart LR Application --> Cache --> CachePipeline --> MetricsBehavior --> CacheMetrics --> OpenTelemetry

CacheMetrics creates the cache meter and the counters used by the framework.


πŸ“Š Built-in MetricsΒΆ

The current implementation publishes:

Metric Description
cache.distributed.hits Successful cache reads
cache.distributed.misses Cache reads that did not find the requested item

The current implementation does not publish operations, duration, or hit_rate metrics.


πŸŽ›οΈ MeterΒΆ

The cache meter name is:

Core.Cache

The meter is created by CacheMetrics and registered with OpenTelemetry through CacheObservabilityContributor.

services.AddOpenTelemetry()
    .WithMetrics(builder =>
    {
        builder.AddMeter("Core.Cache");
    });

AddCoreCache() registers the cache diagnostics services and the observability contributor.


⏱️ When Metrics Are Recorded¢

GetCacheContext<T> and GetOrAddCacheContext<T> implement ICacheMetricContext.

A successful result is recorded as a hit:

Result != null
    ↓
Hit

A missing result is recorded as a miss:

Result == null
    ↓
Miss

MetricsBehavior records the corresponding counter after the cache operation completes successfully.


πŸ”Œ Observability IntegrationΒΆ

CacheObservabilityContributor implements IObservabilityContributor. It is an internal type, so this is a description of what the framework does rather than an extension point you can implement.

It exposes the cache meter:

internal sealed class CacheObservabilityContributor : IObservabilityContributor
{
    public IEnumerable<string> GetActivitySources()
        => ["Core.Cache"];
}

and configures OpenTelemetry metrics for the meter.

The exporter and monitoring backend are handled by the application's observability infrastructure.


πŸ”§ Extending ObservabilityΒΆ

The cache metrics are implemented as a pipeline behavior rather than directly inside each storage provider.

This keeps metric collection independent from Memory or external cache implementations.

Additional telemetry can be added through the application's observability infrastructure or through future cache pipeline capabilities.


βœ… Best PracticesΒΆ

βœ… Monitor cache hits and misses.

βœ… Use the Core.Cache meter when configuring OpenTelemetry.

βœ… Combine cache metrics with Health Checks when using an external provider.

βœ… Configure the exporter and monitoring backend through the application's observability infrastructure.

The current cache implementation intentionally exposes a small metric surface: hits and misses. Additional metrics such as operation duration or hit rate should only be documented once they are implemented.