> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring Redis metrics with ClickHouse Observability

> Collect and visualize Redis metrics in ClickHouse Observability using an OpenTelemetry collector.

Collect Redis metrics with the OpenTelemetry Redis receiver and send them to ClickHouse Observability. Use the [demo dataset](#demo-dataset) to try the integration without installing Redis.

## Prerequisites

* A ClickHouse Observability service
* Docker to run the collector examples, or an existing OpenTelemetry Collector Contrib deployment
* For your own metrics, a Redis instance reachable from the collector and credentials if Redis requires authentication
* For the demo, `curl` to download and send the sample

### Connection details

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Open ClickHouse Observability and go to **Team Settings → Data → Managed Telemetry**. Copy your OTLP HTTP endpoint and API key. You can use **Copy connection details** to copy the configuration, or **Reveal key** to view the masked key.
>
> ![Managed Telemetry connection details](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-managed-telemetry.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=e63a2ac2e6ab996d3fc360ebe0f487a5)
>
> For the OTLP exporter examples below, set these variables in the terminal where you will run the collector:
>
> ```bash theme={null}
> export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
> export OTEL_EXPORTER_OTLP_AUTHORIZATION='Bearer YOUR_API_KEY'
> ```
>
> Replace the placeholders with the exact endpoint, including its port, and API key from your service. Use the base HTTP endpoint without a `/v1/metrics` suffix; the exporter appends the signal path.

> [tab] Self-managed
>
> Use your collector's reachable OTLP HTTP endpoint (for example, `http://YOUR_COLLECTOR_HOST:4318`) and authentication settings. If your collector does not require authentication, omit the exporter's `headers` block from the configurations below. See the [self-managed getting-started guide](https://clickhouse.com/docs/clickstack/self-configured/getting-started/managed.md) for setup guidance.
>
> ```bash theme={null}
> export OTEL_EXPORTER_OTLP_ENDPOINT='http://YOUR_COLLECTOR_HOST:4318'
> export OTEL_EXPORTER_OTLP_AUTHORIZATION='YOUR_INGESTION_KEY'
> ```

The endpoint must be reachable from the collector container. For a destination collector running on this computer, use `http://host.docker.internal:4318`. The Docker commands below include the host mapping.

## Integration with existing Redis

**1. Verify the Redis connection**

From a host with Redis CLI access, check your Redis instance:

```bash theme={null}
redis-cli -h YOUR_REDIS_HOST -p 6379 ping
redis-cli -h YOUR_REDIS_HOST -p 6379 INFO server
```

The first command should return `PONG`; the second should return server information. If Redis requires a password, set `REDISCLI_AUTH` in your terminal before running these commands. For Redis ACL users, also pass `--user YOUR_REDIS_USER`.

**2. Configure the collector**

Save this as `redis-metrics.yaml`:

```yaml theme={null}
receivers:
  redis:
    endpoint: ${env:REDIS_ENDPOINT}
    collection_interval: 10s
    # Uncomment if Redis requires authentication:
    # username: ${env:REDIS_USERNAME}
    # password: ${env:REDIS_PASSWORD}

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
    spike_limit_mib: 64
  resource/redis:
    attributes:
      - key: service.name
        value: redis-service
        action: upsert
  batch:
    timeout: 5s
    send_batch_size: 500
    send_batch_max_size: 500

exporters:
  otlp_http/observability:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      authorization: ${env:OTEL_EXPORTER_OTLP_AUTHORIZATION}

service:
  pipelines:
    metrics/redis:
      receivers: [redis]
      processors: [memory_limiter, resource/redis, batch]
      exporters: [otlp_http/observability]
```

The receiver collects Redis metrics every 10 seconds, including memory usage, clients, commands processed, keyspace hits and misses, and expired or evicted keys. The resource processor sets `service.name` to `redis-service` for filtering.

If Redis requires authentication, uncomment the appropriate receiver fields and set `REDIS_USERNAME` and/or `REDIS_PASSWORD`. These credentials connect to Redis; the OTLP authorization value authenticates with your destination collector. For TLS-enabled Redis, configure the receiver's `tls` settings as described in the [Redis receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.161.0/receiver/redisreceiver).

**3. Run the collector**

Set the [connection variables](#connection-details) and the Redis address reachable from the collector container. For Redis running on this computer:

```bash theme={null}
export REDIS_ENDPOINT='host.docker.internal:6379'
```

For remote Redis, use its hostname and port. For Redis in another container, use its container name and add `--network YOUR_NETWORK` to the command below.

From the directory containing `redis-metrics.yaml`, run:

```bash theme={null}
docker run --rm --name redis-metrics-collector \
  --add-host=host.docker.internal:host-gateway \
  --memory=512m \
  -e REDIS_ENDPOINT \
  -e REDIS_USERNAME \
  -e REDIS_PASSWORD \
  -e OTEL_EXPORTER_OTLP_ENDPOINT \
  -e OTEL_EXPORTER_OTLP_AUTHORIZATION \
  -v "$(pwd)/redis-metrics.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  otel/opentelemetry-collector-contrib:0.161.0 \
  --config=/etc/otelcol-contrib/config.yaml
```

Keep this terminal open while collecting metrics. Allow at least two collection intervals before checking the UI.

**4. Verify metrics**

Import the [dashboard](#dashboards), map its charts to your **Metrics** source, and filter for `ServiceName:redis-service`. Select **Last 15 minutes** and run the dashboard. Evictions and rejected connections can remain zero on a healthy Redis instance.

## Demo dataset

Try the integration with 6,912 gauge and sum data points sampled every five minutes across 24 hours. The sample preserves the original dataset's cache-warming, traffic-spike, and memory-pressure patterns. You need Docker, `curl`, and your destination collector's OTLP HTTP connection details.

Set the [connection variables](#connection-details) before starting.

**1. Download the sample metrics**

```bash theme={null}
curl -fLO https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-demo-5m.json
```

**2. Configure the demo collector**

Save this as `redis-metrics-demo.yaml`:

```yaml theme={null}
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
processors:
  resource/demo:
    attributes:
      - key: service.name
        value: redis-demo
        action: upsert
  transform/demo_timestamps:
    error_mode: propagate
    metric_statements:
      - context: datapoint
        statements:
          - set(cache["interval_ns"], time_unix_nano - start_time_unix_nano)
          - set(time, Now() - Duration("2m") - (Time("2025-10-21T04:59:30Z", "%Y-%m-%dT%H:%M:%SZ") - time))
          - set(start_time_unix_nano, time_unix_nano - cache["interval_ns"])
  batch:
    timeout: 5s
    send_batch_size: 500
    send_batch_max_size: 500
exporters:
  otlp_http/managed:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      authorization: ${env:OTEL_EXPORTER_OTLP_AUTHORIZATION}
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [resource/demo, transform/demo_timestamps, batch]
      exporters: [otlp_http/managed]
```

> [!NOTE]
>
> The demo-only transform refreshes timestamps while preserving metric values and the interval between each point's start and end timestamps. Omit it for live Redis metrics. The batch limit keeps uploads small enough for the destination collector.

**3. Run the demo collector**

From the directory containing the configuration, run the collector and leave this terminal open:

```bash theme={null}
docker run --rm --name redis-metrics-demo-collector \
  --add-host=host.docker.internal:host-gateway \
  --memory=512m \
  -p 127.0.0.1:14318:4318 \
  -e OTEL_EXPORTER_OTLP_ENDPOINT \
  -e OTEL_EXPORTER_OTLP_AUTHORIZATION \
  -v "$(pwd)/redis-metrics-demo.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  otel/opentelemetry-collector-contrib:0.161.0 \
  --config=/etc/otelcol-contrib/config.yaml
```

**4. Send the sample**

In another terminal, run this command from the download directory:

```bash theme={null}
curl --fail-with-body -sS http://localhost:14318/v1/metrics \
  -H 'Content-Type: application/json' \
  --data-binary @redis-metrics-demo-5m.json
```

A response such as `{}` or `{"partialSuccess":{}}` indicates the local collector accepted the request. Check the collector terminal for export errors and allow a few seconds for forwarding. Stop it with **Ctrl+C** after verifying the data. Sending the sample again can produce duplicate points.

**5. Verify the metrics**

Import the dashboard in the [next section](#dashboards), filter for `ServiceName:redis-demo`, and select **Last 2 days**. The sample includes both gauge and sum metrics; no direct database access is needed.

## Dashboards and visualization

**1. [Download the dashboard configuration](https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/examples/redis-metrics-dashboard.json)**

**2. Import the pre-built dashboard**

1. Open **Dashboards** in ClickHouse Observability.
2. Click **Import** in the upper-right corner.

![Import dashboard button](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-import-dashboard.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=16bcb7e6365ca0f6decac5c693e228eb)

3. Upload `redis-metrics-dashboard.json`, map the charts to your **Metrics** source, and click **Finish Import**.

**3. View the dashboard**

Filter for `ServiceName:redis-demo` and select **Last 2 days** for the demo, or filter for `ServiceName:redis-service` and select a time range covering your own Redis metrics.

![Redis Metrics dashboard](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-redis-metrics-dashboard.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=1c306ffee417bf7bff858aaf72bf5fe9)

## Troubleshooting

### Collector fails to start

Check the collector terminal for configuration errors. Confirm the YAML file is mounted at the documented path and the endpoint and required authentication variables are set in the terminal where you run Docker.

### No metrics appearing

* Check the collector output for Redis connection errors or OTLP export errors.
* Verify Redis is reachable from the collector container. For containers, check that they share the intended Docker network.
* Verify Redis credentials and that the user can run the commands required by the [Redis receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.161.0/receiver/redisreceiver).
* Check the **Metrics** source, service-name filter, and time range. For the demo, select **Last 2 days** and confirm the timestamp transform is included in the pipeline.
* For managed services, verify the OTLP HTTP endpoint and Bearer API key against **Managed Telemetry**. For self-managed collectors, use their authentication settings.

## Next steps

* Set up [alerts](https://clickhouse.com/docs/clickstack/observability/features/alerts.md) for memory usage, connection limits, or cache hit rate.
* Create additional [dashboards](https://clickhouse.com/docs/clickstack/observability/features/dashboards/overview.md).
* See [Sending OpenTelemetry data](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md) for more collector configuration guidance.