Introduction

Radar Collector collects Redis metrics from configured deployments and sends them to the Radar server via gRPC.

Supported Deployment Types

• Standalone Redis instances
• Redis Software clusters (REST API integration)
• Redis Cluster (OSS) with automatic node discovery
• Redis Sentinel

Features

• Monitor multiple Redis deployments from a single collector
• YAML configuration with environment variable interpolation (${VAR} and ${VAR:-default})
• Browser-based activation flow (connect command) for zero-config setup
• Remote-managed configuration: deployments can be managed from the Radar server
• Offline collection mode with configurable data redaction
• gRPC communication with API key authentication
• Per-deployment collection settings (interval, retries, timeout)
• Configuration validation and connection testing
• Signal handling for graceful shutdown (SIGINT, SIGTERM)
• Configurable logging levels with JSON output option

Quick Start

1. Install the radar-collector binary
2. Configure your Redis deployments
3. Validate your configuration
4. Run the radar-collector

Architecture

Single-binary design with:

• Configuration layer - YAML parsing with environment variable expansion
• Collection layer - Per-deployment type collectors
• gRPC layer - Communication with Radar server
• Redaction layer - Privacy controls for sensitive data

Installation

Download the radar-collector binary for your platform from the releases page.

Binary Installation

# Download binary (replace VERSION and PLATFORM)
curl -LO https://github.com/redis-field-engineering/radar-collector/releases/download/VERSION/radar-collector-PLATFORM

# Make executable
chmod +x radar-collector-PLATFORM
mv radar-collector-PLATFORM /usr/local/bin/radar-collector

# Verify installation
radar-collector --version

Docker

Pull the Docker image:

# Latest stable alpine image (recommended for Kubernetes and production)
docker pull ghcr.io/redis-field-engineering/radar-collector:alpine-latest

# Or pin to a specific version
docker pull ghcr.io/redis-field-engineering/radar-collector:alpine-v1.2.1

# Or latest (may use a different base image)
docker pull ghcr.io/redis-field-engineering/radar-collector:latest

Run with configuration file:

docker run -v /path/to/radar-collector.yml:/etc/radar/radar-collector.yml \
  ghcr.io/redis-field-engineering/radar-collector:alpine-latest

The default entrypoint runs radar-collector --config /etc/radar/radar-collector.yml, so you only need to mount the config file to the expected path.

Note: If your environment uses a corporate CA for TLS, mount the CA certificate bundle as well:

docker run \
  -v /path/to/radar-collector.yml:/etc/radar/radar-collector.yml \
  -v /path/to/ca-bundle.crt:/etc/ssl/certs/ca-certificates.crt:ro \
  ghcr.io/redis-field-engineering/radar-collector:alpine-latest

Next Steps

1. Configure your Redis deployments
2. Validate your configuration
3. Run the radar-collector

Configuration

Radar Collector uses a YAML configuration file. Default location is radar-collector.yml in the current directory. Use --config to specify a different file.

Basic Example

collector:
  id: radar-collector-001
  collection_interval: 60s

server:
  grpc_url: https://grpc.radar.redis.io:443  # Production Radar gRPC endpoint
  api_key: ${RADAR_API_KEY}

deployments:
  - id: redis-local
    name: Local Redis
    type: standalone
    redis_url: redis://localhost:6379

Configuration Sections

collector

Collector settings:

• id - Unique collector identifier (required)
• hostname - Hostname to report; defaults to system hostname
• collection_interval - How often to collect (default: 30s)
• health_report_interval - Health report interval (default: 60s)
• log_level - Optional log level override
• labels - Key-value labels (e.g., env: production)
• output_directory - Directory for offline collections (default: /var/radar/collections)
• redact - Enable/disable redaction globally for collected data (default: true)
• remote_config - Remote-managed configuration settings (see below)

remote_config

Controls whether the collector pulls deployment configuration from the Radar server:

• enabled - Enable remote config (default: true)
• mode - Config mode: managed or local (default: managed)
• managed_secrets - Whether remote config includes secrets (default: true)
• poll_interval - How often to poll for config changes (default: 30s)

server

Server connection:

• grpc_url - Radar server gRPC endpoint (required)
• api_key - Authentication key (required). Generate an API key from the Radar dashboard under Settings > Access Keys.
• timeout - Request timeout (default: 30s)

deployments

List of Redis databases/clusters to monitor. Each deployment needs:

• id - Unique identifier (required)
• name - Display name (required)
• type - Deployment type (required)
• collection - Optional per-deployment collection settings:
  • interval - Collection interval override (default: 30s)
  • retry_on_failure - Retry failed collections (default: true)
  • max_retries - Maximum retry attempts (default: 3)
  • timeout - Collection timeout (default: 30s)

Type-specific fields vary. See Deployment Types for details.

Environment Variables

The collector supports two types of environment variable usage:

1. YAML Interpolation (Recommended)

Use ${VAR} or ${VAR:-default} syntax directly in your YAML configuration file. These are expanded when the configuration file is loaded:

server:
  api_key: "${MY_API_KEY}"
  grpc_url: "${RADAR_SERVER:-https://grpc.radar.redis.io:443}"

deployments:
  - id: redis-prod
    name: Production Redis
    type: standalone
    redis_url: "redis://${REDIS_HOST}:${REDIS_PORT}"
    credentials:
      password: "${REDIS_PASSWORD}"

Syntax:

• ${VAR} - Required variable (fails if not set)
• ${VAR:-default} - Use default if VAR is unset or empty
• ${VAR-default} - Use default if VAR is unset (empty string is valid)

Important: Only ${VAR} (braced) syntax is expanded. Bare $VAR is NOT expanded, allowing literal $ characters in values (e.g., passwords like my$ecret).

When to use which:

• Use :- when empty values should fall back to default
• Use - when empty is a valid value (e.g., Redis with no password: ${REDIS_PASSWORD-})

2. Runtime Overrides

Environment variables can also override configuration values after the YAML is parsed. See Configuration Schema for the complete list of supported override variables.

Activation (connect)

Radar Collector supports browser-based activation via the connect subcommand. When no API key or stored credential is found, the collector can automatically start the activation flow. See Command Line Options for details.

Further Reading

• Deployment Types - Configure Standalone, Redis Software, Cluster, Sentinel
• Credentials & Security - Authentication and TLS
• Configuration Schema - Complete reference

Deployment Types

Radar Collector supports multiple Redis deployment types. Each type has specific configuration requirements.

Standalone Deployments

Monitor single Redis instances.

Configuration

deployments:
  - id: "cache-01"
    name: "cache-server"
    type: "standalone"
    redis_url: "redis://redis.example.com:6379"
    credentials:
      password: "${REDIS_PASSWORD}" # Optional

For TLS connections:

deployments:
  - id: "cache-tls-01"
    name: "cache-server-tls"
    type: "standalone"
    redis_url: "rediss://redis.example.com:6380" # rediss:// for TLS
    credentials:
      password: "${REDIS_PASSWORD}"

Environment Variables

# When only one standalone deployment exists
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_PASSWORD=mypassword

Data Collected

• Server info (version, uptime, memory)
• Configuration settings
• Client connections
• Replication status
• Persistence info (RDB/AOF)
• Performance metrics

Redis Software Deployments

Monitor Redis Software clusters via REST API.

Configuration

deployments:
  - id: "ent-prod"
    name: "production-enterprise"
    type: "enterprise"
    rest_api:
      host: "enterprise.example.com"
      port: 9443
      use_tls: true
      insecure: true # Default; set false to enforce certificate verification
      enterprise_admin_url: "https://enterprise.example.com:8443" # Optional management UI URL
    enterprise:
      db_endpoint: "external_ip" # Options: external_ip, internal_ip, dns (default: external_ip)
    credentials:
      rest_api:
        basic_auth: "admin@redis.local:${ENTERPRISE_PASSWORD}"

Fields Explained

rest_api section (top-level, required):

