Redis

Overview Copied

The Redis Collection Agent plugin monitors Redis servers and retrieves operational and performance metrics using the Redis Serialization Protocol (RESP).

The plugin collects data by executing standard Redis commands, including:

You can also configure custom queries using:

The plugin uses Lettuce 6.8.x as its Redis client library, providing a thread-safe synchronous API with TLS and mutual TLS (mTLS) support.

The Redis plugin supports Collection Agent publication into Geneos using Dynamic Managed Entities. To deploy:

  1. Set up the Redis Collection Agent plugin.
  2. Configure your mappings.
  3. Configure other Dynamic Entities in the Gateway. For a more detailed procedure, see Create Dynamic Entities in Collection Agent setup.

Prerequisites Copied

Before you deploy the plugin, ensure the following:

Set up the Redis Collection Agent plugin Copied

To configure the plugin, add any of the following configurations to either:

Minimum configuration Copied

Use the following minimum configuration to collect Redis metrics:

class-name: RedisCollector

connection:
  host: redis.example.com

This collects INFO (all sections) and CLIENT LIST every 60 seconds.

Full configuration Copied 

class-name: RedisCollector

# Interval (in millis) between collection cycles (optional, defaults to 60000)
collectionInterval: 30000

connection:
  host: redis.example.com       # default: localhost
  port: 6379                    # default: 6379
  username: default             # optional, for Redis ACL auth
  password: ${REDIS_PASSWORD}   # optional
  database: 0                   # default: 0

# TLS (optional, omit entire section to disable)
tls:
  certFile: /certs/redis.crt       # client cert for mTLS (optional)
  keyFile: /certs/redis.key        # client key for mTLS (optional)
  trustChainFile: /certs/ca.crt    # CA chain for server verification (optional)
  protocols:                       # optional, defaults to JVM default
    - TLSv1.3

# Metrics to collect (optional, defaults to [info, clientList])
metrics:
  - info:
      sections:
        - server
        - memory
  - clientList
  # - clusterInfo                  # enable for cluster deployments
  # - clusterNodes                 # enable for cluster deployments

queries:                           # optional, list of user-defined queries
  - name: my-query
    query: "FT.SEARCH idx:servers *"
    dimensionColumns: [hostname]
    staticDimensions:
      env: production
    dataPoints:
      - column: cpu_usage
        type: gauge
        unit: percent               # optional, see valid values below
      - column: avg_latency_ms
        type: gauge
        unit: milliseconds

Note

For descriptions of all options, see Configuration reference.

TLS configuration Copied

All connections use TLS when the tls block is present. Omit the entire block to connect without TLS. For more information, see TLS settings.

TLS with server verification Copied 

class-name: RedisCollector

connection:
  host: redis.example.com
  port: 6380

tls:
  trustChainFile: /certs/ca.pem

metrics:
  - info

TLS with mutual TLS (mTLS) Copied 

class-name: RedisCollector

connection:
  host: redis-secure.example.com
  port: 6380
  username: app-user
  password: ${env:REDIS_PASSWORD}

tls:
  certFile: /certs/client.pem
  keyFile: /certs/client-key.pem
  trustChainFile: /certs/ca.pem
  protocols:
    - TLSv1.3

metrics:
  - info:
      sections:
        - server
        - memory
        - stats
  - clientList

Example configurations Copied

Standalone with specific INFO sections and queries Copied 

class-name: RedisCollector

collectionInterval: 30000

connection:
  host: redis.example.com
  port: 6379
  password: ${env:REDIS_PASSWORD}

metrics:
  - info:
      sections:
        - server
        - memory
        - cpu
        - stats
        - replication
        - keyspace
        - clients
        - commandstats
        - latencystats
        - errorstats
  - clientList

queries:
  - name: server-inventory
    query: "FT.SEARCH idx:servers *"
    dimensionColumns:
      - hostname
      - role
    dataPoints:
      - column: cpu_usage
        type: gauge
        unit: percent
      - column: memory_usage
        type: gauge
        unit: percent
      - column: status
        type: statusmetric
      - column: region
        type: entityattribute

  - name: web-metrics
    query: "HGETALL app:metrics:web"
    staticDimensions:
      app: web
    dataPoints:
      - column: requests_per_sec
        type: gauge
        unit: per_second
      - column: avg_latency_ms
        type: gauge
        unit: milliseconds
      - column: error_rate
        type: gauge
        unit: percent

  - name: web01-detail
    query: "JSON.GET server:web-01 $"
    staticDimensions:
      hostname: web-01
    dataPoints:
      - column: value
        type: entityattribute

  - name: recent-events
    query: "LRANGE events:recent 0 -1"
    dataPoints:
      - column: value
        type: entityattribute

