Pignone.OpenTelemetry.DistributedCache 8.0.0

OpenTelemetry.Instrumentation.DistributedCache

NuGet package for OpenTelemetry instrumentation of implementations that use the IDistributedCache interface (for example, MemoryDistributedCache, Redis). The package decorates IDistributedCache to create spans enriched with tags and to expose metrics related to cache operations.

Index

• Overview
• Prerequisites
• Installation
• Quick start
• Advanced example — configuration and enrichment
• Best practices and recommendations
• Troubleshooting
• References
• License
• Contact

Overview

This package provides:

• Automatic instrumentation for IDistributedCache via decorating the service.
• Span generation for cache operations (Get, Set, Refresh, Remove).
• Enrichment of spans with attributes (for example, cache.key, cache.operation, cache.hit).
• Emission of metrics (counters and histogram/latency) per operation.

Compatible with .NET 8 and C# 12.

Prerequisites

• .NET 8 SDK
• Register an implementation of IDistributedCache in the IServiceCollection before adding the instrumentation (e.g.: AddDistributedMemoryCache(), AddStackExchangeRedisCache()).

Installation

Via CLI:

dotnet add package OpenTelemetry.Instrumentation.DistributedCache

Or via PackageReference (e.g. csproj):

<PackageReference Include="OpenTelemetry.Instrumentation.DistributedCache" Version="*" />

Quick start

Minimal example using MemoryDistributedCache and OpenTelemetry (Traces + Metrics):

Program.cs (minimal API example)

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDistributedMemoryCache();

services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("Serviço");
        tracing.AddDistributedCacheInstrumentation();
        tracing.AddConsoleExporter();
    })
    .WithMetrics(metrics =>
    {
        metrics.AddDistributedCacheInstrumentation();
        metrics.AddConsoleExporter();
    });

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

With this code:

• The tracing provider will add instrumentation for IDistributedCache.
• Spans will be created when calling GetAsync, SetAsync, RemoveAsync, etc.
• Metrics will be exposed via Meter with a name consistent with the instrumentation.

Advanced example — configuration and enrichment

Example of InstrumentationSettings (C# pseudocode showing common options):

...
services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("Serviço");
        tracing.AddDistributedCacheInstrumentation( option =>
        {
            option.Enrich = (activity, sp) =>
            {
                activity.SetTag("custom.tag", "custom");
            };
        });
        tracing.AddConsoleExporter();
    });
    ...
});

Best practices and recommendations

• Register IDistributedCache before calling AddDistributedCacheInstrumentation. Otherwise, the method will throw InvalidOperationException.
• Avoid adding sensitive keys as span attributes in production. Use MaskCacheKeys or sanitize first.
• Keep tag cardinality low (do not use user/key unique values in tags).
• Adjust trace/exporter sampling according to the cache operation volume.
• For Redis, it's recommended to add redis.index / net.peer.name attributes for better context.

Troubleshooting

• Error: "The IDistributedCache service is not registered."

  • Cause: you did not register an implementation of IDistributedCache.
  • Solution: call services.AddDistributedMemoryCache() or services.AddStackExchangeRedisCache() before adding the instrumentation.

• No spans appearing:

  • Check if the TracerProvider is configured correctly and if there's an enabled exporter.
  • Ensure that the instrumentation was added to the TracerProviderBuilder and that the application is using the injected IDistributedCache from DI (not direct instantiations).

• Metrics not visible:

  • Confirm that MeterProvider includes the instrumentation (AddDistributedCacheInstrumentation) and an exporter or scraping endpoint is configured.

References

• OpenTelemetry: https://opentelemetry.io/
• OpenTelemetry semantic conventions for databases/Redis (may be relevant): https://github.com/open-telemetry/semantic-conventions
• IDistributedCache documentation: https://learn.microsoft.com/dotnet/api/microsoft.extensions.caching.distributed.idistributedcache

License

MIT

Contact

For questions and issues, please open an issue in the package repository.