• host: REST API hostname or IP address
• port: REST API port (typically 9443)
• use_tls: Whether to use HTTPS (typically true for production)
• insecure: Set to true to skip certificate verification for self-signed certificates
• enterprise_admin_url: Optional management UI URL for accessing the Redis Software admin interface. This is used as a redirect URL in the Radar UI to allow users to navigate directly to the deployment’s management console. If not specified, the host and port URL will be used as a fallback.

enterprise section (top-level, optional):

• db_endpoint: How to report database endpoints - external_ip (default), internal_ip, or dns

credentials.rest_api (required):

• basic_auth: Authentication in username:password format (e.g., "admin@cluster.local:password123")

Note: enterprise_api is also accepted as an alias for rest_api in the credentials section for backward compatibility.

Environment Variables

# Override by deployment ID (uses uppercased ID with underscores)
export REDIS_ENTERPRISE_ENT_PROD_REST_API_URL=https://new-url:9443
export REDIS_ENTERPRISE_ENT_PROD_USERNAME=admin@redis.local
export REDIS_ENTERPRISE_ENT_PROD_PASSWORD=newpassword
export REDIS_ENTERPRISE_ENT_PROD_SSL_NO_VERIFY=true

Data Collected

• Cluster topology and nodes
• Database configurations
• License information
• Memory and storage metrics
• Replication status
• Module information

Cluster Deployments

Monitor Redis OSS clusters with automatic node discovery.

Configuration

deployments:
  - id: "cluster-01"
    name: "main-cluster"
    type: "cluster"
    redis_urls:
      - "cluster1.example.com:7000"
      - "cluster2.example.com:7000"
      - "cluster3.example.com:7000"
    credentials:
      password: "${CLUSTER_PASSWORD}" # Optional

Note: The collector automatically discovers all cluster nodes from the seed nodes specified in redis_urls.

Discovery

• Connects to seed nodes
• Runs CLUSTER NODES to discover topology
• Collects from all discovered nodes
• Handles node failures gracefully

Data Collected

• Full cluster topology
• Slot distribution
• Node roles (master/replica)
• Node health status
• Per-node metrics (memory, clients, ops)
• Cluster-wide statistics

Sentinel Deployments

Monitor Redis high-availability setups with Sentinel.

Configuration

deployments:
  - id: "sentinel-01"
    name: "ha-redis"
    type: "sentinel"
    master_name: "mymaster"
    sentinel_urls:
      - "sentinel1.example.com:26379"
      - "sentinel2.example.com:26379"
      - "sentinel3.example.com:26379"
    credentials:
      password: "${REDIS_PASSWORD}" # Redis instance password

Note: A sentinel_password field (for authenticating to the Sentinel instances themselves, separate from the Redis password) is not currently supported. If your Sentinels require authentication, contact the Radar team for guidance.

Discovery

• Connects to Sentinels
• Discovers monitored masters
• Finds replicas for each master
• Handles Sentinel failures with fallback

Data Collected

• Sentinel instances and status
• Monitored masters
• Replica information
• Failover history
• Quorum configuration
• Master/replica Redis metrics

Multiple Deployments

Monitor multiple deployments of different types:

collector:
  id: radar-collector-001

server:
  grpc_url: https://grpc.radar.redis.io:443 # Production Radar gRPC endpoint
  api_key: ${RADAR_API_KEY}

deployments:
  # Software cluster
  - id: ent-01
    name: enterprise-prod
    type: enterprise
    rest_api:
      host: enterprise.local
      port: 9443
      use_tls: true
      insecure: true # For self-signed certs
    enterprise:
      db_endpoint: external_ip
    credentials:
      rest_api:
        basic_auth: "admin@redis.local:${ENT_PASSWORD}"

  # Standalone cache
  - id: cache-01
    name: session-cache
    type: standalone
    redis_url: redis://cache.local:6379
    credentials:
      password: ${CACHE_PASSWORD}

  # Redis Cluster
  - id: cluster-01
    name: data-cluster
    type: cluster
    redis_urls:
      - node1.local:7000
      - node2.local:7000
      - node3.local:7000
    credentials:
      password: ${CLUSTER_PASSWORD}

  # Sentinel HA
  - id: sentinel-01
    name: ha-redis
    type: sentinel
    master_name: mymaster
    sentinel_urls:
      - sentinel1.local:26379
      - sentinel2.local:26379
    credentials:
      password: ${REDIS_PASSWORD}

Collection Behavior

All deployments are collected concurrently. Individual deployment failures don’t stop other collections. Failed collections are retried with exponential backoff (default: 3 attempts).

Validation

# Validate all deployments
radar-collector --validate

# Validate specific deployment connectivity
radar-collector validate --deployment enterprise-prod

# Test collection from a specific deployment
radar-collector test --deployment session-cache

Credentials & Security

Configure Redis credentials to allow Radar Collector to collect monitoring data. The collector supports various authentication methods depending on the deployment type.

Deployment-Specific Credentials

• Redis Standalone - Password auth, default ACL user, TLS/SSL
• Redis Software - REST API basic auth, Data ACL setup

For Redis Cluster deployments, authentication is configured via credentials.password and optional credentials.username. If credentials.username is omitted, the collector authenticates as the default ACL user.

For Redis Sentinel deployments, authentication is configured via the credentials.password field in the deployment configuration. See Deployment Types for examples.

General Security Recommendations

1. Use dedicated monitoring credentials - Don’t reuse admin credentials for collection
2. Apply least privilege - Only grant the permissions the collector needs
3. Use environment variables for secrets - Never hardcode credentials in config files
4. Enable TLS where supported - Use rediss:// URLs for encrypted Redis connections
5. Rotate credentials regularly - Update passwords and API keys on a schedule

Redis Standalone Credentials

For standalone Redis instances, the collector uses redis_url only for the host, port, and TLS scheme. Authentication comes from credentials.password or the REDIS_PASSWORD environment variable.

Standalone deployments do not currently support configuring a Redis ACL username. When a password is provided, the collector authenticates as the default ACL user.

Method 1: credentials.password

Use the credentials section to configure authentication:

deployments:
  - id: "redis-prod"
    name: "Production Redis"
    type: "standalone"
    redis_url: "redis://localhost:6379"
    credentials:
      password: "${REDIS_PASSWORD}"

Method 2: REDIS_PASSWORD Environment Variable

If credentials.password is omitted, the collector falls back to REDIS_PASSWORD:

deployments:
  - id: "redis-prod"
    name: "Production Redis"
    type: "standalone"
    redis_url: "redis://localhost:6379"

export REDIS_PASSWORD="your-secure-password"

Method 3: TLS Endpoint Configuration

Use rediss:// in redis_url for secure connections and keep the password in credentials.password:

deployments:
  - id: "redis-tls"
    name: "Redis with TLS"
    type: "standalone"
    redis_url: "rediss://localhost:6380"
    credentials:
      password: "${REDIS_PASSWORD}"

Redis ACL Limitations

Standalone deployments currently authenticate as the default ACL user only. If your Redis instance requires a non-default ACL username, standalone monitoring is not supported yet.

Default User Permissions

For Redis instances with ACL support (Redis 6+), grant the default user the minimum commands required by the collector:

# Connect to Redis
redis-cli

# Configure the default user with the required permissions
ACL SETUSER default on >${SECURE_PASSWORD} \
  +info +ping +config|get +client|list +memory|usage +latency \
  +@read ~* &*

# Verify the user
ACL LIST

Or without a password (not recommended for production):

ACL SETUSER default on nopass \
  +info +ping +config|get +client|list +memory|usage +latency \
  +@read ~* &*

Required Permissions

The default ACL user needs these Redis permissions:

Minimal ACL Rule

For the most restrictive setup:

ACL SETUSER default on >${PASSWORD} \
  +info +ping +config|get +client|list +memory|usage +latency \
  +@read ~* &*

TLS/SSL Configuration

For secure connections, use rediss:// URLs:

deployments:
  - id: "redis-tls"
    name: "Redis with TLS"
    type: "standalone"
    redis_url: "rediss://localhost:6380"
    credentials:
      password: "${REDIS_PASSWORD}"

Environment Variables

