Skip to main content
The Redis integration requires CXDOT Collector 1.12.0 or greater. Redis is an in-memory data store that applications use as a database, cache, and message broker. Use the Redis integration to collect memory, client, command, key, persistence, replication, cluster, and slow log metrics from Redis servers running in your environment. The Redis integration supports Redis Open Source 7.2 or greater.

Supported telemetry types

The Redis integration supports these telemetry types:

Prerequisites

The Redis integration has the following prerequisites:
  • Make port 6379, or your custom Redis port, reachable from the CXDOT Collector over TCP. The integration doesn’t support Unix domain sockets.
  • If your Redis servers require authentication, prepare credentials for the CXDOT Collector. On a server protected only by the requirepass password, the Collector authenticates with that password, so you don’t need to create a user. On a server that uses an access control list (ACL), connect with redis-cli as a user that can manage users, and create a user that can run only the commands the Collector sends:
    Replace PASSWORD with a password for this user. The examples on this page use the username cxdot. If you choose another username, use it in the configuration too. To keep the user after the server restarts, run ACL SAVE if the server loads its users from an ACL file, or CONFIG REWRITE if it loads them from its configuration file.
  • If you enable the optional collections in the Configure section, grant their additional permissions. Collecting connections per client name needs +client|list. Collecting key lengths needs +type +llen +scard +zcard +hlen +xlen, +scan when keys contains a glob pattern, read access to the keys you list (for example, '%R~queue:*'), and +select when the keys are in databases other than 0. The Collector doesn’t report a length for a key that the user can’t read. Per-command statistics come from INFO and need no extra permission.
  • On Redis 7.2 or greater, the redis.acl.denied metric counts requests that ACL rules deny, including requests from the Collector. Each collection that reads a key the user can’t read causes a denial with redis.acl.denied.reason set to key. Each time the Collector connects, it sends CLIENT SETINFO to report its client library name. The Collector doesn’t depend on this command, but each denied CLIENT SETINFO request increments the count for the cmd reason and appears in the ACL log. Therefore, the count increases with every connection. To keep these denials out of redis.acl.denied and the ACL log, also grant +client|setinfo. Redis versions before 7.2 reject +client|setinfo, so omit it on those versions.

Configure

The Redis integration is enabled by default. It collects from each Redis server independently, whether the server is a standalone server, a primary, or a replica, and whether or not it runs in cluster mode. The Collector doesn’t follow cluster redirects or use discovered servers to find other nodes. Make sure that the Collector discovers each node that you want to monitor, or list the node as a static target.

Configure on Kubernetes

You can configure targets in Kubernetes either by annotating Redis pods or by listing static endpoints in your Helm values. To configure the Redis integration in Kubernetes, follow these steps:
  1. To collect from Redis pods in Kubernetes, add a CXDOT integration annotation to the pod template. The annotation key must end with the container name, and its value can reference credentials stored in a Kubernetes Secret in the same namespace. For example, add the following annotation to your Redis workload:
    The Collector replaces ${target.host} with the pod IP address, ${target.port.redis} with the container port named redis, and ${k8s_secret:redis-credentials/password} with the password key of the redis-credentials Secret. To allow the Collector to read the Secret, add the pod’s namespace to apiServer.metadataServer.secretAllowlist in the Helm values for your CXDOT Collector. The Collector also discovers Redis pods that carry the app.kubernetes.io/name: redis label and listen on port 6379. The Collector connects without credentials or TLS to every pod that it finds by label. A CXDOT integration annotation takes precedence over the label for its container. To stop collecting from a container, set redis: {enabled: false} in the annotation. Metrics from each discovered pod include that pod’s Kubernetes metadata. For more information, see autodiscovery.
  2. Optional: To collect from Redis servers outside your Kubernetes cluster, configure static targets. For example, add the following to the Helm values file for your CXDOT Collector:
    When you configure static targets, this integration instance collects from exactly those targets instead of discovered targets. Static targets use the integration’s username, password, and tls settings. The cluster Collector collects from static targets, so provide any password environment variable through clusterCollector.extraEnv. For more information about Collector tiers, see architecture.
  3. Optional: Collect per-command statistics, open connections per client name, or the lengths of specific keys. These collections are off by default. In the Helm values, these settings apply to the static targets that the same integration instance lists. For example, add the following to that instance in the Helm values file for your CXDOT Collector:
    Per-command statistics add one time series for each command that the server has run. Client metrics run CLIENT LIST, whose response grows with the number of connections. Each key length reads the key type and its type-specific length. A glob pattern in keys, such as queue:*, also scans every key in each database that holds keys. On a server with many keys, list key names rather than patterns where possible. For an annotated pod, set them in its CXDOT integration annotation.
  4. Optional: Configure a second integration instance to collect from both annotated pods and static targets, or to use different credentials for some static targets. For example, add the following to the Helm values file for your CXDOT Collector:
    The redis/external key defines a named instance for the static targets, with its own credentials. The bare redis key continues to collect from discovered targets. Provide EXTERNAL_REDIS_PASSWORD through clusterCollector.extraEnv.
  5. Optional: Disable the integration. For example, add the following to the Helm values file for your CXDOT Collector:

Configure on a host

To configure the Redis integration on a host outside Kubernetes, such as a virtual machine, install the CXDOT Collector on Linux on each Redis host. Run the Collector in host mode and list the local server. For example, add the following to the Collector configuration file:
The example reads the password from the REDIS_PASSWORD environment variable of the Collector process. On a host, the integration collects only from the servers in instances. The Collector adds the host’s host.name attribute to every metric. When every endpoint is localhost, host.name identifies the server. To collect from more than one server on a host, such as several cluster nodes on different ports, list each one.

Validate

To validate the Redis integration, follow these steps:
  1. In Live Telemetry Analyzer, filter for __name__=cxdot.integration.target.health and cxdot.integration.name=redis. Confirm that each expected target reports 1. A value of 0 means that the Collector couldn’t connect to the server, authenticate, or run PING and INFO. Use the server.address and server.port attributes, and host.name on hosts, to identify each target.
  2. In Metrics Explorer, run the following query:
    Confirm that the query returns one time series per target.

Troubleshooting

  • A target reports 0 and the Collector logs NOAUTH Authentication required or WRONGPASS: The server requires credentials that the Collector didn’t send, or the supplied credentials don’t match. Static targets use the integration’s username and password, and targets that the Collector finds by annotation use the credentials in their annotations. Servers that the Collector finds by label connect without credentials, so configure a password-protected server with a CXDOT integration annotation instead.
  • Some metrics are missing from a Valkey server: The integration collects from Valkey, a fork of Redis, on a best-effort basis. Metrics that Valkey reports differently from Redis might be missing.
  • A target reports 0 for a while after the Redis server starts: A server that loads its dataset from disk at startup rejects PING until loading finishes, so the Collector reports it as unreachable until then.
  • Metrics don’t carry the server’s primary or replica role: The Collector reports the role once per server, as the redis.role metric with a role attribute, so promoting a replica doesn’t start new time series for every metric. To filter by role, join on the server’s identity. For example, the following query returns memory use for primaries only:
  • Slow log metrics don’t include entries from before the Collector started: The redis.slowlog.duration histogram counts each slow log entry once and starts from the newest entry when the Collector first reads the slow log, after the Redis server restarts, or after the Collector reaches a different server. Because each collection reads at most the newest 128 entries, the histogram counts only part of a burst of more than 128 slow commands within one collection interval.

Configuration reference

Configure one Redis integration instance with the following settings. In Helm values, place these settings under collection.cxdot.integrations.redis. In a Collector configuration file, place them under cxdot.integrations.redis.

