werkspot/redis_exporter repository overview

⁠Prometheus Redis Metrics Exporter

Prometheus exporter for Redis metrics.
Supports Redis 2.x, 3.x, 4.x, 5.x, and 6.x

⁠Building and running the exporter

⁠Build and run locally

git clone https://github.com/oliver006/redis_exporter.git
cd redis_exporter
go build .
./redis_exporter --version

⁠Pre-build binaries

For pre-built binaries please take a look at the releases⁠.

⁠Upgrading from 0.x to 1.x

PR #256⁠ introduced breaking changes which were released as version v1.0.0.

If you only scrape one Redis instance and use command line flags --redis.address and --redis.password then you're most probably not affected. Otherwise, please see PR #256⁠ and this README⁠ for more information.

⁠Basic Prometheus Configuration

Add a block to the scrape_configs of your prometheus.yml config file:

scrape_configs:
  - job_name: redis_exporter
    static_configs:
    - targets: ['<<REDIS-EXPORTER-HOSTNAME>>:9121']

and adjust the host name accordingly.

⁠Kubernetes SD configurations

To have instances in the drop-down as human readable names rather than IPs, it is suggested to use instance relabelling⁠.

For example, if the metrics are being scraped via the pod role, one could add:

          - source_labels: [__meta_kubernetes_pod_name]
            action: replace
            target_label: instance
            regex: (.*redis.*)

as a relabel config to the corresponding scrape config. As per the regex value, only pods with "redis" in their name will be relabelled as such.

Similar approaches can be taken with other role types⁠ depending on how scrape targets are retrieved.

⁠Prometheus Configuration to Scrape Multiple Redis Hosts

Run the exporter with the command line flag --redis.addr= so it won't try to access the local instance every time the /metrics endpoint is scraped.

scrape_configs:
  ## config for the multiple Redis targets that the exporter will scrape
  - job_name: 'redis_exporter_targets'
    static_configs:
      - targets:
        - redis://first-redis-host:6379
        - redis://second-redis-host:6379
        - redis://second-redis-host:6380
        - redis://second-redis-host:6381
    metrics_path: /scrape
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: <<REDIS-EXPORTER-HOSTNAME>>:9121

  ## config for scraping the exporter itself
  - job_name: 'redis_exporter'
    static_configs:
      - targets:
        - <<REDIS-EXPORTER-HOSTNAME>>:9121

The Redis instances are listed under targets, the Redis exporter hostname is configured via the last relabel_config rule.
If authentication is needed for the Redis instances then you can set the password via the --redis.password command line option of the exporter (this means you can currently only use one password across the instances you try to scrape this way. Use several exporters if this is a problem).
You can also use a json file to supply multiple targets by using file_sd_configs like so:

scrape_configs:
  - job_name: 'redis_exporter_targets'
    file_sd_configs:
      - files:
        - targets-redis-instances.json
    metrics_path: /scrape
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: <<REDIS-EXPORTER-HOSTNAME>>:9121

  ## config for scraping the exporter itself
  - job_name: 'redis_exporter'
    static_configs:
      - targets:
        - <<REDIS-EXPORTER-HOSTNAME>>:9121

The targets-redis-instances.json should look something like this:

[
  {
    "targets": [ "redis://redis-host-01:6379", "redis://redis-host-02:6379"],
    "labels": { }
  }
]

Prometheus uses file watches and all changes to the json file are applied immediately.

⁠Command line flags

Redis instance addresses can be tcp addresses: redis://localhost:6379, redis.example.com:6379 or e.g. unix sockets: unix:///tmp/redis.sock.
SSL is supported by using the rediss:// schema, for example: rediss://azure-ssl-enabled-host.redis.cache.windows.net:6380 (note that the port is required when connecting to a non-standard 6379 port, e.g. with Azure Redis instances).
Password-protected instances can be accessed by using the URI format including a password: redis://h:<<PASSWORD>>@<<HOSTNAME>>:<<PORT>>

Command line settings take precedence over any configurations provided by the environment variables.

⁠Run via Docker

The latest release is automatically published to the Docker registry⁠.

You can run it like this:

docker run -d --name redis_exporter -p 9121:9121 oliver006/redis_exporter

The latest docker image contains only the exporter binary. If, e.g. for debugging purposes, you need the exporter running in an image that has a shell, etc then you can run the alpine image:

docker run -d --name redis_exporter -p 9121:9121 oliver006/redis_exporter:alpine

If you try to access a Redis instance running on the host node, you'll need to add --network host so the redis_exporter container can access it:

docker run -d --name redis_exporter --network host oliver006/redis_exporter

⁠Run on Kubernetes

Here⁠ is an example Kubernetes deployment configuration for how to deploy the redis_exporter as a sidecar to a Redis instance.

⁠What's exported

Most items from the INFO command are exported, see Redis documentation⁠ for details.
In addition, for every database there are metrics for total keys, expiring keys and the average TTL for keys in the database.
You can also export values of keys if they're in numeric format by using the -check-keys flag. The exporter will also export the size (or, depending on the data type, the length) of the key. This can be used to export the number of elements in (sorted) sets, hashes, lists, streams, etc.

If you require custom metric collection, you can provide a Redis Lua script⁠ using the -script flag. An example can be found in the contrib folder⁠.

⁠The redis_memory_max_bytes metric

The metric redis_memory_max_bytes will show the maximum number of bytes Redis can use.
It is zero if no memory limit is set for the Redis instance you're scraping (this is the default setting for Redis).
You can confirm that's the case by checking if the metric redis_config_maxmemory is zero or by connecting to the Redis instance via redis-cli and running the command CONFIG GET MAXMEMORY.

⁠What it looks like

Example Grafana⁠ screenshots:

Grafana dashboard is available on grafana.com⁠ and/or github.com⁠.

⁠Viewing multiple Redis simultaneously

If running Redis Sentinel⁠, it may be desirable to view the metrics of the various cluster members simultaneously. For this reason the dashboard's drop down is of the multi-value type, allowing for the selection of multiple Redis. Please note that there is a caveat; the single stat panels up top namely uptime, total memory use and clients do not function upon viewing multiple Redis.

⁠Using the mixin

There is a set of sample rules, alerts and dashboards available in redis-mixin⁠

⁠Development

The tests require a variety of real Redis instances to not only verify correctness of the exporter but also compatibility with older versions of Redis and with Redis-like systems like KeyDB or Tile38.
The contrib/docker-compose-for-tests.yml⁠ file has service definitions for everything that's needed.
You can bring up the Redis test instances first by running make docker-env-up and then, every time you want to run the tests, you can run make docker-test. This will mount the current directory (with the .go source files) into a docker container and kick off the tests.
Once you're done testing you can bring down the stack by running make docker-env-down.
Or you can bring up the stack, run the tests, and then tear down the stack, all in one shot, by running make docker-all.

⁠Communal effort

Open an issue or PR if you have more suggestions, questions or ideas about what to add.