Store sensitive information in environment variables:

# Set environment variables
export REDIS_PASSWORD="your-secure-password"
export REDIS_HOST="redis.example.com"
export REDIS_PORT="6379"

Reference them in configuration:

deployments:
  - id: "redis-prod"
    name: "Production Redis"
    type: "standalone"
    redis_url: "redis://${REDIS_HOST}:${REDIS_PORT}"
    credentials:
      password: "${REDIS_PASSWORD}"

  - id: "redis-replica"
    name: "Redis Replica"
    type: "standalone"
    redis_url: "redis://${REDIS_HOST_REPLICA}:6379"
    credentials:
      password: "${REDIS_REPLICA_PASSWORD}"

Testing Credentials

Validate your credentials using the validation command:

# Validate all deployments
radar-collector --validate

# Validate specific deployment connectivity
radar-collector validate --deployment redis-prod

# Test collection from a specific deployment
radar-collector test --deployment redis-prod

Security Best Practices

1. Avoid admin credentials - Use a dedicated password with least-privilege ACLs on the default user
2. Apply least privilege - Only grant necessary permissions
3. Use environment variables - Don’t hardcode credentials in config files
4. Enable TLS - Use rediss:// URLs for encrypted connections
5. Rotate credentials - Regularly update passwords and API keys
6. Monitor access - Review Redis logs for authentication events

Redis Software Credentials

Redis Software deployments use REST API basic authentication:

deployments:
  - id: "ent-01"
    name: "production-enterprise"
    type: "enterprise"
    rest_api:
      host: "enterprise.example.com"
      port: 9443
      use_tls: true
      insecure: true # Default; set false to enforce certificate verification
      enterprise_admin_url: "https://enterprise.example.com:8443" # Optional management UI redirect URL
    credentials:
      rest_api:
        basic_auth: "admin@cluster.local:${ENTERPRISE_PASSWORD}"

Key points:

• Authentication uses username:password format in the basic_auth field
• Typically uses admin-level credentials for cluster API access
• Defaults to insecure: true for Enterprise REST API connections; set insecure: false to enforce certificate verification
• Uses port 9443 for REST API access
• enterprise_admin_url is optional and provides a redirect URL to the management UI

Software data access: create Data ACL, Role, and User

You can grant the collector read-only access in Redis Software using either the REST API or the Admin UI.

Option A — REST API

1. Create a Redis ACL (Data ACL)

curl -X POST "https://<your-cluster-host>:9443/v1/redis_acls" \
  -H "Content-Type: application/json" \
  -u "<admin-user>:<admin-password>" \
  -d '{
    "name": "radar-collector-acl",
    "acl": "+@read +info +ping +config|get +client|list +memory +latency"
  }'

• Save the uid from the response (call it ACL_UID).

2. Create a Role and then assign the ACL to each database you want monitored

# Create role
curl -X POST "https://<your-cluster-host>:9443/v1/roles" \
  -H "Content-Type: application/json" \
  -u "<admin-user>:<admin-password>" \
  -d '{
    "name": "radar-collector-role",
    "management": "cluster_member"
  }'

# Save the role uid from the response (ROLE_UID), then for each database:
# Replace <BDB_ID> with the database id/uid on your cluster
curl -X PUT "https://<your-cluster-host>:9443/v1/bdbs/<BDB_ID>" \
  -H "Content-Type: application/json" \
  -u "<admin-user>:<admin-password>" \
  -d '{
    "roles_permissions": [
      { "role_uid": ROLE_UID, "redis_acl_uid": ACL_UID }
    ]
  }'

3. Create the collector user and assign the role

curl -X POST "https://<your-cluster-host>:9443/v1/users" \
  -H "Content-Type: application/json" \
  -u "<admin-user>:<admin-password>" \
  -d '{
    "email": "radar-collector@cluster.local",
    "password": "<secure-password>",
    "name": "radar-collector",
    "role_uids": [ ROLE_UID ]
  }'

Option B — Admin UI

1. Create a new Redis ACL

• Navigate: Access Control → Roles → Data ACLs → Add Redis ACL
• Name: radar-collector-acl
• ACL Rule: +@read +info +ping +config|get +client|list +memory +latency

2. Create a role and assign the ACL to databases

• Navigate: Access Control → Roles → Create Role
• Name: radar-collector-role
• Management: cluster_member
• For each database to monitor: Database → Configuration → Security → Assign radar-collector-acl to radar-collector-role

3. Create a user and give it the role

• Navigate: Access Control → Users → Add User
• Email: radar-collector@cluster.local
• Password: <secure-password>
• Name: radar-collector
• Assign role: radar-collector-role

Using the created credentials

Use the created user credentials for Radar Software collection:

# REST API basic auth in your collector configuration
credentials:
  rest_api:
    basic_auth: "radar-collector@cluster.local:<secure-password>"

Notes:

• The Data ACL grants read-only access used by the collector to collect metrics.
• Apply the role+ACL to every database you want the collector to monitor.
• For clusters with self-signed certs, set use_tls: true and insecure: true in the Software rest_api config.

Running the Collector

The radar-collector supports multiple operational modes:

First-Run Activation

When the collector starts with the default config path (radar-collector.yml) and that file does not exist, it automatically enters a browser-based activation flow (unless a stored credential already exists from a previous activation). This connects the collector to your Radar account without manual configuration.

# First run - auto-activates if default config file is missing and no stored credential
./radar-collector

# Explicit activation
./radar-collector connect

# Activation without browser (prints URL to terminal)
./radar-collector connect --no-browser

After activation, the collector stores its credential locally and begins collecting. On subsequent runs, the stored credential is reused automatically.

Continuous Mode (Production)

Standard production mode - continuously collects metrics and submits to server.

# Default configuration file (radar-collector.yml)
./radar-collector

# Custom configuration
./radar-collector --config /etc/radar/production.yml

# With debug logging
RUST_LOG=debug ./radar-collector

Behavior:

• Collects from all configured deployments at specified intervals
• Automatically submits data to Radar server via gRPC
• Runs continuously until stopped with SIGTERM/SIGINT
• Gracefully completes current collection before shutdown
• If remote config is enabled (default), deployments can be managed from the Radar server

Use when:

• Running in production environments
• Deployed as systemd service or Kubernetes pod
• Continuous monitoring is required

Offline Mode

Collect data to local files for manual inspection before submission.

Collect to File

# Auto-generated filename (includes hostname, version, timestamp)
./radar-collector --once --output-file
# Creates: radar-collection-hostname-v0.1.0-20251014-120000.json

# Custom path
./radar-collector --once --output-file /var/lib/radar/collection.json

Redaction

Redaction is controlled by collector.redact in your config file (default: true).

When enabled, the collector redacts:

• Passwords and API keys (***REDACTED***)
• Hostnames (deterministic hashing)
• IP addresses (192.xxx.xxx.xxx)
• Port numbers (masked as numeric 0)

To disable, set in your config:

collector:
  redact: false

When disabled, data is written/submitted as collected.

Submit Collected Data

# Submit previously collected file
./radar-collector submit --file radar-collection-hostname-v0.1.0-20251014-120000.json

# With custom server config
./radar-collector --config production.yml submit --file collection.json

Use when:

• Air-gapped environments requiring manual file transfer
• Security reviews needed before cloud submission
• Compliance workflows require approval process
• Local debugging and analysis

Test Mode

Test single deployment without affecting production monitoring.

# Collect and submit once
./radar-collector test --deployment redis-prod

# Collect without submitting (dry run)
./radar-collector test --deployment redis-prod --dry-run

# With debug output
RUST_LOG=debug ./radar-collector test --deployment software-cluster

Behavior:

• Collects from specified deployment once
• Shows collected data (in dry-run mode)
• Exits after single collection
• Does not affect other deployments

Use when:

• Testing new deployment configuration
• Verifying connectivity before production
• Debugging collection issues
• Validating data format

Validation Mode

Validate configuration and test connectivity without collecting data.

# Validate all deployments
./radar-collector --validate

# Validate specific deployment
./radar-collector validate --deployment redis-prod

