Observability

Monitor your client's activity for optimization and debugging.

node-redis has built-in support for OpenTelemetry (OTel) instrumentation to collect metrics. This can be very helpful for diagnosing problems and improving the performance and connection resiliency of your application. See the Observability overview for an introduction to Redis client observability and a reference guide for the available metrics.

This page explains how to enable and use OTel instrumentation in node-redis using an example configuration for a local Grafana instance. See our observability demonstration repository on GitHub to learn how to set up a suitable Grafana dashboard.

Installation

Install the OTel dependencies with the following commands:

npm install @opentelemetry/api
npm install @opentelemetry/sdk-metrics

Import

Start by importing the required OTel and Redis modules:

Foundational: Import required libraries for Redis observability, OpenTelemetry metrics, and Redis operations
import { createClient, OpenTelemetry } from 'redis';
import { metrics } from '@opentelemetry/api';
import {
  ConsoleMetricExporter,
  MeterProvider,
  PeriodicExportingMetricReader
} from '@opentelemetry/sdk-metrics';

const reader = new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
});

const meterProvider = new MeterProvider({
    readers: [reader]
});

metrics.setGlobalMeterProvider(meterProvider);

OpenTelemetry.init({
    metrics: {
        enabled: true,
        enabledMetricGroups: ["command", "pubsub", "streaming", "resiliency"],
        includeCommands: ["GET", "HSET", "XREADGROUP", "PUBLISH"],
        excludeCommands: ["SET"],
        hidePubSubChannelNames: true,
        hideStreamNames: false,
        bucketsOperationDuration: [0.001, 0.01, 0.1, 1],
        bucketsStreamProcessingDuration: [0.01, 0.1, 1, 5],
    },
});

const client = createClient();

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');
console.log(value); // >>> value

await meterProvider.forceFlush();
await meterProvider.shutdown();
await client.destroy();
Node.js Quick-Start

Configure the meter provider

Otel uses a Meter provider to create the objects that collect the metric information. The example below configures a meter provider to export metrics to a local Grafana instance every 10 seconds, but see the OpenTelemetry Node.js docs to learn more about other export options.

Foundational: Configure a meter provider to export metrics to a local Grafana instance every 10 seconds
import { createClient, OpenTelemetry } from 'redis';
import { metrics } from '@opentelemetry/api';
import {
  ConsoleMetricExporter,
  MeterProvider,
  PeriodicExportingMetricReader
} from '@opentelemetry/sdk-metrics';

const reader = new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
});

const meterProvider = new MeterProvider({
    readers: [reader]
});

metrics.setGlobalMeterProvider(meterProvider);

OpenTelemetry.init({
    metrics: {
        enabled: true,
        enabledMetricGroups: ["command", "pubsub", "streaming", "resiliency"],
        includeCommands: ["GET", "HSET", "XREADGROUP", "PUBLISH"],
        excludeCommands: ["SET"],
        hidePubSubChannelNames: true,
        hideStreamNames: false,
        bucketsOperationDuration: [0.001, 0.01, 0.1, 1],
        bucketsStreamProcessingDuration: [0.01, 0.1, 1, 5],
    },
});

const client = createClient();

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');
console.log(value); // >>> value

await meterProvider.forceFlush();
await meterProvider.shutdown();
await client.destroy();
Node.js Quick-Start

Configure the Redis client

You configure the client library for OTel only once per application. This will enable OTel for all Redis connections you create. The example below shows the options you can pass to the observability instance via the MetricConfig object during initialization.

Foundational: Configure Redis observability with a list of metric groups and optional command filtering and privacy controls
import { createClient, OpenTelemetry } from 'redis';
import { metrics } from '@opentelemetry/api';
import {
  ConsoleMetricExporter,
  MeterProvider,
  PeriodicExportingMetricReader
} from '@opentelemetry/sdk-metrics';

const reader = new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
});

const meterProvider = new MeterProvider({
    readers: [reader]
});

metrics.setGlobalMeterProvider(meterProvider);

OpenTelemetry.init({
    metrics: {
        enabled: true,
        enabledMetricGroups: ["command", "pubsub", "streaming", "resiliency"],
        includeCommands: ["GET", "HSET", "XREADGROUP", "PUBLISH"],
        excludeCommands: ["SET"],
        hidePubSubChannelNames: true,
        hideStreamNames: false,
        bucketsOperationDuration: [0.001, 0.01, 0.1, 1],
        bucketsStreamProcessingDuration: [0.01, 0.1, 1, 5],
    },
});

const client = createClient();

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');
console.log(value); // >>> value