Cluster deployment Copied 

class-name: RedisCollector

collectionInterval: 15000

connection:
  host: redis-node-1.cluster.local
  port: 6379

metrics:
  - info
  - clientList
  - clusterInfo
  - clusterNodes

Configure your mappings Copied

To display metrics in Geneos, configure Dynamic Entity mappings and attach them to the Netprobe that receives data from the Collection Agent.

You can configure mappings using one of the following options:

Metrics collected Copied

INFO Copied

Each key-value pair from the INFO output becomes a data point.

Numeric values are published as Gauge, status-like values as StatusMetric, and all others as EntityAttribute.

Compound section parsing Copied

Several INFO sections contain compound values, for example db0:keys=42,expires=5,avg_ttl=3600000. Instead of emitting these as a single opaque string, the plugin decomposes them into individually typed metrics with additional dimensions:

Section Example line Extra dimensions Sub-metrics
keyspace db0:keys=42,expires=5,avg_ttl=3600000 database=db0 keys, expires, avg_ttl (ms)
commandstats cmdstat_get:calls=100,usec=500,usec_per_call=5.00,... command=get calls, usec (us), usec_per_call (us), rejected_calls, failed_calls
latencystats latency_percentiles_usec_get:p50=1.003,p99=2.007,... command=get p50 (us), p99 (us), p99.9 (us)
errorstats errorstat_ERR:count=5 error_type=ERR count
keysizes (Redis 8.0+) db0_distrib_strings_sizes:1=19,2=655,... database=db0, key_type=strings, size_type=sizes bucket_1, bucket_2, bucket_4, …
replication (replicas) slave0:ip=10.0.0.1,port=6380,state=online,offset=123456,lag=0 replica=slave0 ip (attr), port, state (status), offset (bytes), lag (seconds)

Non-compound lines in these sections (for example, role:master and connected_slaves:2 in the replication section) are parsed normally using the default logic.

CLUSTER INFO Copied

Key-value pairs from CLUSTER INFO output.

CLUSTER NODES Copied

Per-node metrics from CLUSTER NODES output.

CLIENT LIST Copied

Per-client metrics from CLIENT LIST output.

Query results Copied

User-defined queries produce data points based on the dataPoints configuration.

Dimensions include:

Properties include:

Alerting recommendations Copied

The following metrics are a recommended starting point for alerting. Tune thresholds for your environment and workload.

Memory Copied

Metric Section Condition Severity Rationale
mem_fragmentation_ratio memory > 1.5 Warning Excessive fragmentation; consider MEMORY PURGE or restart
mem_fragmentation_ratio memory < 1.0 Warning Redis is swapping to disk; add memory or reduce dataset

Connections Copied

Metric Section Condition Severity Rationale
connected_clients clients > 80% of maxclients Warning Approaching connection limit
blocked_clients clients > 0 (sustained) Warning Clients blocked on BLPOP/BRPOP; may indicate consumer lag
rejected_connections stats > 0 Critical Clients turned away; maxclients reached

Performance Copied

Metric Section Condition Severity Rationale
instantaneous_ops_per_sec stats Sudden drop > 50% Warning Possible slowdown, blocking command, or network issue
latency_percentiles_usec_* (p99) latencystats > 1000 us Warning Tail latency degradation; check slow log
usec_per_call commandstats > 1000 us for hot commands Warning Specific command running slowly

Keyspace Copied

Metric Section Condition Severity Rationale
keyspace_hits / (keyspace_hits + keyspace_misses) stats < 90% hit ratio Warning Low cache effectiveness; review key TTLs and eviction policy
evicted_keys stats > 0 (sustained) Warning Memory pressure forcing evictions
expired_keys stats Rapid increase Info Normal for TTL-based caches, but spikes may indicate bulk expiry

Replication Copied

Metric Section Condition Severity Rationale
role replication Changes from master to slave Critical Unexpected failover
connected_slaves replication Drops below expected count Critical Replica disconnected; replication broken
master_link_status replication down Critical Replica lost connection to master

Cluster Copied

Metric Condition Severity Rationale
cluster_state fail Critical Cluster cannot serve requests
cluster_slots_ok < 16384 Critical Not all hash slots are covered
Node link_state disconnected Warning Cluster node unreachable

Configuration reference Copied

Connection settings Copied

Field Type Description
host string

Redis server hostname or IP address.

Required: No

Default: localhost
port int

Redis server port.

Required: No

Default: 6379
username string