Use when:

• First-time configuration setup
• Troubleshooting connection issues
• Verifying credentials
• Pre-deployment checks

Additional Options

Logging Levels

Control log verbosity with RUST_LOG:

# Info (default) - standard operational messages
RUST_LOG=info ./radar-collector

# Debug - detailed operational information
RUST_LOG=debug ./radar-collector

# Trace - very verbose, includes all data
RUST_LOG=trace ./radar-collector

Graceful Shutdown

The radar-collector handles SIGTERM and SIGINT signals gracefully:

1. Receives shutdown signal
2. Stops scheduling new collections
3. Completes current collection in progress
4. Exits cleanly

# Send graceful shutdown signal
kill -TERM <pid>

# Or use Ctrl+C
^C

Running in Production

For production deployments, see:

• Linux Deployment - Systemd service setup
• Kubernetes Deployment - Container orchestration

Validation & Testing

Validate Configuration

# Check configuration syntax and list all deployments
./radar-collector --validate

# Validate and test connectivity for a specific deployment
./radar-collector validate --deployment redis-prod

Test Collection

# Test collection from a specific deployment (collects once and exits)
./radar-collector test --deployment redis-prod

# Debug output
RUST_LOG=debug ./radar-collector test --deployment redis-prod

# Dry run - collect from all deployments without submitting
./radar-collector --dry-run --once

Recommended Workflow

1. Validate configuration

   ./radar-collector --validate
   

2. Test a single deployment

   ./radar-collector test --deployment redis-prod
   

3. Dry run (collect from all without submitting)

   ./radar-collector --dry-run --once
   

4. Run radar-collector

   ./radar-collector
   

Deployment

Deploy Radar Collector as a systemd service or in Kubernetes.

Deployment Methods

• Linux Deployment - Systemd service
• Kubernetes Deployment - Container orchestration

Network Requirements

• Access to Radar server gRPC endpoint
• Access to all monitored Redis instances
• DNS resolution for hostnames

Security

• Store API keys in environment variables or secrets
• Use dedicated Redis monitoring users with minimal permissions
• Run radar-collector as non-root user

Resource Usage

• CPU: ~0.1 core per 10 deployments
• Memory: ~50MB base + ~10MB per deployment
• Network: Minimal (<1KB per collection)

Linux Deployment

Deploy Radar Collector as a systemd service.

Installation

1. Create User and Directories

sudo useradd --system --no-create-home --shell /usr/sbin/nologin radar-collector
sudo mkdir -p /opt/radar-collector /etc/radar-collector
sudo chown radar-collector:radar-collector /opt/radar-collector

2. Install Binary

sudo cp target/release/radar-collector /opt/radar-collector/
sudo chmod +x /opt/radar-collector/radar-collector
sudo chown radar-collector:radar-collector /opt/radar-collector/radar-collector

3. Create Configuration

sudo vi /etc/radar-collector/config.yml

collector:
  id: radar-collector-001

server:
  grpc_url: ${RADAR_SERVER_URL}
  api_key: ${RADAR_API_KEY}

deployments:
  - id: redis-prod
    name: Production Redis
    type: standalone
    redis_url: ${REDIS_URL}

4. Create Environment File

sudo vi /etc/radar-collector/environment

RADAR_SERVER_URL=http://localhost:50051
RADAR_API_KEY=your-api-key
REDIS_URL=redis://localhost:6379
RUST_LOG=info

Set permissions:

sudo chmod 600 /etc/radar-collector/environment
sudo chmod 640 /etc/radar-collector/config.yml

5. Create Systemd Service

sudo vi /etc/systemd/system/radar-collector.service

[Unit]
Description=Radar Collector
After=network.target

[Service]
Type=simple
User=radar-collector
Group=radar-collector
WorkingDirectory=/opt/radar-collector
ExecStart=/opt/radar-collector/radar-collector --config /etc/radar-collector/config.yml
Restart=always
RestartSec=10
EnvironmentFile=/etc/radar-collector/environment
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

6. Start Service

sudo systemctl daemon-reload
sudo systemctl enable radar-collector
sudo systemctl start radar-collector
sudo systemctl status radar-collector

Service Management

# View logs
sudo journalctl -u radar-collector -f

# Restart after config changes
sudo systemctl restart radar-collector

# Stop service
sudo systemctl stop radar-collector

Kubernetes Deployment

Deploy Radar Collector in Kubernetes using Deployments, ConfigMaps, and Secrets for scalable monitoring.

Prerequisites

• Kubernetes cluster (1.19+)
• kubectl configured to access your cluster
• Container image of Radar Collector

Container Image

The Radar Collector is published to GHCR:

# Pull the latest stable alpine image (recommended)
docker pull ghcr.io/redis-field-engineering/radar-collector:alpine-latest

# Or pin to a specific version (recommended for production)
docker pull ghcr.io/redis-field-engineering/radar-collector:alpine-v1.2.1

The default entrypoint and command in the published image are:

ENTRYPOINT ["/usr/local/bin/radar-collector"]
CMD ["--config", "/etc/radar/radar-collector.yml"]

Quick Start

1. Create Namespace

# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: radar-collector
  labels:
    name: radar-collector

kubectl apply -f namespace.yaml

2. Create Secrets

Store sensitive configuration in Kubernetes Secrets.

Obtaining an API key: Log in to the Radar dashboard and navigate to Settings > Access Keys to generate a new key.

# secrets.yaml
apiVersion: v1
kind: Secret
metadata:
  name: radar-collector-secrets
  namespace: radar-collector
type: Opaque
stringData:
  api-key: "your-radar-api-key"
  enterprise-basic-auth: "admin@cluster.local:enterprise-password"

For Redis Software, enterprise-basic-auth must be a single username:password value because the collector uses it for REST API basic auth. For direct Redis connections such as standalone or cluster, store only the Redis password in the Secret, for example redis-password: "your-redis-password", and reference that from ${REDIS_STANDALONE_PASSWORD} or ${REDIS_CLUSTER_PASSWORD}. If you use Redis ACLs, keep the username as a separate field in the collector config.

Create radar-collector-secrets in the same namespace as the collector Deployment. This repository does not include a committed staging copy of that Secret, so if your collector runs in staging, create the Secret in staging and update the manifest namespace accordingly.

kubectl apply -f secrets.yaml

3. Create ConfigMap

Store the collector configuration:

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: radar-collector-config
  namespace: radar-collector
data:
  radar-collector.yml: |
    collector:
      id: "radar-collector-k8s-${HOSTNAME}"
      hostname: "${HOSTNAME}"
      collection_interval: "30s"
      remote_config:
        enabled: false

    server:
      grpc_url: "https://grpc.radar.redis.io:443"
      api_key: "${RADAR_API_KEY}"

    deployments:
      - id: "redis-enterprise"
        name: "Redis Software Production"
        type: "enterprise"
        rest_api:
          host: "cluster.redis.local"
          port: 9443
          use_tls: true
          insecure: true
          enterprise_admin_url: "https://cluster.redis.local:8443"
        enterprise:
          db_endpoint: external_ip
        credentials:
          rest_api:
            basic_auth: "${ENTERPRISE_BASIC_AUTH}"

kubectl apply -f configmap.yaml

4. Create Deployment

Deploy the Radar Collector:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: radar-collector
  namespace: radar-collector
  labels:
    app: radar-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: radar-collector
  template:
    metadata:
      labels:
        app: radar-collector
    spec:
      serviceAccountName: radar-collector
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: radar-collector
          image: ghcr.io/redis-field-engineering/radar-collector:alpine-latest
          imagePullPolicy: Always

          env:
            - name: HOSTNAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: RADAR_API_KEY
              valueFrom:
                secretKeyRef:
                  name: radar-collector-secrets
                  key: api-key
            - name: ENTERPRISE_BASIC_AUTH
              valueFrom:
                secretKeyRef:
                  name: radar-collector-secrets
                  key: enterprise-basic-auth
            - name: RUST_LOG
              value: "info"

          volumeMounts:
            - name: config
              mountPath: /etc/radar
              readOnly: true

          resources:
            requests:
              memory: "64Mi"
              cpu: "50m"
            limits:
              memory: "128Mi"
              cpu: "200m"

          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL

      volumes:
        - name: config
          configMap:
            name: radar-collector-config

      restartPolicy: Always
      nodeSelector:
        kubernetes.io/os: linux