await meterProvider.forceFlush();
await meterProvider.shutdown();
await client.destroy();
Node.js Quick-Start

The available options for MetricConfig are described in the table below:

Property Default Description
enabled false Set this to true explicitly to enable metrics.
meterProvider Uses this provider instead of the global provider from @opentelemetry/api.
includeCommands [] List of Redis commands to track. If set, only these commands will be tracked. Note that you should use the Redis command name rather than the node-redis method name where the two differ.
excludeCommands [] List of Redis commands to exclude from tracking. If set, all commands except these will be tracked. Note that you should use the Redis command name rather than the node-redis method name where the two differ.
enabledMetricGroups ['connection-basic', 'resiliency'] List of metric groups to enable. By default, only connection-basic and resiliency are enabled. See Redis metric groups for a list of available groups.
hidePubSubChannelNames false If true, channel names in pub/sub metrics will be hidden.
hideStreamNames false If true, stream names in streaming metrics will be hidden.
bucketsOperationDuration [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10] List of bucket boundaries for the operation.duration histogram (see Custom histogram buckets below).
bucketsConnectionCreateTime [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10] List of bucket boundaries for the connection.create_time histogram (see Custom histogram buckets below).
bucketsConnectionWaitTime [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10] List of bucket boundaries for the connection.wait_time histogram (see Custom histogram buckets below).
bucketsStreamProcessingDuration [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10] List of bucket boundaries for the stream.lag histogram (see Custom histogram buckets below).

Custom histogram buckets

For the histogram metrics, a reasonable default set of buckets is defined, but you can customize the bucket boundaries to suit your needs (the buckets are the ranges of data values counted for each bar of the histogram). Pass an increasing list of float values to the bucketsXxx options when you create the MetricConfig object. The first and last values in the list are the lower and upper bounds of the histogram, respectively, and the values in between define the bucket boundaries.

Use Redis

Once you have configured the client, all Redis connections you create will be automatically instrumented and the collected metrics will be exported to your configured destination.

The example below shows the simplest Redis connection and a few commands, but see the observability demonstration repository for an example that calls a variety of commands in a more realistic way.

Foundational: Use Redis with automatic instrumentation
import { createClient, OpenTelemetry } from 'redis';
import { metrics } from '@opentelemetry/api';
import {
  ConsoleMetricExporter,
  MeterProvider,
  PeriodicExportingMetricReader
} from '@opentelemetry/sdk-metrics';

const reader = new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
});

const meterProvider = new MeterProvider({
    readers: [reader]
});

metrics.setGlobalMeterProvider(meterProvider);

OpenTelemetry.init({
    metrics: {
        enabled: true,
        enabledMetricGroups: ["command", "pubsub", "streaming", "resiliency"],
        includeCommands: ["GET", "HSET", "XREADGROUP", "PUBLISH"],
        excludeCommands: ["SET"],
        hidePubSubChannelNames: true,
        hideStreamNames: false,
        bucketsOperationDuration: [0.001, 0.01, 0.1, 1],
        bucketsStreamProcessingDuration: [0.01, 0.1, 1, 5],
    },
});

const client = createClient();

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');
console.log(value); // >>> value

await meterProvider.forceFlush();
await meterProvider.shutdown();
await client.destroy();
Node.js Quick-Start

Shutdown

When your application exits, you should call the shutdown() method to ensure that all pending metrics are exported.

Foundational: Shutdown Redis observability
import { createClient, OpenTelemetry } from 'redis';
import { metrics } from '@opentelemetry/api';
import {
  ConsoleMetricExporter,
  MeterProvider,
  PeriodicExportingMetricReader
} from '@opentelemetry/sdk-metrics';

const reader = new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
});

const meterProvider = new MeterProvider({
    readers: [reader]
});

metrics.setGlobalMeterProvider(meterProvider);

OpenTelemetry.init({
    metrics: {
        enabled: true,
        enabledMetricGroups: ["command", "pubsub", "streaming", "resiliency"],
        includeCommands: ["GET", "HSET", "XREADGROUP", "PUBLISH"],
        excludeCommands: ["SET"],
        hidePubSubChannelNames: true,
        hideStreamNames: false,
        bucketsOperationDuration: [0.001, 0.01, 0.1, 1],
        bucketsStreamProcessingDuration: [0.01, 0.1, 1, 5],
    },
});

const client = createClient();

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');
console.log(value); // >>> value

await meterProvider.forceFlush();
await meterProvider.shutdown();
await client.destroy();
Node.js Quick-Start
RATE THIS PAGE
Back to top ↑