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
requirepasspassword, 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 withredis-clias a user that can manage users, and create a user that can run only the commands the Collector sends:ReplacePASSWORDwith a password for this user. The examples on this page use the usernamecxdot. If you choose another username, use it in the configuration too. To keep the user after the server restarts, runACL SAVEif the server loads its users from an ACL file, orCONFIG REWRITEif 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,+scanwhenkeyscontains a glob pattern, read access to the keys you list (for example,'%R~queue:*'), and+selectwhen the keys are in databases other than0. The Collector doesn’t report a length for a key that the user can’t read. Per-command statistics come fromINFOand need no extra permission. -
On Redis 7.2 or greater, the
redis.acl.deniedmetric 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 withredis.acl.denied.reasonset tokey. Each time the Collector connects, it sendsCLIENT SETINFOto report its client library name. The Collector doesn’t depend on this command, but each deniedCLIENT SETINFOrequest increments the count for thecmdreason and appears in the ACL log. Therefore, the count increases with every connection. To keep these denials out ofredis.acl.deniedand 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:-
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 namedredis, and${k8s_secret:redis-credentials/password}with thepasswordkey of theredis-credentialsSecret. To allow the Collector to read the Secret, add the pod’s namespace toapiServer.metadataServer.secretAllowlistin the Helm values for your CXDOT Collector. The Collector also discovers Redis pods that carry theapp.kubernetes.io/name: redislabel and listen on port6379. 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, setredis: {enabled: false}in the annotation. Metrics from each discovered pod include that pod’s Kubernetes metadata. For more information, see autodiscovery. -
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, andtlssettings. The cluster Collector collects from static targets, so provide any password environment variable throughclusterCollector.extraEnv. For more information about Collector tiers, see architecture. -
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 inkeys, such asqueue:*, 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. -
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/externalkey defines a named instance for the static targets, with its own credentials. The barerediskey continues to collect from discovered targets. ProvideEXTERNAL_REDIS_PASSWORDthroughclusterCollector.extraEnv. -
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: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:-
In Live Telemetry Analyzer, filter for
__name__=cxdot.integration.target.healthandcxdot.integration.name=redis. Confirm that each expected target reports1. A value of0means that the Collector couldn’t connect to the server, authenticate, or runPINGandINFO. Use theserver.addressandserver.portattributes, andhost.nameon hosts, to identify each target. -
In Metrics Explorer, run the following query:
Confirm that the query returns one time series per target.
Troubleshooting
-
A target reports
0and the Collector logsNOAUTH Authentication requiredorWRONGPASS: The server requires credentials that the Collector didn’t send, or the supplied credentials don’t match. Static targets use the integration’susernameandpassword, 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
0for a while after the Redis server starts: A server that loads its dataset from disk at startup rejectsPINGuntil 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.rolemetric with aroleattribute, 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.durationhistogram 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 undercollection.cxdot.integrations.redis. In a Collector configuration file,
place them under cxdot.integrations.redis.
Optional settings
-
enabledType: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. -
usernameType:string. Optional. Default: empty string. Redis ACL username for connections to the configured targets. Leave empty to authenticate as the Redisdefaultuser. 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. -
passwordType:string. Optional. Redis password for connections to the configured targets: therequirepasspassword, or the ACL user’s password whenusernameis 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_intervalType:duration. Optional. Default:10s. Time between metric collections from each configured target. Use a Go duration string, such as10sor1m. 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. -
timeoutType:duration. Optional. Default:10s. Maximum time allowed to collect metrics from one configured Redis target. Use a Go duration string, such as10sor1m. The value must not exceedcollection_interval. Discovered targets use the timeout from their discovery configuration. -
instancesType:array of object. Optional. Default:[]. Redis targets. Each entry’sendpointishost: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[].endpointType:string. Required. Redis target inhost:portformat. Enclose a literal IPv6 address in brackets, such as[2001:db8::1]:6379. -
command_statsType:boolean. Optional. Default:false. Whether to collect per-command statistics from configured targets through theINFO commandstatssection: the number of calls to each command and the CPU time spent running it. If true, the Collector reportsredis.cmd.callsandredis.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 thecommand_statssetting in their annotations. Targets that the Collector finds by label don’t collect these statistics. -
collect_client_metricsType:boolean. Optional. Default:false. Whether to count the open connections to each configured target by the name that clients set withCLIENT SETNAME. If true, the Collector runsCLIENT LISTat each collection and reportsredis.clients.connection.count, counting connections without a name asunknown. If false, the Collector doesn’t runCLIENT LISTor reportredis.clients.connection.count. TheCLIENT LISTreply grows with the number of connections. Targets that the Collector finds by annotation use thecollect_client_metricssetting in their annotations. Targets that the Collector finds by label don’t collect these metrics. -
keysType:array of string. Optional. Default:[]. Keys whose lengths the Collector reports asredis.key.lengthfor 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, and1for a string. Each collection reads every listed key in every database that holds keys, or only in the database specified bydbwhen 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 withintimeout, the Collector reports no key lengths for that collection. A listed key that has no elements in any database reports0. A glob pattern that matches nothing in a nonempty database reports no time series. Targets that the Collector finds by annotation use thekeyssetting in their annotations. Targets that the Collector finds by label don’t collect key lengths. -
dbType:integer. Optional. Minimum:0. Number of the database to readkeysfrom. If omitted, the Collector reads every database that holds keys. If this database holds no keys, the Collector reports0for every entry inkeys. Onlykeysuses this setting, because every other metric covers the whole server. -
warn_on_missing_keysType:boolean. Optional. Default:true. Whether to log a warning for each entry inkeysthat 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 of0for 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. -
tlsType:object. Optional. TLS settings for connections to the configured targets. TLS is on wheninsecureisfalseor the block setsca_fileorca_pem. With TLS on, the Collector verifies the server certificate unlessinsecure_skip_verifyistrue. 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_fileType:string. Optional. Path to a PEM-encoded certificate authority (CA) certificate file used to verify the Redis server certificate. Don’t set bothca_fileandca_pem. If neither is set, the Collector uses the system certificate authority pool. Whenca_fileis set, the Collector uses only this file unlessinclude_system_ca_certs_poolistrue. -
tls.ca_pemType:string. Optional. PEM-encoded certificate authority certificate content used to verify the Redis server certificate. Don’t set bothca_pemandca_file. Whenca_pemis set, the Collector uses only these certificates unlessinclude_system_ca_certs_poolistrue. -
tls.cert_fileType: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 itstls-auth-clientssetting isnooroptional. Setkey_fileorkey_pemwith this setting. Don’t set bothcert_fileandcert_pem. -
tls.cert_pemType:string. Optional. PEM-encoded client certificate content to present to the Redis server. Setkey_fileorkey_pemwith this setting. Don’t set bothcert_pemandcert_file. -
tls.cipher_suitesType: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_preferencesType: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 curvesP256,P384,P521, andX25519, andX25519MLKEM768, a hybrid post-quantum key exchange. If omitted, the Collector uses the Go TLS library defaults. -
tls.include_system_ca_certs_poolType:boolean. Optional. Whether to add certificates from the system certificate authority pool to a custom CA configured withca_fileorca_pem. If true, the Collector trusts both the custom CA and the system pool. If false, the Collector trusts only the custom CA. -
tls.insecureType:boolean. Optional. Default:true. Whether to connect to Redis without TLS. If true and neitherca_filenorca_pemis set, the Collector uses an unencrypted connection. If false, or ifca_fileorca_pemis set, the Collector connects over TLS. -
tls.insecure_skip_verifyType: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_fileType:string. Optional. Path to the PEM-encoded client private key file used withcert_fileorcert_pemfor mutual TLS authentication. Don’t set bothkey_fileandkey_pem. -
tls.key_pemType:string. Optional. PEM-encoded client private key content used withcert_fileorcert_pemfor mutual TLS authentication. Don’t set bothkey_pemandkey_file. The Collector masks this value in configuration views, diagnostic output, and logs. -
tls.max_versionType:string. Optional. Maximum TLS protocol version the Collector can use:1.0,1.1,1.2, or1.3. The value must be greater than or equal tomin_version. If omitted, the Collector uses the maximum version supported by the Go TLS library. -
tls.min_versionType:string. Optional. Minimum TLS protocol version the Collector can use:1.0,1.1,1.2, or1.3. The value must be less than or equal tomax_version. If omitted, the minimum version is TLS 1.2. -
tls.reload_intervalType:duration. Optional. How often the Collector reloads certificate and key files, as a Go duration string such as1m. If omitted, the Collector doesn’t reload file-backed certificate and key material. -
tls.server_name_overrideType: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.tpmType:object. Optional. Trusted platform module settings for the TLS private key. -
tls.tpm.authType:string. Optional. Authorization value for the trusted platform module key. The Collector masks this value in configuration views, diagnostic output, and logs. -
tls.tpm.enabledType:boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the Collector uses the trusted platform module attpm.pathwith the key material fromkey_fileorkey_pem. If false, the Collector uses the configured software key. -
tls.tpm.owner_authType:string. Optional. Owner authorization value for the trusted platform module. The Collector masks this value in configuration views, diagnostic output, and logs. -
tls.tpm.pathType:string. Optional. Path to the trusted platform module device or Unix domain socket, such as/dev/tpm0or/dev/tpmrm0.