5. Create ServiceAccount and RBAC

Create service account with minimal permissions:

# rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: radar-collector
  namespace: radar-collector

---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: radar-collector
  namespace: radar-collector
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["get", "list"]

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: radar-collector
  namespace: radar-collector
subjects:
  - kind: ServiceAccount
    name: radar-collector
    namespace: radar-collector
roleRef:
  kind: Role
  name: radar-collector
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f rbac.yaml
kubectl apply -f deployment.yaml

Deployment Type Reference

The examples above use Redis Software by default. If you are collecting from a different deployment type, replace the deployments entry in radar-collector.yml and update the referenced secret/env var names to match.

Redis Software (type: enterprise)

The collector connects to the Redis Software REST API to discover all databases in the cluster. It does not connect directly to individual Redis instances for collection.

- id: "redis-enterprise"
  name: "Redis Software Production"
  type: "enterprise"
  rest_api:
    host: "cluster.redis.local"     # REST API hostname
    port: 9443                       # REST API port (typically 9443)
    use_tls: true                    # Use HTTPS (recommended for production)
    insecure: true                   # Skip cert verification (for self-signed certs)
    enterprise_admin_url: "https://cluster.redis.local:8443"  # Optional management UI link
  enterprise:
    db_endpoint: external_ip         # How to report DB endpoints: external_ip, internal_ip, or dns
  credentials:
    rest_api:
      basic_auth: "${ENTERPRISE_BASIC_AUTH}"  # "username:password" format

Network requirements: The collector pod needs egress to the REST API host on port 9443 (HTTPS).

Secret value: enterprise-basic-auth: "username:password"

Standalone (type: standalone)

Connects directly to a single Redis instance. Use rediss:// for TLS.

- id: "redis-cache"
  name: "Session Cache"
  type: "standalone"
  redis_url: "redis://redis-cache.svc.cluster.local:6379"
  credentials:
    password: "${REDIS_STANDALONE_PASSWORD}"

Network requirements: Egress to the Redis host on port 6379 (or 6380 for TLS).

Secret value: redis-password: "your-redis-password"

Cluster (type: cluster)

Provide seed nodes. The collector runs CLUSTER NODES to automatically discover the full topology, then collects from every node.

- id: "redis-cluster"
  name: "Data Cluster"
  type: "cluster"
  redis_urls:
    - "redis-node-0.svc.cluster.local:7000"
    - "redis-node-1.svc.cluster.local:7000"
    - "redis-node-2.svc.cluster.local:7000"
  credentials:
    username: "radar-agent"           # Optional ACL username
    password: "${REDIS_CLUSTER_PASSWORD}"

Network requirements: Egress to every cluster node on the Redis port. Since the collector discovers nodes dynamically, ensure network policies allow traffic to all nodes in the cluster, not just the seed nodes.

Secret value: redis-cluster-password: "your-redis-password" with optional username in the collector config when ACLs are enabled.

Advanced Configuration

Multi-Environment Setup

Deploy different collectors for different environments:

# production-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: radar-collector-production
  namespace: radar-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: radar-collector
      environment: production
  template:
    metadata:
      labels:
        app: radar-collector
        environment: production
    spec:
      containers:
        - name: radar-collector
          image: ghcr.io/redis-field-engineering/radar-collector:alpine-latest
          env:
            - name: ENVIRONMENT
              value: "production"
          volumeMounts:
            - name: config
              mountPath: /etc/radar
      volumes:
        - name: config
          configMap:
            name: radar-collector-config-production

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: radar-collector-staging
  namespace: radar-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: radar-collector
      environment: staging
  template:
    metadata:
      labels:
        app: radar-collector
        environment: staging
    spec:
      containers:
        - name: radar-collector
          image: ghcr.io/redis-field-engineering/radar-collector:alpine-latest
          env:
            - name: ENVIRONMENT
              value: "staging"
          volumeMounts:
            - name: config
              mountPath: /etc/radar
      volumes:
        - name: config
          configMap:
            name: radar-collector-config-staging

Network Policies

Restrict network access:

# network-policy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: radar-collector-netpol
  namespace: radar-collector
spec:
  podSelector:
    matchLabels:
      app: radar-collector
  policyTypes:
    - Egress
  egress:
    # Allow DNS resolution
    - to: []
      ports:
        - protocol: UDP
          port: 53
    # Allow HTTPS/gRPC to Radar server
    - to: []
      ports:
        - protocol: TCP
          port: 443
    # Allow Redis Software REST API
    - to: []
      ports:
        - protocol: TCP
          port: 9443

If you switch the collector to type: standalone, allow egress to the Redis host on 6379 or 6380. If you switch to type: cluster, allow egress to the seed nodes and all discovered cluster nodes, commonly on port 7000.

TLS and Corporate CA Certificates

If your environment uses a corporate proxy or private CA, the collector’s TLS library cannot verify the Radar gRPC server certificate by default. Mount a complete CA bundle into the container to resolve this.

Mount CA Bundle

Add the CA bundle as a ConfigMap or Secret and mount it into the container:

apiVersion: v1
kind: ConfigMap
metadata:
  name: corporate-ca
  namespace: radar-collector
data:
  ca-bundle.crt: |
    -----BEGIN CERTIFICATE-----
    ... system and corporate CA certificates ...
    -----END CERTIFICATE-----

Then add the volume and mount to your Deployment:

spec:
  containers:
    - name: radar-collector
      image: ghcr.io/redis-field-engineering/radar-collector:alpine-latest
      volumeMounts:
        - name: config
          mountPath: /etc/radar
          readOnly: true
        - name: ca-cert
          mountPath: /etc/radar/certs/ca-bundle.crt
          subPath: ca-bundle.crt
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: radar-collector-config
    - name: ca-cert
      configMap:
        name: corporate-ca

Important: Do not mount a single corporate CA certificate over /etc/ssl/certs/ca-certificates.crt unless that file is a complete CA bundle. Replacing the system bundle with a single certificate can break TLS verification for endpoints that rely on public CAs.

Using SSL_CERT_FILE

Set SSL_CERT_FILE only when it points to a complete CA bundle:

env:
  - name: SSL_CERT_FILE
    value: "/etc/radar/certs/ca-bundle.crt"

Management and Operations

View Logs

kubectl logs -n radar-collector -l app=radar-collector -f
kubectl logs -n radar-collector <pod-name> -f
kubectl logs -n radar-collector <pod-name> --previous

Update Configuration

kubectl apply -f configmap.yaml
kubectl rollout restart deployment/radar-collector -n radar-collector
kubectl rollout status deployment/radar-collector -n radar-collector

Troubleshooting

Common Issues

Pod won’t start:

kubectl get pods -n radar-collector
kubectl describe pod <pod-name> -n radar-collector
kubectl logs <pod-name> -n radar-collector

Configuration issues:

kubectl get configmap radar-collector-config -n radar-collector -o yaml
kubectl exec -it <pod-name> -n radar-collector -- radar-collector --validate --config /etc/radar/radar-collector.yml

Health Checks

kubectl get deployment radar-collector -n radar-collector
kubectl get pods -n radar-collector -l app=radar-collector
kubectl get events -n radar-collector --sort-by='.lastTimestamp'

Troubleshooting

Diagnosis Steps

1. Validate configuration: radar-collector --validate
2. Enable debug logging: RUST_LOG=debug radar-collector
3. Test connectivity with curl/redis-cli
4. Check error messages for diagnostic hints

Common Issues

Redis Software REST API Connection Failed

Symptoms:

Error: failed to connect to localhost:9443

Solutions:

1. Use actual hostname, not “localhost”

   rest_api:
     host: "enterprise.example.com"
     port: 9443
     use_tls: true
   

