--- title: Redis monitoring integration source: https://docs.newrelic.com/docs/infrastructure/host-integrations/host-integrations-list/redis/redis-integration --- Our Redis integration reports critical performance data from your [Redis](https://redis.io) server to New Relic products. You can view this [metric data](#metrics) and [inventory data](#inventory) in pre-built dashboards, create alert policies, and create custom queries and charts. You can also specify keys that are important to your application and get information about their length. Read on to install the integration, and to see what data we collect. ## Compatibility and requirements [#comp-req] Our integration is compatible with Redis versions from 3.0 to 7.0. Before installing the integration, make sure that you meet the following requirements: - A New Relic account. Don't have one? [Sign up for free!](https://newrelic.com/signup) No credit card required. - If Redis is **not** running on Kubernetes or Amazon ECS, you must [install the infrastructure agent](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/get-started/install-infrastructure-agent-new-relic) on a Linux OS host that's running Redis. Otherwise: - If running on Kubernetes, see [these requirements](https://docs.newrelic.com/docs/monitor-service-running-kubernetes#requirements). - If running on ECS, see [these requirements](https://docs.newrelic.com/docs/integrations/host-integrations/host-integrations-list/monitor-services-running-amazon-ecs). The integration obtains data by executing Redis commands: - [`INFO` command](https://redis.io/commands/info): Data from the INFO command populates metric data and some inventory data. - [`CONFIG GET` command](https://redis.io/commands/config-get): Most inventory data comes from this command. - In managed Redis installations without permissions to execute the `CONFIG` command (for example, AWS ElastiCache), the execution of this command can be disabled with the `config_inventory: false` configuration option. - Key length acquisition: Depending on the type of key, these commands are used: - [`LLEN`](https://redis.io/commands/llen) for `list` - [`SCARD`](https://redis.io/commands/scard) for `set` - [`ZCOUNT`](https://redis.io/commands/zcount) for `zset` - [`HLEN`](https://redis.io/commands/hlen) for `hash` type. For key length data collection, the agent uses [pipelining](https://redis.io/topics/pipelining) to minimize the impact on your Redis performance. However, if you are collecting the length of many keys, your Redis performance may be affected. For this reason, the agent includes a default key limit (but this limit can be overwritten). > #### ⚠️ IMPORTANT > > If you edited the names of the Redis commands mentioned above, the integration > will not be able to retrieve the Redis data. ## Quick start [#quick] Instrument your Redis server quickly and send your telemetry data with guided install. Our guided install creates a customized CLI command for your environment that downloads and installs the New Relic CLI and the infrastructure agent. Ready to get started? Click one of these buttons to try it out. [Guided install](https://one.newrelic.com/marketplace/install-data-source?state=eea8674d-6cb6-b7c3-e0c9-d25f5d75ff79) [EU Guided install](https://one.eu.newrelic.com/marketplace/install-data-source?state=eea8674d-6cb6-b7c3-e0c9-d25f5d75ff79) [JP Guided install](https://onenr.io/0LwGrMWyYQ6) ## Install and activate [#install] To install the Redis integration, follow the instructions for your environment: Additional notes: - **Advanced:** Integrations are also available in [tarball format](https://docs.newrelic.com/docs/integrations/host-integrations/installation/install-host-integrations-built-new-relic#tarball) to allow installation outside of a package manager. - **On-host integrations do not automatically update.** For best results, regularly [update the integration package](https://docs.newrelic.com/docs/integrations/host-integrations/installation/update-infrastructure-host-integration-package) and [the infrastructure agent](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/installation/update-infrastructure-agent). **ECS** See [Monitor service running on ECS](https://docs.newrelic.com/docs/integrations/host-integrations/host-integrations-list/monitor-services-running-amazon-ecs). ' ' **Kubernetes** See [Monitor service running on Kubernetes](https://docs.newrelic.com/docs/monitor-service-running-kubernetes). **Linux** 1. Install [the infrastructure agent](https://docs.newrelic.com/docs/integrations/host-integrations/installation/install-infrastructure-host-integrations/#install), and replace the `INTEGRATION_FILE_NAME` variable with `nri-redis`. 2. Change the directory to the integrations configuration folder: ```sh cd /etc/newrelic-infra/integrations.d ``` 3. Copy the sample configuration file: ```sh sudo cp redis-config.yml.sample redis-config.yml ``` 4. Edit the `redis-config.yml` file based on your Redis server connection methods: **Connect with Unix socket** If you connect using Unix socket, specify the `unix_socket_path` in the [configuration file](#config). If there are more than one Redis instance using Unix sockets, make sure to set `use_unix_socket` to `true` in the [configuration file](#config). Be sure that the user executing the Redis integration has correct permissions for accessing that Unix socket. The permissions of the Unix socket are set in the Redis configuration (value of `unixsocketperm`). **Connect with TCP** If you connect via TCP, the [config file](config) is by default set to `localhost` and port `6379`. You can change this by specifying `hostname` and/or the `port` argument. If you use this method, the `unix_socket_path` parameter cannot be set. 5. If required, set other configuration file settings based on your Redis setup, as described in [Configuration](#config). 6. To enable automatic Redis error log parsing and forwarding, copy (or rename) the `redis-log.yml.example` file to `redis-log.yml`. No need to restart the agent. **Example:** ```sh sudo cp /etc/newrelic-infra/logging.d/redis-log.yml.example /etc/newrelic-infra/logging.d/redis-log.yml ``` **Windows** 1. Download the `nri-redis` .MSI installer image from: 2. To install from the Windows command prompt, run: ```sh msiexec.exe /qn /i PATH\TO\nri-redis-amd64.msi ``` or double-click the file in Explorer. 3. In the Integrations directory, `C:\Program Files\New Relic\newrelic-infra\integrations.d\`, create a copy of the sample configuration file by running: ```sh copy redis-win-config.yml.sample redis-win-config.yml ``` 4. Edit the `redis-win-config.yml` file as described in the [configuration settings](#config). ## Create a New Relic user for your Redis server [#enable-instance] If you're using Redis 6+ and using access control lists (ACLs) to control access to your instance, you may want to create a `newrelic` user for the integration. Use this command to create and grant the required permissions to your user: ```sh ACL SETUSER newrelic on >'YOUR_SELECTED_PASSWORD' ~* +INFO +CONFIG|GET +SELECT +TYPE +LLEN +SCARD +ZCOUNT +HLEN ``` ## Configure the integration [#config] There are several ways to configure the integration, depending on how it was installed: - If enabled via Kubernetes: see [Monitor services running on Kubernetes](https://docs.newrelic.com/docs/monitor-service-running-kubernetes). - If enabled via Amazon ECS: see [Monitor services running on ECS](https://docs.newrelic.com/docs/integrations/host-integrations/host-integrations-list/monitor-services-running-amazon-ecs). - If installed on-host: edit the config in the integration's YAML configuration file `redis-config.yml`. Use the YAML configuration to place required login credentials and configure how your data is collected, depending on your setup and preference. The configuration file has common settings applicable to all integrations, like `interval`, `timeout`, `inventory_source`. To learn more about these common settings, see our [YAML configuration format](https://docs.newrelic.com/docs/create-integrations/infrastructure-integrations-sdk/specifications/host-integrations-newer-configuration-format/#configuration-basics). > #### ⚠️ IMPORTANT > > If you're still using our legacy configuration/definition files, use our > [older, standard configuration > foramt](https://docs.newrelic.com/docs/create-integrations/infrastructure-integrations-sdk/specifications/host-integrations-standard-configuration-format/). Specific settings related to Redis are defined using the `env` section of the configuration file. These settings control the connection to your Redis instance as well as other security settings and features. ## Redis instance settings [#instance-settings] The Redis integration collects both Metrics(**M**) and Inventory(**I**) information. In the table, use the **Applies To** column for the settings available to each collection: | Setting | Description | Default | Applies To | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- | | `HOSTNAME` | Redis server hostname. | `localhost` | M/I | | `PORT` | Port where Redis server is listening. | `6379` | M/I | | `USERNAME` | Username to use when connecting to the Redis server. Use only with Redis 6+ if ACL is enabled. | N/A | M/I | | `PASSWORD` | Password to use when connecting to the Redis server. Use only with Redis servers if `REQUIREPASS` or ACL is enabled. | N/A | M/I | | `UNIX_SOCKET_PATH` | Path to Unix socket file on which Redis server is listening. Use this instead of Hostname/Port. | N/A | M/I | | `USE_UNIX_SOCKET` | Set to `true` to uniquely identify the monitored entities when using Unix sockets. | `false` | M/I | | `USE_TLS` | Use TLS when communicating with the Redis server. | `false` | M/I | | `TLS_INSECURE_SKIP_VERIFY` | Disable server name verification when connecting over TLS. | `false` | M/I | | `KEYS` | List of the keys for retrieving their lengths. | N/A | M | | `KEYS_LIMIT` | Max number of keys to retrieve their lengths. | `30` | M | | `CONFIG_INVENTORY` | Set to 'false' in environments where the Redis CONFIG command is not allowed (for example, AWS or ElastiCache). | `true` | I | | `RENAMED_COMMANDS` | Map default Redis commands to their renamed form. | N/A | M/I | | [`REMOTE_MONITORING`](https://docs.newrelic.com/docs/remote-monitoring-host-integrations) | Enable multi-tenancy monitoring. | `true` | M/I | | `METRICS` | Set to `true` to enable metrics-only collection. | `false` | | | `INVENTORY` | Set to `true` to enable inventory-only collection. | `false` | | The values for these settings can be defined in several ways: - Add the value directly to the configuration file. This is the most common way. - Replace the values from environment variables using the `{{}}` notation. This requires infrastructure agent 1.14.0+. For more on this, see more on [infrastructure agent passthrough environment variables](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/configuration/configure-infrastructure-agent/#passthrough). - Use secrets management to protect sensible information, such as passwords, so that it's not exposed in plain text on the configuration file. For more information, see [secrets management](https://docs.newrelic.com/docs/integrations/host-integrations/installation/secrets-management). ## Labels and custom attributes [#labels] You can also decorate your metrics with labels. Labels allow you to add key/value pair attributes to your metrics so that you can query, filter, or group your metrics. Even though our default sample configuration file includes examples of labels, they're optional. You can remove, modify, or add new ones. ```yml labels: env: production role: load_balancer ``` ## Example configurations [#examples] **Basic configuration** This is the basic configuration used to collect metrics and inventory from your localhost: ````yml integrations: - name: nri-redis env: METRICS: true HOSTNAME: localhost PORT: 6379 REMOTE_MONITORING: true interval: 15s labels: environment: production - name: nri-redis env: INVENTORY: true HOSTNAME: localhost PORT: 6379 REMOTE_MONITORING: true interval: 60s labels: environment: production inventory_source: config/redis ``` ```` **Basic authentication** This configuration connects to Redis using basic authentication. Replace `my_password` with your `REQUIREPASS` password: ````yml integrations: - name: nri-redis env: METRICS: true HOSTNAME: localhost PORT: 6379 PASSWORD: "my_password" REMOTE_MONITORING: true interval: 15s labels: environment: production - name: nri-redis env: INVENTORY: true HOSTNAME: localhost PORT: 6379 PASSWORD: "my_password" REMOTE_MONITORING: true interval: 60s labels: environment: production inventory_source: config/redis ``` ```` **REDIS 6+ ACL authentication** In Redis 6+, you can protect your instance with [Access Control Lists (ACLs)](https://redis.io/topics/acl). For ACLs, replace the `USERNAME` and `PASSWORD` values with your credentials: ````yml integrations: - name: nri-redis env: METRICS: true HOSTNAME: localhost PORT: 6379 USERNAME: my_user PASSWORD: "my_password" REMOTE_MONITORING: true interval: 15s labels: environment: production - name: nri-redis env: INVENTORY: true HOSTNAME: localhost PORT: 6379 USERNAME: my_user PASSWORD: "my_password" REMOTE_MONITORING: true interval: 60s labels: environment: production inventory_source: config/redis ``` ```` **Metrics-only with TLS connection** Use to connect to Redis with TLS. You can add `TLS_INSECURE_SKIP_VERIFY : true` to disable the server name verification: ````yml integrations: - name: nri-redis env: METRICS: true HOSTNAME: localhost PORT: 6379 USE_TLS: true REMOTE_MONITORING: true interval: 15s labels: environment: production ``` ```` **Metrics-only connecting over socket** Use to connect to Redis using a socket file. This is an alternative to a TCP Hostname/Port connection: ````yml integrations: - name: nri-redis env: METRICS: true UNIX_SOCKET_PATH: /var/run/redis/redis.sock USE_UNIX_SOCKET: true REMOTE_MONITORING: true interval: 15s labels: environment: production ``` ```` **Using renamed commands** Use this to collect your metrics/inventory if you've used the [`rename-command`](https://redis.io/topics/security#disabling-of-specific-commands) to protect your instance: ````yml integrations: - name: nri-redis env: METRICS: true HOSTNAME: localhost PORT: 6379 RENAMED_COMMANDS: '{"CONFIG":"b840fc9f15f59e41cb7be6c52","LLEN":"c940fc2d15f59e41cb7be6c21"}' REMOTE_MONITORING: true interval: 15s labels: environment: production - name: nri-redis env: INVENTORY: true HOSTNAME: localhost PORT: 6379 RENAMED_COMMANDS: '{"CONFIG":"b840fc9f15f59e41cb7be6c52"}' REMOTE_MONITORING: true interval: 60s labels: environment: production inventory_source: config/redis ``` ```` **Multi-instance monitoring with keys filtering** Use this if you need to collect metrics from two different Redis servers using the the same integration. The first instance example is only collecting `KEY_1` amd `KEY_2` from Redis database 0. The second instance example shows how to collect from different databases with `{"DB":"KEYS"}`. ````yml integrations: - name: nri-redis env: METRICS: true HOSTNAME: redis_host_1 PORT: 6379 KEYS: '["KEY_1","KEY_2"]' REMOTE_MONITORING: true interval: 15s labels: environment: production - name: nri-redis env: METRICS: true HOSTNAME: redis_host_2 PORT: 6379 KEYS: '{"0":["KEY_1","KEY_2"],"1":["KEY_3"]}' REMOTE_MONITORING: true interval: 15s labels: environment: production ``` ```` ## Find and use data [#find-and-use] Data from this service is reported to an [integration dashboard](https://docs.newrelic.com/docs/integrations/new-relic-integrations/getting-started/infrastructure-integration-dashboards-charts). Metrics are attached to the `RedisSample` and `RedisKeyspaceSample` [event types](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#events-new-relic). You can [query this data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/query-new-relic-data) for troubleshooting purposes or to create custom charts and dashboards. For more on how to find and use your data, see [Understand integration data](https://docs.newrelic.com/docs/infrastructure/integrations/find-use-infrastructure-integration-data). ## Metric data [#metrics] The Redis integration collects the following metric data attributes: ### Redis sample metrics [#redissample-metrics] These attributes are attached to the `RedisSample` event type: | Name | Description | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cluster.connectedSlaves` | Number of connected slaves. | | `db.aofLastRewriteTimeInMilliseconds` | Duration of the last AOF rewrite operation in milliseconds. | | `db.aofLastBgrewriteStatus` | Boolean representing status of the last AOF background rewrite operation. | | `db.aofLastWriteStatus` | Boolean representing status of the last AOF write operation. | | `db.evictedKeysPerSecond` | Number of evicted keys due to maxmemory limit per second. | | `db.expiredKeysPerSecond` | Number of key expiration events per second. | | `db.keyspaceHitsPerSecond` | Number of successful lookups of keys in the main dictionary per second. | | `db.keyspaceMissesPerSecond` | Number of failed lookup of keys in the main dictionary per second. | | `db.latestForkUsecMilliseconds` | Duration of the latest fork operation in milliseconds. | | `db.rdbBgsaveInProgress` | Boolean. A flag indicating a RDB save is ongoing. | | `db.rdbChangesSinceLastSave` | Number of changes since the last dump. | | `db.rdbLastBgsaveStatus` | Boolean representing the status of the last RDB save operation. | | `db.rdbLastBgsaveTimeMilliseconds` | Duration of the last RDB save operation in milliseconds. | | `db.rdbLastSaveTime` | Epoch-based timestamp of last successful RDB save in seconds. | | `db.syncFull` | Count of the number times slaves have fully synchronized with this master. | | `db.syncPartialErr` | Count of the number of times partial syncs have failed to complete. | | `db.syncPartialOk` | Count of the number of times partial syncs have completed. | | `net.blockedClients` | Number of clients pending on a blocking call (`BLPOP`, `BRPOP`, `BRPOPLPUSH`). | | `net.clientBiggestInputBufBytes` | The biggest input buffer among current client connections. | | `net.clientLongestOutputList` | The longest output list among current client connections. | | `net.commandsProcessedPerSecond` | Number of commands processed by the server per second. | | `net.connectedClients` | Number of client connections (excluding connections from slaves). | | `net.connectionsReceivedPerSecond` | Number of connections accepted by the server per second. | | `net.inputBytesPerSecond` | Total number of bytes input per second. | | `net.outputBytesPerSecond` | Total number of bytes output per second. | | `net.pubsubChannels` | Global number of pub/sub channels with client subscriptions. | | `net.pubsubPatterns` | Global number of pub/sub pattern with client subscriptions. | | `net.rejectedConnectionsPerSecond` | Number of connections per second rejected because of maxclients limit. | | `software.uptimeMilliseconds` | Number of milliseconds since Redis server start. | | `system.memFragmentationRatio` | Ratio between `used_memory_rss` and `used_memory`. | | `system.totalSystemMemoryBytes` | The amount of memory in bytes available in the instance where Redis is running. | | `system.usedCpuSysMilliseconds` | System CPU consumed by the Redis server in milliseconds. | | `system.usedCpuSysChildrenMilliseconds` | System CPU consumed by the background processes in milliseconds. | | `system.usedCpuUserMilliseconds` | User CPU consumed by the Redis server in milliseconds. | | `system.usedCpuUserChildrenMilliseconds` | User CPU consumed by the background processes in milliseconds. | | `system.usedMemoryBytes` | The total number of bytes allocated by Redis using its allocator (either standard `libc`, `jemalloc`, or an alternative allocator such as `tcmalloc`). | | `system.usedMemoryLuaBytes` | Number of bytes used by the Lua engine. | | `system.usedMemoryPeakBytes` | The peak memory consumed by Redis in bytes. | | `system.usedMemoryRssBytes` | Number of bytes that Redis allocated as seen by the operating system (also known as resident set size). This is the number reported by tools such as `top(1)` and `ps(1)`. | ### Keyspace metrics The Redis integration collects the following keyspace metadata and metrics. These attributes are attached to the `RedisKeyspaceSample` event type: | Name | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `db.avgTtl` | The average time to live (TTL) in milliseconds of keys that have an expiration set in the database being reported on. | | `db.keys` | Number of keys in the database being reported on. | | `db.keyspace` | Redis database index, which is the integer number (usually a number between `0` and `15`). Format: `db` followed by the database index. For example: `db0`, `db1`, `db2`, etc. | | `db.expires` | Number of keys with an expiration in the database being reported on. | ## Inventory data [#inventory] Inventory data includes everything reported by the Redis [`CONFIG GET`](https://redis.io/commands/config-get) command, with the exception of `requirepass`, which stores the password to the Redis server. For more on inventory data, see [Understand inventory data](https://docs.newrelic.com/docs/infrastructure/integrations-getting-started/getting-started/understand-integration-data-data-types#inventory-data). ## Other system data [#metadata] The Redis integration collects these additional [attributes](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#attribute) about your Redis service: | Name | Description | | ------------------ | ------------------------------------------------------------------------------------ | | `software.version` | The version of the Redis server. Example: `3.2.3`. | | `cluster.role` | Either `master` or `slave,` depending on the role of the Redis node being monitored. | ## Check the source code [#source-code] This integration is open source software. That means you can [browse its source code](https://github.com/newrelic/nri-redis) and send improvements, or create your own fork and build it.