Redis ACL username (Redis 6+). Omit for legacy AUTH password-only mode.

Required: No

Default: None
password string

Redis password. Supports ${env:VAR} substitution.

Required: No

Default: None
database int

Redis database index (0–15)

Required: No

Default: 0

TLS settings Copied

When the tls block is present, all connections use TLS. The plugin uses Lettuce’s SslOptions, which delegates to Netty’s SslContextBuilder for TLS handling. This supports:

Field Type Description
certFile string

Path to PEM X.509 client certificate chain for mutual TLS.

Required: No

Default: None
keyFile string

Path to PKCS#8 PEM client private key for mutual TLS.

Required: No

Default: None
trustChainFile string

Path to PEM CA certificate chain for server verification.

Required: No

Default: None
protocols list

Allowed TLS protocol versions.

Valid values: TLSv1.2, TLSv1.3

Required: No

Default: None

Metrics settings Copied

A list that controls which built-in Redis commands are collected. Each entry is either a plain string or a single-key map for commands that have sub-options.

If you omit this setting, the default is [info, clientList].

Metric types Copied

Metric Description Sub-options
info Collects INFO command output (such as server, memory, CPU, stats) sections
clientList Collects CLIENT LIST per-client metrics
clusterInfo Collects CLUSTER INFO cluster state metrics
clusterNodes Collects CLUSTER NODES per-node cluster metrics

Plain string form (no sub-options):

metrics:
  - clientList
  - clusterInfo

Map form (with sub-options, currently only info supports this):

metrics:
  - info:
      sections:
        - server
        - memory

When info is listed as a plain string (without sections), all INFO sections are collected.

info.sections values Copied

Section Description
server General server info: version, uptime, OS, process ID, config file
clients Connected client counts, blocked clients, max input/output buffers
memory Memory usage, peak memory, fragmentation ratio, allocator stats
persistence RDB and AOF status, last save timestamps, rewrite progress
stats Commands processed, connections received, keyspace hits/misses, evictions
replication Role (master/replica), replication offset, connected replicas, backlog
cpu CPU time consumed (system/user for server and background processes)
modules List of loaded Redis modules
commandstats Per-command call counts, total time, and rejected calls
latencystats Per-command latency percentile distribution (p50, p99, p999)
errorstats Error counts grouped by error type
cluster Single flag indicating if cluster mode is enabled
keyspace Per-database key counts, keys with expiry, average TTL
all Returns all standard sections (equivalent to omitting sections)
everything Like all but also includes commandstats, latencystats, and errorstats

Query settings Copied

The queries setting is a list of user-defined query configurations. Each query runs a Redis command and maps the response to data points.

Field Type Description
name string

Display name for the query (added as the query_name property on each data point).

Required: Yes
query string

The raw Redis command exactly as typed in redis-cli. The parsing strategy is inferred automatically from the command prefix: FT.* commands are parsed as RediSearch results, JSON.* commands as RedisJSON results, and everything else as standard RESP.

Required: Yes
dimensionColumns list

Column names from the result to use as additional dimensions.

Required: No
staticDimensions map

Fixed key-value pairs to add as dimensions to every data point.

Required: No
dataPoints list

Mappings from result columns to data point types.

Required: No

Supported RESP commands Copied

Command Query format Result columns
GET GET <key> key, value
HGETALL HGETALL <key> One column per hash field, plus _key
LRANGE LRANGE <key> <start> <stop> _key, index, value
SMEMBERS SMEMBERS <key> _key, value

Data point types Copied

Use the following fields to map result columns to data point types.

Field Type Description
column string

The result field/column name to read the value from.

Required: Yes
type string

The data point type to emit. See Type values.

Required: Yes
unit string

Unit for Gauge data points (case-insensitive). Ignored for non-Gauge types. See Unit values.

Required: No

Type values Copied

Type Description
gauge Numeric value that can go up or down (memory usage, CPU percent)
counter Monotonically increasing numeric value (total requests)
statusmetric String value representing a state (ok, error, connected)
entityattribute String metadata about an entity (version, hostname, region)

Unit values Copied

Unit Description
none No unit / dimensionless
bytes Bytes
kilobytes Kilobytes
gigabytes Gigabytes
mebibytes Mebibytes (MiB)
seconds Seconds
milliseconds Milliseconds
microseconds Microseconds
nanoseconds Nanoseconds
minutes Minutes
hours Hours
days Days
percent Percentage
per_second Rate per second
byte_seconds Byte-seconds
epoch_milliseconds Epoch timestamp in milliseconds
["Geneos"] ["User Guide"]

Was this topic helpful?