2. Verify port 9443 (REST API), not 8443 (Admin UI)

3. For self-signed certificates:

   rest_api:
     host: "enterprise.example.com"
     port: 9443
     use_tls: true
     insecure: true  # Skip certificate validation (default: true)
   

Test connectivity:

curl -k -u admin@redis.local:password https://enterprise.example.com:9443/v1/cluster

Authentication Failed

Symptoms:

Error: Missing access token
Error: gRPC error: Unauthenticated

Solution:

Set API key via environment variable or config:

export ACCESS_KEY=your-api-key

Or in config:

server:
  api_key: your-api-key

Configuration Validation Failed

Symptoms:

Error: missing field `type`

Solution:

Check YAML syntax and required fields:

# Validate configuration
radar-collector --validate

# Test specific deployment
radar-collector validate --deployment redis-prod

gRPC Transport Error on Submission

Symptoms:

Error: transport error
Error: error trying to connect: ...

The collector connects to Redis and collects data successfully, but fails when submitting to the Radar server via gRPC.

Cause: The Radar gRPC endpoint uses TLS. If your environment uses a corporate proxy or private CA, the collector’s TLS library cannot verify the server certificate.

Solutions:

1. Kubernetes: Mount the corporate CA certificate into the container. See Kubernetes Deployment - TLS and Corporate CA Certificates.

2. Linux/systemd: Add the CA to the system trust store or set the SSL_CERT_FILE environment variable:

   export SSL_CERT_FILE=/path/to/corporate-ca-bundle.crt
   

3. Docker: Mount the CA certificate:

   docker run -v /path/to/ca-bundle.crt:/etc/ssl/certs/ca-certificates.crt:ro \
     ghcr.io/redis-field-engineering/radar-collector:alpine-latest \
     --config /etc/radar/radar-collector.yml
   

Debug Logging

# Info level (default)
RUST_LOG=info radar-collector

# Debug level
RUST_LOG=debug radar-collector

# Trace level (very verbose)
RUST_LOG=trace radar-collector

Testing Connectivity

Redis Software

curl -k https://enterprise.example.com:9443/v1/cluster

Redis Standalone/Cluster

redis-cli -h host -p port ping

Getting Help

Include this information when reporting issues:

1. Collector version: radar-collector --version
2. Validation output: radar-collector --validate
3. Debug logs: RUST_LOG=debug radar-collector 2>&1 | head -100
4. Connection test results

Configuration Schema

Complete reference for Radar Collector configuration.

Top-Level Configuration

collector:                         # Optional - Collector settings
  id: string                       # Required - Unique collector identifier
  collection_interval: string      # Optional - Collection interval (default: 30s)
  output_directory: string         # Optional - Output dir for offline collections
  redact: boolean                  # Optional - Redact sensitive fields (default: true)

server:                            # Required - Server configuration
  grpc_url: string                 # Required - gRPC server endpoint
  api_key: string                  # Required - API key for authentication
  timeout: string                  # Optional - Request timeout (default: 30s)

deployments: array                 # Required - List of deployments to monitor

Collector Configuration

The collector section controls agent behavior:

collector:
  id: "radar-collector-001"        # Unique identifier for this collector
  hostname: "my-host"              # Override system hostname (optional)
  collection_interval: 30s         # How often to collect from each deployment
  health_report_interval: 60s      # Health report interval
  log_level: info                  # Optional log level override
  labels:                          # Optional key-value labels
    env: production
    region: us-east-1
  output_directory: /var/radar/collections  # Where to write offline collection files
  redact: true                     # Redact sensitive fields (default: true)
  remote_config:                   # Remote-managed configuration
    enabled: true                  # Enable remote config (default: true)
    mode: managed                  # managed or local (default: managed)
    managed_secrets: true          # Include secrets from server (default: true)
    poll_interval: 30s             # Config polling interval (default: 30s)

Redaction behavior when enabled:

• Passwords and API keys → ***REDACTED***
• Hostnames → deterministic hash (e.g. host-a1b2c3.example.com)
• IP addresses → 192.xxx.xxx.xxx
• Port numbers → 0

To disable via config:

collector:
  redact: false

Server Configuration

The server section configures connection to the Radar server. Generate an API key from the Radar dashboard under Settings > Access Keys.

server:
  grpc_url: "https://grpc.radar.redis.io:443"  # gRPC endpoint
  api_key: "your-api-key"                       # Authentication key
  timeout: "30s"                                # Request timeout (optional)

Deployment Configuration

Each deployment in the deployments array must specify a type and type-specific fields.

Common Fields

Per-Deployment Collection Settings

Each deployment can override collection behavior:

deployments:
  - id: "cache-01"
    name: "cache-server"
    type: "standalone"
    redis_url: "redis://localhost:6379"
    collection:
      interval: "60s"           # Override collection interval
      retry_on_failure: true    # Retry on failure (default: true)
      max_retries: 3            # Max retry attempts (default: 3)
      timeout: "30s"            # Collection timeout (default: 30s)

Standalone Configuration

deployments:
  - id: string                      # Required - Unique deployment ID
    name: string                    # Required - Unique name
    type: "standalone"              # Required
    redis_url: string               # Optional - Redis connection URL (default: redis://localhost:6379, use rediss:// for TLS)
    credentials:                    # Optional - Authentication
      password: string              # Optional - Redis password

Note: For standalone deployments, redis_url controls the host, port, and TLS scheme only. Configure authentication with credentials.password or REDIS_PASSWORD. Standalone deployments do not currently support a Redis ACL username.

Example:

deployments:
  - id: "cache-01"
    name: "cache-server"
    type: "standalone"
    redis_url: "redis://redis.example.com:6379"
    credentials:
      password: "${REDIS_PASSWORD}"

For TLS:

deployments:
  - id: "cache-tls-01"
    name: "cache-server-tls"
    type: "standalone"
    redis_url: "rediss://redis.example.com:6380"  # rediss:// for TLS
    credentials:
      password: "${REDIS_PASSWORD}"

Redis Software Configuration

deployments:
  - id: string                      # Required - Unique deployment ID
    name: string                    # Required - Unique name
    type: "enterprise"              # Required
    rest_api:                       # Required - REST API configuration
      host: string                  # Required - REST API hostname
      port: integer                 # Required - REST API port (typically 9443)
      use_tls: boolean              # Required - Use HTTPS (typically true)
      insecure: boolean             # Optional - Skip cert verification (default: true)
      enterprise_admin_url: string  # Optional - Management UI redirect URL
    enterprise:                     # Optional - Enterprise options
      db_endpoint: string           # Optional - Database endpoint style (external_ip, internal_ip, dns)
    credentials:                    # Required - Authentication
      rest_api:
        basic_auth: string          # Required - "username:password" format

Note: enterprise_api is also accepted as an alias for rest_api in the credentials section for backward compatibility.

Example:

deployments:
  - id: "ent-prod"
    name: "production-enterprise"
    type: "enterprise"
    rest_api:
      host: "enterprise.example.com"
      port: 9443
      use_tls: true
      insecure: true  # For self-signed certificates
      enterprise_admin_url: "https://enterprise.example.com:8443"  # Management UI redirect URL
    enterprise:
      db_endpoint: "external_ip"
    credentials:
      rest_api:
        basic_auth: "admin@redis.local:${ENTERPRISE_PASSWORD}"

Cluster Configuration

deployments:
  - id: string                      # Required - Unique deployment ID
    name: string                    # Required - Unique name
    type: "cluster"                 # Required
    redis_urls: array<string>       # Required - Seed nodes for discovery
    credentials:                    # Optional - Authentication
      username: string              # Optional - Cluster username
      password: string              # Optional - Cluster password

Example:

deployments:
  - id: "cluster-01"
    name: "main-cluster"
    type: "cluster"
    redis_urls:
      - "node1.example.com:7000"
      - "node2.example.com:7000"
      - "node3.example.com:7000"
    credentials:
      password: "${CLUSTER_PASSWORD}"

Sentinel Configuration