Optional settings

  • enabled Type: boolean. Optional. Default: true. Whether to run the Redis integration. If true, the Collector collects Redis metrics. If false, the Collector doesn’t run this integration.
  • username Type: string. Optional. Default: empty string. Redis ACL username for connections to the configured targets. Leave empty to authenticate as the Redis default user. Targets that the Collector finds by annotation use the credentials in their annotations. Targets that the Collector finds by label don’t use this setting.
  • password Type: string. Optional. Redis password for connections to the configured targets: the requirepass password, or the ACL user’s password when username is set. The Collector reports a target as unreachable when the target requires a password that the Collector doesn’t send. Targets that the Collector finds by annotation use the credentials in their annotations. Targets that the Collector finds by label don’t use this setting. The Collector masks this value in configuration views, diagnostic output, and logs.
  • collection_interval Type: duration. Optional. Default: 10s. Time between metric collections from each configured target. Use a Go duration string, such as 10s or 1m. Targets that the Collector finds by label use the integration default. Targets that the Collector finds by annotation use the collection interval their annotations set.
  • timeout Type: duration. Optional. Default: 10s. Maximum time allowed to collect metrics from one configured Redis target. Use a Go duration string, such as 10s or 1m. The value must not exceed collection_interval. Discovered targets use the timeout from their discovery configuration.
  • instances Type: array of object. Optional. Default: []. Redis targets. Each entry’s endpoint is host:port, for example, redis.default.svc:6379. Enclose a literal IPv6 address in brackets, such as [2001:db8::1]:6379. When this list isn’t empty, the integration collects from exactly these targets instead of discovered targets. On a host, the integration collects only from this list. In a Redis Cluster, list every node: each node reports only its own state, and the Collector doesn’t discover other nodes from a listed node.
  • instances[].endpoint Type: string. Required. Redis target in host:port format. Enclose a literal IPv6 address in brackets, such as [2001:db8::1]:6379.
  • command_stats Type: boolean. Optional. Default: false. Whether to collect per-command statistics from configured targets through the INFO commandstats section: the number of calls to each command and the CPU time spent running it. If true, the Collector reports redis.cmd.calls and redis.cmd.usec, with one time series for each command that the server has run. If false, the Collector doesn’t report them. Targets that the Collector finds by annotation use the command_stats setting in their annotations. Targets that the Collector finds by label don’t collect these statistics.
  • collect_client_metrics Type: boolean. Optional. Default: false. Whether to count the open connections to each configured target by the name that clients set with CLIENT SETNAME. If true, the Collector runs CLIENT LIST at each collection and reports redis.clients.connection.count, counting connections without a name as unknown. If false, the Collector doesn’t run CLIENT LIST or report redis.clients.connection.count. The CLIENT LIST reply grows with the number of connections. Targets that the Collector finds by annotation use the collect_client_metrics setting in their annotations. Targets that the Collector finds by label don’t collect these metrics.
  • keys Type: array of string. Optional. Default: []. Keys whose lengths the Collector reports as redis.key.length for configured targets. Each entry is a key name or a glob pattern. An entry that contains *, ?, or [ without a preceding backslash is a glob pattern. The length is the number of elements in a list, set, sorted set, hash, or stream, and 1 for a string. Each collection reads every listed key in every database that holds keys, or only in the database specified by db when that setting is set. A glob pattern scans every key in each database that the Collector reads, so its cost grows with the number of keys on the server. When a read fails or doesn’t finish within timeout, the Collector reports no key lengths for that collection. A listed key that has no elements in any database reports 0. A glob pattern that matches nothing in a nonempty database reports no time series. Targets that the Collector finds by annotation use the keys setting in their annotations. Targets that the Collector finds by label don’t collect key lengths.
  • db Type: integer. Optional. Minimum: 0. Number of the database to read keys from. If omitted, the Collector reads every database that holds keys. If this database holds no keys, the Collector reports 0 for every entry in keys. Only keys uses this setting, because every other metric covers the whole server.
  • warn_on_missing_keys Type: boolean. Optional. Default: true. Whether to log a warning for each entry in keys that has no elements in any database that the Collector reads. If true, the Collector logs the warning at each collection. If false, the Collector reports a length of 0 for the entry without logging an entry-specific warning. The Collector still logs a warning when the Redis keyspace is empty, the selected database holds no keys, or a key-length read fails.
  • tls Type: object. Optional. TLS settings for connections to the configured targets. TLS is on when insecure is false or the block sets ca_file or ca_pem. With TLS on, the Collector verifies the server certificate unless insecure_skip_verify is true. Targets that the Collector finds by annotation use the TLS settings in their annotations. Targets that the Collector finds by label don’t use these settings.
  • tls.ca_file Type: string. Optional. Path to a PEM-encoded certificate authority (CA) certificate file used to verify the Redis server certificate. Don’t set both ca_file and ca_pem. If neither is set, the Collector uses the system certificate authority pool. When ca_file is set, the Collector uses only this file unless include_system_ca_certs_pool is true.
  • tls.ca_pem Type: string. Optional. PEM-encoded certificate authority certificate content used to verify the Redis server certificate. Don’t set both ca_pem and ca_file. When ca_pem is set, the Collector uses only these certificates unless include_system_ca_certs_pool is true.
  • tls.cert_file Type: string. Optional. Path to the PEM-encoded client certificate file to present to the Redis server. A Redis server with TLS enabled requires a client certificate unless its tls-auth-clients setting is no or optional. Set key_file or key_pem with this setting. Don’t set both cert_file and cert_pem.
  • tls.cert_pem Type: string. Optional. PEM-encoded client certificate content to present to the Redis server. Set key_file or key_pem with this setting. Don’t set both cert_pem and cert_file.
  • tls.cipher_suites Type: array of string. Optional. TLS 1.0 through 1.2 cipher suites that the Collector can use. The order of the list doesn’t matter, and TLS 1.3 cipher suites aren’t configurable. If omitted, the Collector uses the secure defaults from the Go TLS library. For supported names, see https://go.dev/src/crypto/tls/cipher_suites.go.
  • tls.curve_preferences Type: array of string. Optional. Key exchange mechanisms the Collector can use for TLS handshakes. The order of the list doesn’t matter. The Go TLS library applies its internal preference order to the enabled mechanisms. Supported values are the elliptic curves P256, P384, P521, and X25519, and X25519MLKEM768, a hybrid post-quantum key exchange. If omitted, the Collector uses the Go TLS library defaults.
  • tls.include_system_ca_certs_pool Type: boolean. Optional. Whether to add certificates from the system certificate authority pool to a custom CA configured with ca_file or ca_pem. If true, the Collector trusts both the custom CA and the system pool. If false, the Collector trusts only the custom CA.
  • tls.insecure Type: boolean. Optional. Default: true. Whether to connect to Redis without TLS. If true and neither ca_file nor ca_pem is set, the Collector uses an unencrypted connection. If false, or if ca_file or ca_pem is set, the Collector connects over TLS.
  • tls.insecure_skip_verify Type: boolean. Optional. Whether to skip verification of the Redis server certificate. If true, the connection is encrypted but isn’t authenticated and is vulnerable to machine-in-the-middle attacks. If false, the Collector verifies the certificate. Applies only when TLS is on.
  • tls.key_file Type: string. Optional. Path to the PEM-encoded client private key file used with cert_file or cert_pem for mutual TLS authentication. Don’t set both key_file and key_pem.
  • tls.key_pem Type: string. Optional. PEM-encoded client private key content used with cert_file or cert_pem for mutual TLS authentication. Don’t set both key_pem and key_file. The Collector masks this value in configuration views, diagnostic output, and logs.
  • tls.max_version Type: string. Optional. Maximum TLS protocol version the Collector can use: 1.0, 1.1, 1.2, or 1.3. The value must be greater than or equal to min_version. If omitted, the Collector uses the maximum version supported by the Go TLS library.
  • tls.min_version Type: string. Optional. Minimum TLS protocol version the Collector can use: 1.0, 1.1, 1.2, or 1.3. The value must be less than or equal to max_version. If omitted, the minimum version is TLS 1.2.
  • tls.reload_interval Type: duration. Optional. How often the Collector reloads certificate and key files, as a Go duration string such as 1m. If omitted, the Collector doesn’t reload file-backed certificate and key material.
  • tls.server_name_override Type: string. Optional. Server name to verify in the Redis server certificate instead of the endpoint hostname. Use this setting when the certificate name differs from the endpoint hostname.
  • tls.tpm Type: object. Optional. Trusted platform module settings for the TLS private key.
  • tls.tpm.auth Type: string. Optional. Authorization value for the trusted platform module key. The Collector masks this value in configuration views, diagnostic output, and logs.
  • tls.tpm.enabled Type: boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the Collector uses the trusted platform module at tpm.path with the key material from key_file or key_pem. If false, the Collector uses the configured software key.
  • tls.tpm.owner_auth Type: string. Optional. Owner authorization value for the trusted platform module. The Collector masks this value in configuration views, diagnostic output, and logs.
  • tls.tpm.path Type: string. Optional. Path to the trusted platform module device or Unix domain socket, such as /dev/tpm0 or /dev/tpmrm0.