OpenTelemetry

OpenTelemetry

CacheWeave emits OpenTelemetry metrics and distributed traces when EnableMetrics = true (the default). No hard dependency on the OTel SDK is taken in CacheWeave.Core — instrumentation is wired via reflection so the package remains lightweight.

Enabling Metrics

builder.Services.AddCacheWeave(options =>
{
    options.EnableMetrics = true; // default
});

Wiring into the OTel Pipeline

using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddCacheWeaveMeter()          // CacheWeave metrics
        .AddPrometheusExporter())
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddCacheWeaveInstrumentation() // CacheWeave Activity spans
        .AddOtlpExporter());

Both extension methods are provided by CacheWeave.Core.Extensions.OpenTelemetryExtensions.

Metrics Reference

All metrics are emitted under the meter name "CacheWeave".

Metric Name	Type	Unit	Description
cacheweave.hits	Counter	{requests}	Cache hits
cacheweave.misses	Counter	{requests}	Cache misses
cacheweave.sets	Counter	{requests}	Cache writes
cacheweave.evictions	Counter	{requests}	Cache evictions (key or prefix)
cacheweave.duration	Histogram	ms	End-to-end filter duration (hit or miss + fetch)

Tags

Each metric includes the following tags:

Tag	Values	Description
cache.key	string	The resolved cache key
cache.provider	redis, inmemory, sqlite, etc.	The active provider

Activity Spans

CacheWeave starts an Activity span for each cache operation using ActivitySource named "CacheWeave".

Span Name	Description
cache.get	Cache lookup (hit or miss)
cache.set	Cache write
cache.evict	Cache eviction

Span attributes mirror the metric tags (cache.key, cache.provider).

Prometheus + Grafana

Prometheus scrape config

scrape_configs:
  - job_name: my-api
    static_configs:
      - targets: ['localhost:5000']
    metrics_path: /metrics

Grafana dashboard queries

Hit rate (%):

rate(cacheweave_hits_total[5m])
  / (rate(cacheweave_hits_total[5m]) + rate(cacheweave_misses_total[5m]))
  * 100

Cache sets per second:

rate(cacheweave_sets_total[1m])

P99 cache duration (ms):

histogram_quantile(0.99, rate(cacheweave_duration_milliseconds_bucket[5m]))

Evictions per minute:

rate(cacheweave_evictions_total[1m]) * 60

Disabling Metrics

Set EnableMetrics = false to skip all Stopwatch allocations and meter calls — zero overhead when OTel is not configured:

builder.Services.AddCacheWeave(options =>
{
    options.EnableMetrics = false;
});

Diagnostic Logging

CacheWeave logs internal activity (key resolution, hit/miss, write, eviction) at the level configured by DiagnosticLogLevel:

builder.Services.AddCacheWeave(options =>
{
    options.DiagnosticLogLevel = LogLevel.Information; // default: Debug
});

Log categories:

Category	Events
CacheWeave.Core.Filters.CacheWeaveFilter	Hit, miss, write, key resolved
CacheWeave.Core.Filters.CacheWeaveEvictFilter	Eviction executed, missing key/prefix warning

To surface CacheWeave logs in production without changing the global log level:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "CacheWeave": "Information"
    }
  }
}