deployments:
  - id: string                      # Required - Unique deployment ID
    name: string                    # Required - Unique name
    type: "sentinel"                # Required
    master_name: string             # Required - Name of master in Sentinel
    sentinel_urls: array<string>    # Required - Sentinel endpoints
    credentials:                    # Optional - Authentication
      password: string              # Optional - Redis password

Example:

deployments:
  - id: "sentinel-01"
    name: "ha-redis"
    type: "sentinel"
    master_name: "mymaster"
    sentinel_urls:
      - "sentinel1.example.com:26379"
      - "sentinel2.example.com:26379"
      - "sentinel3.example.com:26379"
    credentials:
      password: "${REDIS_PASSWORD}"

Complete Example

# Collector configuration
collector:
  id: "radar-collector-001"
  collection_interval: "60s"
  redact: true  # set to false to disable redaction

# Server configuration
server:
  grpc_url: "https://grpc.radar.redis.io:443"  # Production Radar gRPC endpoint
  api_key: "${RADAR_API_KEY}"

# Deployment configurations
deployments:
  # Software cluster
  - id: "ent-01"
    name: "enterprise-production"
    type: "enterprise"
    rest_api:
      host: "cluster.redis.local"
      port: 9443
      use_tls: true
      insecure: true
      enterprise_admin_url: "https://cluster.redis.local:8443"  # Optional
    enterprise:
      db_endpoint: "external_ip"
    credentials:
      rest_api:
        basic_auth: "admin@redis.local:${ENT_PASSWORD}"

  # Standalone instance
  - id: "cache-01"
    name: "session-cache"
    type: "standalone"
    redis_url: "redis://cache.redis.local:6379"
    credentials:
      password: "${CACHE_PASSWORD}"

  # Redis Cluster
  - id: "cluster-01"
    name: "data-cluster"
    type: "cluster"
    redis_urls:
      - "cluster1.redis.local:7000"
      - "cluster2.redis.local:7000"
      - "cluster3.redis.local:7000"
    credentials:
      password: "${CLUSTER_PASSWORD}"

  # Sentinel HA
  - id: "sentinel-01"
    name: "ha-master"
    type: "sentinel"
    master_name: "mymaster"
    sentinel_urls:
      - "sentinel1.redis.local:26379"
      - "sentinel2.redis.local:26379"
      - "sentinel3.redis.local:26379"
    credentials:
      password: "${REDIS_PASSWORD}"

Environment Variables

The collector supports two mechanisms for using environment variables:

1. YAML Interpolation (Recommended)

Environment variables are expanded during configuration file loading using shell-like syntax:

• ${VAR} - Required variable (agent fails to start if not set)
• ${VAR:-default} - Use default if VAR is unset or empty
• ${VAR-default} - Use default if VAR is unset (empty string is valid)

Important: Only ${VAR} (braced) syntax is expanded. Bare $VAR is NOT expanded, allowing literal $ characters in values (e.g., passwords like my$ecret). Interpolation is applied after YAML parsing, so # and other YAML-significant characters inside interpolated secrets are treated as data, not syntax.

When to use which:

• Use :- when empty values should fall back to default
• Use - when empty is a valid value (e.g., Redis with no password: password: ${REDIS_PASSWORD-})

Example:

server:
  grpc_url: "${RADAR_SERVER:-https://grpc.radar.redis.io:443}"
  api_key: "${RADAR_API_KEY}"

deployments:
  - id: "redis-prod"
    name: "Production Redis"
    type: "standalone"
    redis_url: "redis://${REDIS_HOST:-localhost}:${REDIS_PORT:-6379}"
    credentials:
      password: "${REDIS_PROD_PASSWORD}"

  - id: "redis-dev"
    name: "Dev Redis"
    type: "standalone"
    redis_url: "redis://${DEV_REDIS_HOST}:6379"
    credentials:
      password: "${REDIS_DEV_PASSWORD}"

Benefits:

• ✅ Per-deployment control (different env vars for each deployment)
• ✅ Works with any configuration field
• ✅ Clear and explicit in configuration file
• ✅ Supports default values

2. Runtime Overrides

Environment variables can override configuration values after YAML parsing. These are applied globally or per-deployment.

When to use:

• Quick testing/debugging without modifying config files
• Container/Kubernetes environments where env vars are easier to manage
• Overriding specific values in existing configurations

Precedence: Runtime overrides take precedence over YAML values (including interpolated values).

Global Overrides

Apply to all deployments or global settings:

# Server settings
export GRPC_ENDPOINT=https://grpc.radar.redis.io:443
export COLLECTION_INTERVAL=30  # seconds

# Standalone/Cluster/Sentinel (applies to ALL deployments of these types)
export REDIS_HOST=redis.example.com      # All standalone deployments
export REDIS_PORT=6379                   # All standalone deployments
export REDIS_PASSWORD=secret             # All standalone/cluster/sentinel deployments

⚠️ Warning: REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD apply to ALL deployments of the respective type. For multiple deployments with different credentials, use per-deployment overrides or YAML interpolation instead.

Per-Deployment Overrides

Override specific deployments using their id field (converted to UPPERCASE with - replaced by _):

Standalone Deployments:

# For deployment with id: "redis-prod"
export REDIS_STANDALONE_REDIS_PROD_HOST=prod.redis.example.com
export REDIS_STANDALONE_REDIS_PROD_PORT=6380
export REDIS_STANDALONE_REDIS_PROD_PASSWORD=prod-secret

Cluster Deployments:

# For deployment with id: "cluster-01"
export REDIS_CLUSTER_CLUSTER_01_PASSWORD=cluster-secret

Sentinel Deployments:

# For deployment with id: "sentinel-ha"
export REDIS_SENTINEL_SENTINEL_HA_PASSWORD=sentinel-secret

Redis Software (Enterprise) Deployments:

# For deployment with id: "ent-01"
export REDIS_ENTERPRISE_ENT_01_REST_API_URL=https://new-url:9443
export REDIS_ENTERPRISE_ENT_01_ADMIN_URL=https://admin.example.com:8443
export REDIS_ENTERPRISE_ENT_01_USERNAME=newuser
export REDIS_ENTERPRISE_ENT_01_PASSWORD=newpass
export REDIS_ENTERPRISE_ENT_01_SSL_NO_VERIFY=true

REDIS_ENTERPRISE_{ID}_REST_API_URL must use https://. REDIS_ENTERPRISE_{ID}_SSL_NO_VERIFY=true disables certificate verification while keeping HTTPS enabled.

Advanced Settings

Retry Configuration:

export RETRY_MAX_ATTEMPTS=5              # Default: 3
export RETRY_INITIAL_DELAY_SECS=2        # Default: 1
export RETRY_MAX_DELAY_SECS=60           # Default: 30
export RETRY_MULTIPLIER=3.0              # Default: 2.0

Collection Behavior:

export CONCURRENT_COLLECTION=false       # Default: true (disable for debugging)

Authentication

The collector authenticates with the Radar server via an API key set in server.api_key.

Via config file (recommended):

server:
  api_key: "${MY_API_KEY}"

export MY_API_KEY=your-api-key

Via environment variable:

export ACCESS_KEY=your-api-key

If both server.api_key and the ACCESS_KEY environment variable are set, ACCESS_KEY takes precedence.

Validation

Validate your configuration:

# Validate entire configuration
radar-collector --validate

# Validate specific deployment
radar-collector validate --deployment enterprise-production

# Test collection from deployment
radar-collector test --deployment session-cache

# Dry run (collect but don't submit)
radar-collector --dry-run

Environment Variables Reference

Complete reference for all environment variables supported by Radar Collector.

Two Types of Environment Variable Usage

1. YAML Interpolation (Recommended)

Variables are expanded when the configuration file is loaded:

server:
  api_key: "${RADAR_API_KEY}"
  grpc_url: "${RADAR_SERVER:-https://grpc.radar.redis.io:443}"

Syntax:

• ${VAR} - Required (fails if not set)
• ${VAR:-default} - Use default if VAR is unset or empty
• ${VAR-default} - Use default if VAR is unset (empty string is valid)

