📊 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¶

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

Built-in Metrics¶

The current implementation publishes:

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 the CoreSystem observability contract:

IObservabilityContributor

It exposes the cache meter:

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.