Metrics Plugin

Prometheus-compatible metrics for monitoring Redis operations, cache performance, and plugin health.

Overview

The Metrics Plugin provides observability into your Redis operations with Prometheus-format metrics.

Question	Without Metrics	With Metrics Plugin
Is Redis slow?	Unknown	p99 latency visible
Cache hit rate?	Unknown	Hit rate visible
Lock contention?	Guesswork	Metrics available
Error rate?	Check logs	Error counters

Key Features

• Prometheus Format — Standard metrics format compatible with Prometheus-based systems
• Automatic Instrumentation — Plugins emit metrics when enabled
• Built-in Endpoint — HTTP endpoint for Prometheus scraping
• Custom Metrics — API for adding application-specific metrics
• Grafana Dashboards — Example dashboards for visualizations
• Alert Templates — Example AlertManager configurations

Installation

ioredis

npm install @nestjs-redisx/core @nestjs-redisx/metrics ioredis

node-redis

npm install @nestjs-redisx/core @nestjs-redisx/metrics redis

Basic Configuration

import { Module } from '@nestjs/common';
import { RedisModule } from '@nestjs-redisx/core';
import { MetricsPlugin } from '@nestjs-redisx/metrics';

@Module({
  imports: [
    RedisModule.forRoot({
      clients: {
        host: 'localhost',
        port: 6379,
      },
      plugins: [
        new MetricsPlugin({
          prefix: 'redisx_',
          endpoint: '/metrics',
          defaultLabels: {
            service: 'my-service',
          },
        }),
      ],
    }),
  ],
})
export class AppModule {}

Viewing Metrics

curl http://localhost:3000/metrics

# HELP redisx_cache_hits_total Total cache hits
# TYPE redisx_cache_hits_total counter
redisx_cache_hits_total{layer="l1"} 15234

# HELP redisx_cache_misses_total Total cache misses
# TYPE redisx_cache_misses_total counter
redisx_cache_misses_total{layer="l1"} 892

# HELP redisx_command_duration_seconds Redis command latency in seconds
# TYPE redisx_command_duration_seconds histogram
redisx_command_duration_seconds_bucket{command="GET",client="default",le="0.001"} 1523
redisx_command_duration_seconds_bucket{command="GET",client="default",le="0.005"} 2891

Available Metrics

Command Metrics

Metric	Type	Labels	Description
commands_total	Counter	command, client, status	Total Redis commands
command_duration_seconds	Histogram	command, client	Command latency
connections_active	Gauge	client	Active connections
errors_total	Counter	client, error_type	Total errors

Cache Metrics

Metric	Type	Labels	Description
cache_hits_total	Counter	layer	Cache hits
cache_misses_total	Counter	layer	Cache misses
cache_hit_ratio	Gauge	layer	Hit ratio (0-1)
cache_size	Gauge	layer	Current cache size
cache_stampede_prevented_total	Counter	—	Stampede preventions

Lock Metrics

Metric	Type	Labels	Description
lock_acquisitions_total	Counter	status	Lock attempts
lock_wait_duration_seconds	Histogram	—	Wait time
lock_hold_duration_seconds	Histogram	—	Hold time
locks_active	Gauge	—	Active lock count

Rate Limit Metrics

Metric	Type	Labels	Description
ratelimit_requests_total	Counter	status	Rate limit requests

Stream Metrics

Metric	Type	Labels	Description
stream_messages_published_total	Counter	stream	Messages published
stream_messages_consumed_total	Counter	stream, group, status	Messages consumed
stream_publish_duration_seconds	Histogram	stream	Publish latency
stream_publish_errors_total	Counter	stream	Publish errors
stream_processing_duration_seconds	Histogram	stream, group	Processing duration

Idempotency Metrics

Metric	Type	Labels	Description
idempotency_requests_total	Counter	status	Idempotency requests
session_created_total	Counter	-	Sessions created
session_destroyed_total	Counter	reason	Sessions removed (destroyed/revoked/expired-by-cap)
session_limit_rejections_total	Counter	-	Logins refused by the seat limit
idempotency_duration_seconds	Histogram	—	Check duration

Architecture

Documentation

Topic	Description
Core Concepts	Understanding metrics collection
Configuration	Configuration reference
Prometheus	Prometheus integration
Grafana Dashboards	Example visualizations
Plugin Metrics	Metrics from each plugin
Custom Metrics	Adding application metrics
Alerting	AlertManager configuration
Troubleshooting	Debugging common issues