Important: Only ${VAR} (braced) syntax is expanded. Bare $VAR is NOT expanded. This allows literal $ characters in YAML values (e.g., passwords like my$ecret). Interpolation is applied after YAML parsing, so # and other YAML-significant characters inside interpolated secrets are treated as data, not syntax.

When to use which:

• Use :- when empty values should fall back to default
• Use - when empty is a valid value (e.g., Redis with no password: password: ${REDIS_PASSWORD-})

Use for: Per-deployment credentials, secrets, environment-specific values

2. Runtime Overrides

Variables override configuration after YAML parsing. See sections below for supported variables.

Use for: Quick testing, debugging, container environments

Global Configuration

Authentication

The collector uses ACCESS_KEY for gRPC authentication. You can set it:

1. Via config file (recommended):

   server:
     api_key: "${MY_API_KEY}"
   

2. Via environment variable:

   export ACCESS_KEY=your-api-key
   

If both are set, ACCESS_KEY takes precedence.

Standalone Deployments

Global Overrides (All Standalone Deployments)

⚠️ Warning: These apply to ALL standalone deployments.

Per-Deployment Overrides

Replace {ID} with deployment ID in UPPERCASE with - → _.

Example: deployment id: "redis-prod" → REDIS_PROD

Example:

# For deployment with id: "redis-prod"
export REDIS_STANDALONE_REDIS_PROD_HOST=prod.example.com
export REDIS_STANDALONE_REDIS_PROD_PORT=6380
export REDIS_STANDALONE_REDIS_PROD_PASSWORD=secret

Cluster Deployments

Global Override (All Cluster Deployments)

⚠️ Warning: Applies to ALL cluster deployments.

Per-Deployment Override

Example:

# For deployment with id: "cluster-01"
export REDIS_CLUSTER_CLUSTER_01_PASSWORD=cluster-secret

Sentinel Deployments

Global Override (All Sentinel Deployments)

⚠️ Warning: Applies to ALL sentinel deployments.

Per-Deployment Override

Example:

# For deployment with id: "sentinel-ha"
export REDIS_SENTINEL_SENTINEL_HA_PASSWORD=sentinel-secret

Redis Software (Enterprise) Deployments

All per-deployment. Replace {ID} with deployment ID in UPPERCASE with - → _.

Example:

# For deployment with id: "ent-01"
export REDIS_ENTERPRISE_ENT_01_REST_API_URL=https://enterprise.example.com:9443
export REDIS_ENTERPRISE_ENT_01_ADMIN_URL=https://admin.example.com:8443
export REDIS_ENTERPRISE_ENT_01_USERNAME=admin@example.com
export REDIS_ENTERPRISE_ENT_01_PASSWORD=secret
export REDIS_ENTERPRISE_ENT_01_SSL_NO_VERIFY=true

REDIS_ENTERPRISE_{ID}_SSL_NO_VERIFY defaults to true. Set to false to require certificate verification.

Retry Configuration

Control retry behavior for failed operations:

Example:

export RETRY_MAX_ATTEMPTS=5
export RETRY_INITIAL_DELAY_SECS=2
export RETRY_MAX_DELAY_SECS=60
export RETRY_MULTIPLIER=3.0

Advanced Settings

Set to false to disable concurrent collection (useful for debugging):

export CONCURRENT_COLLECTION=false

Best Practices

1. Use YAML interpolation for secrets and per-deployment values:

   credentials:
     password: "${REDIS_PROD_PASSWORD}"  # Different var per deployment
   

2. Use runtime overrides for testing/debugging:

   GRPC_ENDPOINT=http://localhost:50051 radar-collector
   

3. Avoid global overrides with multiple deployments:

   • ❌ REDIS_PASSWORD affects ALL deployments
   • ✅ Use REDIS_STANDALONE_{ID}_PASSWORD for specific deployments
   • ✅ Or use YAML interpolation with different variables

4. ID transformation rules:

   • Deployment id: "my-redis" → MY_REDIS
   • Deployment id: "redis_prod" → REDIS_PROD
   • Deployment id: "Redis-01" → REDIS_01

Command Line Reference

Synopsis

radar-collector [OPTIONS] [COMMAND]

Global Options

Subcommands

connect

Connect this collector to Radar using a browser-based activation flow. The collector opens a browser window to the Radar UI where you authenticate and approve the collector. On success, the collector stores its credential locally and begins collecting.

If the default config file (radar-collector.yml) is not found and no stored credential exists from a previous activation, the collector automatically enters this activation flow on first run.

# Start browser-based activation
radar-collector connect

# Activation with a custom Radar API URL
radar-collector connect --server-url https://radar.redis.io/api

# Print the activation URL without opening a browser
radar-collector connect --no-browser

Options:

• --server-url <URL> - Override the Radar API base URL used for activation
• --no-browser - Disable automatic browser launch; print the activation URL only

validate

Validate a specific deployment configuration and test connectivity.

# Validate specific deployment
radar-collector validate --deployment my-redis

# With custom config
radar-collector --config custom.yml validate --deployment production

Options:

• -d, --deployment <NAME> - Name of deployment to validate (required)

test

Test collection from a specific deployment (full collection).

# Test specific deployment
radar-collector test --deployment my-redis

# Test with debug logging
radar-collector --log-level debug test --deployment my-redis

Options:

• -d, --deployment <NAME> - Name of deployment to test (required)

submit

Submit a previously collected offline data file to the server.

# Submit offline collection file
radar-collector submit --file /path/to/collection.json

# With custom config for server settings
radar-collector --config custom.yml submit --file collection.json

Options:

• -f, --file <PATH> - Path to offline collection JSON file (required)

Usage Examples

Basic Operation

# Run with default config
radar-collector

# Run with custom config
radar-collector --config /etc/radar/config.yml

# Run once and exit
radar-collector --once

# Dry run (no submission)
radar-collector --dry-run

Offline Collection

# Collect to auto-generated file (redaction comes from config, default enabled)
radar-collector --once --output-file

# Collect to specific file
radar-collector --once --output-file /path/to/collection.json

# Collect with custom output directory
radar-collector --once --output-file --output-dir /var/lib/radar

# Force-enable redaction via CLI
radar-collector --once --output-file --redact

# Submit previously collected file
radar-collector submit --file radar-collection-hostname-v0.1.0-20251014-120000.json

Validation

# Validate entire configuration
radar-collector --validate

# Validate specific deployment
radar-collector validate --deployment redis-production

Debugging

# Enable debug logging
radar-collector --log-level debug

# JSON formatted logs
radar-collector --json-logs

# Test collection without submission
radar-collector --dry-run --once

Environment Variables

Authentication

• ACCESS_KEY - API key for gRPC authentication

Configuration Overrides

Global settings:

• GRPC_ENDPOINT - Override gRPC server endpoint
• COLLECTION_INTERVAL - Override collection interval (seconds)

Per-deployment overrides (by deployment ID):

# Software deployment with ID "ent-01"
export REDIS_ENTERPRISE_ENT_01_REST_API_URL=https://enterprise:9443
export REDIS_ENTERPRISE_ENT_01_USERNAME=admin
export REDIS_ENTERPRISE_ENT_01_PASSWORD=secret
export REDIS_ENTERPRISE_ENT_01_SSL_NO_VERIFY=true

# Standalone defaults (when only one exists)
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_PASSWORD=mypassword

Logging

• RUST_LOG - Control log verbosity
  • error - Errors only
  • warn - Warnings and errors
  • info - Standard operation (default)
  • debug - Detailed operations
  • trace - All data including responses

Example:

RUST_LOG=debug radar-collector
RUST_LOG=radar_collector=debug,tonic=warn radar-collector

Exit Codes

• 0 - Success
• 1 - Error (configuration, connection, or runtime error)

Signal Handling

The radar-collector handles the following signals gracefully:

• SIGINT (Ctrl+C) - Graceful shutdown
• SIGTERM - Graceful shutdown

During shutdown:

1. Current collection completes
2. Pending submissions are sent
3. Connections are closed
4. Final metrics are logged