Introduction

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

Supported Deployment Types

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

Features

Monitor multiple Redis deployments from a single agent
YAML configuration with environment variable expansion
Offline collection mode with configurable data redaction
gRPC communication with API key authentication
Configuration validation and connection testing
Signal handling for graceful shutdown (SIGINT, SIGTERM)
Configurable logging levels with JSON output option

Quick Start

Install the agent binary
Configure your Redis deployments
Validate your configuration
Run the agent

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-agent 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-agent/releases/download/VERSION/radar-agent-PLATFORM

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

# Verify installation
radar-agent --version

Docker

Pull the Docker image:

docker pull ghcr.io/redis-field-engineering/radar-agent:latest

Run with configuration file:

docker run -v /path/to/config.yml:/config.yml ghcr.io/redis-field-engineering/radar-agent:latest --config /config.yml

Next Steps

Configuration

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

Basic Example

agent:
  id: radar-agent-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

agent

Agent settings:

id - Unique agent identifier (required)
collection_interval - How often to collect (default: 60s)
output_directory - Directory for offline collections (default: current directory)
redaction_level - Default redaction level: none, credentials, all (default: all)

server

Server connection:

grpc_url - Radar server gRPC endpoint (required)
api_key - Authentication key (required)
timeout - Request timeout (default: 30s)

deployments

List of Redis deployments to monitor. Each deployment needs:

id - Unique identifier (required)
name - Display name (required)
type - Deployment type (required)

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

Environment Variables

Use ${VAR} or ${VAR:-default} syntax:

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

Deployment Types

Radar Agent 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

Enterprise Deployments

Monitor Redis Enterprise clusters via REST API.

Configuration

deployments:
  - id: "ent-prod"
    name: "production-enterprise"
    type: "enterprise"  # Case-insensitive
    rest_api:
      host: "enterprise.example.com"
      port: 9443
      use_tls: true
      insecure: false  # Set true for self-signed certs
      enterprise_admin_url: "https://enterprise.example.com:8443"  # Optional 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 UI URL for reference only (not used for data collection)

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")

Alternative Configuration (Compatibility)

For backward compatibility, enterprise_api is also supported as an alias for rest_api in the credentials section:

deployments:
  - id: "ent-prod"
    name: "production-enterprise"
    type: "enterprise"
    rest_api:
      host: "enterprise.example.com"
      port: 9443
      use_tls: true
      insecure: true
    credentials:
      enterprise_api:  # Alternative to rest_api (both work)
        basic_auth: "admin@redis.local:${ENTERPRISE_PASSWORD}"

Environment Variables

# Override by deployment ID (uses uppercased ID with underscores)
export RADAR_ENTERPRISE_ENT_PROD_REST_API_URL=https://new-url:9443
export RADAR_ENTERPRISE_ENT_PROD_USERNAME=admin@redis.local
export RADAR_ENTERPRISE_ENT_PROD_PASSWORD=newpassword
export RADAR_ENTERPRISE_ENT_PROD_INSECURE=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"  # Case-insensitive
    redis_urls:
      - "cluster1.example.com:7000"
      - "cluster2.example.com:7000"
      - "cluster3.example.com:7000"
    credentials:
      password: "${CLUSTER_PASSWORD}"  # Optional

Note: The agent 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"  # Case-insensitive
    master_name: "mymaster"
    sentinel_urls:
      - "sentinel1.example.com:26379"
      - "sentinel2.example.com:26379"
      - "sentinel3.example.com:26379"
    credentials:
      password: "${REDIS_PASSWORD}"           # Redis instance password
      sentinel_password: "${SENTINEL_PASSWORD}" # Sentinel password (if different)

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:

agent:
  id: radar-agent-001

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

deployments:
  # Enterprise 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 specific deployment
radar-agent validate --deployment enterprise-prod

# Test collection
radar-agent test --deployment session-cache

# Validate all
radar-agent --validate

Credentials & Security

Configure Redis credentials to allow Radar Agent to collect monitoring data. The agent requires read-only access to Redis instances and supports various authentication methods.

Redis Standalone Authentication

For standalone Redis instances, you can configure authentication in several ways:

Method 1: URL-based Authentication

Include credentials directly in the Redis URL:

deployments:
  - id: "redis-prod"
    name: "Production Redis"
    deployment_type: "standalone"
    redis_url: "redis://username:password@localhost:6379"

Method 2: Separate Credentials

Use the credentials section for better security:

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

Method 3: Environment Variables in URL

Combine URL format with environment variable expansion:

deployments:
  - id: "redis-prod"
    name: "Production Redis"
    deployment_type: "standalone" 
    redis_url: "redis://${REDIS_USER}:${REDIS_PASSWORD}@${REDIS_HOST}:6379"

Redis ACL Setup

Creating a Monitoring User

For Redis instances with ACL support (Redis 6+), create a dedicated monitoring user:

# Connect to Redis
redis-cli

# Create user with read-only permissions
ACL SETUSER radar-agent on >${SECURE_PASSWORD} \
  +info +ping +config|get +client|list +memory|usage +latency \
  +@read ~* &*

# Verify the user
ACL LIST

Required Permissions

The radar-agent user needs these Redis permissions:

Command Category	Commands	Purpose
Server Info	`+info`, `+ping`	Basic server information and health
Configuration	`+config\|get`	Redis configuration settings
Client Info	`+client\|list`	Active connection information
Memory	`+memory\|usage`	Memory usage statistics
Performance	`+latency`	Latency monitoring data
Data Access	`+@read`, `~*`	Read access to all keys for sampling
Pub/Sub	`&*`	Access to all pub/sub channels

Minimal ACL Rule

For the most restrictive setup:

ACL SETUSER radar-agent 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"
    deployment_type: "standalone"
    redis_url: "rediss://username:password@localhost:6380"

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"
    deployment_type: "standalone"
    redis_url: "redis://radar-agent:${REDIS_PASSWORD}@${REDIS_HOST}:${REDIS_PORT}"
    
  - id: "redis-replica"
    name: "Redis Replica"
    deployment_type: "standalone" 
    redis_url: "redis://${REDIS_HOST_REPLICA}:6379"
    credentials:
      username: "radar-agent"
      password: "${REDIS_REPLICA_PASSWORD}"

Testing Credentials

Validate your credentials using the validation command:

# Test all deployments
radar-agent validate

# Test specific deployment
radar-agent validate --deployment-id redis-prod

# Test with connection attempts
radar-agent validate --test-connections

Security Best Practices

Use dedicated monitoring users - Don't use admin credentials
Apply least privilege - Only grant necessary permissions
Use environment variables - Don't hardcode credentials in config files
Enable TLS - Use rediss:// URLs for encrypted connections
Rotate credentials - Regularly update passwords and API keys
Monitor access - Review Redis logs for authentication events

Redis Enterprise Authentication

Redis Enterprise 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: false  # Set true for self-signed certificates
    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
Supports self-signed certificates with insecure: true
Uses port 9443 for REST API access

Future Authentication Support

Planned authentication methods for future deployment types:

Redis Cloud (Planned)

API key authentication
Cloud console integration

AWS ElastiCache (Planned)

IAM role-based authentication
AUTH token support

Running the Agent

The agent supports multiple operational modes:

Continuous Mode (Production)

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

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

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

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

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

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-agent --once --output-file
# Creates: radar-collection-hostname-v0.1.0-20251014-120000.json

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

# With specific redaction level
./radar-agent --once --output-file --redact credentials

Redaction Levels

all (default) - Maximum privacy:

Passwords → ***REDACTED***
API keys → ***REDACTED***
Hostnames → host-a1b2c3d4.domain.com (deterministic hash)
IP addresses → 192.xxx.xxx.xxx (first octet only)
Port numbers → 6xxx (first digit only)

credentials - Moderate privacy:

Passwords → ***REDACTED***
API keys → ***REDACTED***
Hostnames, IPs, ports → visible

none - No redaction (debug only):

All data visible in plaintext
Only use in isolated, secure environments

Submit Collected Data

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

# With custom server config
./radar-agent --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-agent test --deployment redis-prod

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

# With debug output
RUST_LOG=debug ./radar-agent test --deployment enterprise-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-agent --validate

# Validate specific deployment
./radar-agent 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-agent

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

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

Graceful Shutdown

The agent handles SIGTERM and SIGINT signals gracefully:

Receives shutdown signal
Stops scheduling new collections
Completes current collection in progress
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
./radar-agent --validate

# Test specific deployment
./radar-agent validate --deployment redis-prod

Test Collection

# Dry run - collect without submitting
./radar-agent test --deployment redis-prod --dry-run

# Single collection with submission
./radar-agent test --deployment redis-prod

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

Recommended Workflow

Validate configuration
```
./radar-agent --validate
```

Test single deployment

./radar-agent test --deployment redis-prod --dry-run

Run agent
```
./radar-agent
```

Deployment

Deploy Radar Agent 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 agent 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 Agent as a systemd service.

Installation

1. Create User and Directories

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

2. Install Binary

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

3. Create Configuration

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

agent:
  id: radar-agent-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-agent/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-agent/environment
sudo chmod 640 /etc/radar-agent/config.yml

5. Create Systemd Service

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

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

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

[Install]
WantedBy=multi-user.target

6. Start Service

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

Service Management

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

# Restart after config changes
sudo systemctl restart radar-agent

# Stop service
sudo systemctl stop radar-agent

Kubernetes Deployment

Deploy Radar Agent 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 Agent

Quick Start

1. Create Namespace

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

kubectl apply -f namespace.yaml

2. Create Secrets

Store sensitive configuration in Kubernetes Secrets:

# secrets.yaml
apiVersion: v1
kind: Secret
metadata:
  name: radar-agent-secrets
  namespace: radar-agent
type: Opaque
stringData:
  api-key: "your-radar-api-key"
  redis-password: "your-redis-password"

kubectl apply -f secrets.yaml

3. Create ConfigMap

Store the agent configuration:

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

    server:
      grpc_url: "https://api.radar.com:443"
      api_key: "${RADAR_API_KEY}"

    deployments:
      - id: "redis-production"
        name: "Production Redis"
        deployment_type: "standalone"
        redis_url: "redis://radar-agent:${REDIS_PASSWORD}@redis.production.svc.cluster.local:6379"
        collection:
          interval: "30s"
          retry_on_failure: true
          max_retries: 3

kubectl apply -f configmap.yaml

4. Create Deployment

Deploy the Radar Agent:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: radar-agent
  namespace: radar-agent
  labels:
    app: radar-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: radar-agent
  template:
    metadata:
      labels:
        app: radar-agent
    spec:
      serviceAccountName: radar-agent
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
      containers:
      - name: radar-agent
        image: radar-agent:latest  # Replace with your image
        imagePullPolicy: Always
        
        # Command and arguments
        command: ["/app/radar-agent"]
        args: ["--config", "/etc/radar-agent/config.yml"]
        
        # Environment variables
        env:
        - name: HOSTNAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: RADAR_API_KEY
          valueFrom:
            secretKeyRef:
              name: radar-agent-secrets
              key: api-key
        - name: REDIS_PASSWORD
          valueFrom:
            secretKeyRef:
              name: radar-agent-secrets
              key: redis-password
        - name: RUST_LOG
          value: "info"
        
        # Volume mounts
        volumeMounts:
        - name: config
          mountPath: /etc/radar-agent
          readOnly: true
        
        # Resource limits
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "500m"
        
        # Health checks
        livenessProbe:
          exec:
            command:
            - /app/radar-agent
            - validate
            - --config
            - /etc/radar-agent/config.yml
          initialDelaySeconds: 30
          periodSeconds: 60
          timeoutSeconds: 10
        
        readinessProbe:
          exec:
            command:
            - /app/radar-agent  
            - validate
            - --config
            - /etc/radar-agent/config.yml
            - --test-connections
          initialDelaySeconds: 10
          periodSeconds: 30
          timeoutSeconds: 15
      
      volumes:
      - name: config
        configMap:
          name: radar-agent-config
      
      # Restart policy
      restartPolicy: Always
      
      # Node selection (optional)
      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-agent
  namespace: radar-agent

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

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

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

Advanced Configuration

Multi-Environment Setup

Deploy different agents for different environments:

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

---
apiVersion: apps/v1  
kind: Deployment
metadata:
  name: radar-agent-staging
  namespace: radar-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: radar-agent
      environment: staging
  template:
    metadata:
      labels:
        app: radar-agent
        environment: staging
    spec:
      containers:
      - name: radar-agent
        image: radar-agent:latest
        env:
        - name: ENVIRONMENT
          value: "staging"
        volumeMounts:
        - name: config
          mountPath: /etc/radar-agent
      volumes:
      - name: config
        configMap:
          name: radar-agent-config-staging

Horizontal Pod Autoscaler

Auto-scale based on CPU usage:

# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: radar-agent-hpa
  namespace: radar-agent
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: radar-agent
  minReplicas: 1
  maxReplicas: 3
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

Network Policies

Restrict network access:

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

Container Image

Dockerfile

Create a secure container image:

# Dockerfile
FROM rust:1.88-slim as builder

WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim

# Install CA certificates and create user
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    rm -rf /var/lib/apt/lists/* && \
    groupadd -r radar-agent && \
    useradd -r -g radar-agent radar-agent

# Copy binary
COPY --from=builder /app/target/release/radar-agent /app/radar-agent

# Set ownership and permissions
RUN chown radar-agent:radar-agent /app/radar-agent

# Switch to non-root user
USER radar-agent

# Expose metrics port (if implemented)
EXPOSE 8080

ENTRYPOINT ["/app/radar-agent"]

Build and Push

# Build image
docker build -t radar-agent:latest .

# Tag for registry
docker tag radar-agent:latest your-registry.com/radar-agent:latest

# Push to registry
docker push your-registry.com/radar-agent:latest

Management and Operations

View Logs

# View logs from all radar-agent pods
kubectl logs -n radar-agent -l app=radar-agent -f

# View logs from specific pod
kubectl logs -n radar-agent <pod-name> -f

# View previous container logs (after restart)
kubectl logs -n radar-agent <pod-name> --previous

Update Configuration

# Update ConfigMap
kubectl apply -f configmap.yaml

# Restart deployment to pick up changes
kubectl rollout restart deployment/radar-agent -n radar-agent

# Check rollout status
kubectl rollout status deployment/radar-agent -n radar-agent

Scale Deployment

# Scale to 3 replicas
kubectl scale deployment/radar-agent --replicas=3 -n radar-agent

# Auto-scale based on CPU
kubectl autoscale deployment/radar-agent --cpu-percent=70 --min=1 --max=5 -n radar-agent

Monitoring and Alerting

Pod Monitoring

# servicemonitor.yaml (for Prometheus Operator)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: radar-agent
  namespace: radar-agent
spec:
  selector:
    matchLabels:
      app: radar-agent
  endpoints:
  - port: metrics
    interval: 30s
    path: /metrics

Alerting Rules

# alerts.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: radar-agent-alerts
  namespace: radar-agent
spec:
  groups:
  - name: radar-agent
    rules:
    - alert: RadarAgentDown
      expr: up{job="radar-agent"} == 0
      for: 5m
      labels:
        severity: critical
      annotations:
        summary: "Radar Agent is down"
        description: "Radar Agent has been down for more than 5 minutes"

Troubleshooting

Common Issues

Pod won't start:

# Check pod status
kubectl get pods -n radar-agent

# Describe pod for events
kubectl describe pod <pod-name> -n radar-agent

# Check logs
kubectl logs <pod-name> -n radar-agent

Configuration issues:

# Validate ConfigMap
kubectl get configmap radar-agent-config -n radar-agent -o yaml

# Test configuration in pod
kubectl exec -it <pod-name> -n radar-agent -- /app/radar-agent validate --config /etc/radar-agent/config.yml

Network connectivity:

# Test from within pod
kubectl exec -it <pod-name> -n radar-agent -- /bin/sh

# Inside pod:
curl -v https://api.radar.com
redis-cli -u redis://user:pass@redis.example.com:6379 ping

Health Checks

Monitor deployment health:

# Check deployment status
kubectl get deployment radar-agent -n radar-agent

# Check pod health
kubectl get pods -n radar-agent -l app=radar-agent

# Check recent events
kubectl get events -n radar-agent --sort-by='.lastTimestamp'

Troubleshooting

Diagnosis Steps

Validate configuration: radar-agent --validate
Enable debug logging: RUST_LOG=debug radar-agent
Test connectivity with curl/redis-cli
Check error messages for diagnostic hints

Common Issues

Enterprise REST API Connection Failed

Symptoms:

Error: failed to connect to localhost:9443

Solutions:

Use actual hostname, not "localhost"

credentials:
  rest_api:
    url: "https://enterprise.example.com:9443"  # Correct

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

For self-signed certificates:

credentials:
  rest_api:
    insecure: true  # Skip certificate validation

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-agent --validate

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

Debug Logging

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

# Debug level
RUST_LOG=debug radar-agent

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

Testing Connectivity

Enterprise

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:

Agent version: radar-agent --version
Validation output: radar-agent --validate
Debug logs: RUST_LOG=debug radar-agent 2>&1 | head -100
Connection test results

Configuration Schema

Complete reference for Radar Agent configuration.

Top-Level Configuration

server:                            # Required - Server configuration
  grpc_endpoint: string            # Required - gRPC server endpoint
  api_key: string                  # Required - API key for authentication

collection_interval: integer       # Optional - Seconds between collections (default: 60)
deployments: array                 # Required - List of deployments to monitor

Server Configuration

The server section configures connection to the Radar server:

server:
  grpc_endpoint: "http://localhost:50051"  # gRPC endpoint
  api_key: "your-api-key"                  # Authentication key

The api_key is automatically set as the ACCESS_KEY environment variable for gRPC authentication.

Deployment Configuration

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

Common Fields

Field	Type	Required	Description
`name`	string	✅	Deployment name (must be unique)
`type`	string	✅	Deployment type (case-insensitive)

Standalone Configuration

deployments:
  - id: string                      # Required - Unique deployment ID
    name: string                    # Required - Unique name
    type: "standalone"              # Required
    redis_url: string               # Required - Redis connection URL
    credentials:                    # Optional - Authentication
      password: string              # Optional - Redis password

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}"

Enterprise 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: false)
      enterprise_admin_url: string  # Optional - Admin UI URL for reference
    enterprise:                     # Optional - Enterprise options
      db_endpoint: string           # Optional - Database endpoint style (external_ip, internal_ip, dns)
    credentials:                    # Required - Authentication
      rest_api:                     # Can also use 'enterprise_api' for compatibility
        basic_auth: string          # Required - "username:password" format

Note: Both rest_api and enterprise_api field names are supported 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"  # Optional UI reference
    enterprise:
      db_endpoint: "external_ip"
    credentials:
      rest_api:  # or 'enterprise_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
      sentinel_password: string     # Optional - Sentinel password (if different)

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}"
      sentinel_password: "${SENTINEL_PASSWORD}"

Complete Example

# Agent configuration
agent:
  id: "radar-agent-001"
  collection_interval: "60s"

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

# Deployment configurations
deployments:
  # Enterprise cluster
  - id: "ent-01"
    name: "enterprise-production"
    type: "enterprise"
    rest_api:
      host: "cluster.redis.local"
      port: 9443
      use_tls: true
      insecure: false
      enterprise_admin_url: "https://cluster.redis.local:8443"  # Optional
    enterprise:
      db_endpoint: "external_ip"
    credentials:
      rest_api:  # or enterprise_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 Variable Expansion

Configuration values can reference environment variables:

${VAR} - Value must be set
${VAR:-default} - Use default if not set

Example:

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

deployments:
  - id: "redis-01"
    name: "redis"
    type: "standalone"
    redis_url: "${REDIS_URL:-redis://localhost:6379}"
    credentials:
      password: "${REDIS_PASSWORD}"

Environment Variable Overrides

Configuration can be overridden using environment variables:

Global Settings

export GRPC_ENDPOINT=https://grpc.radar.redis.io:443
export COLLECTION_INTERVAL=30
export RADAR_API_KEY=your-api-key  # For authentication

Per-Deployment Settings

For Enterprise deployments (using the id field):

# For deployment with id: "ent-01"
export RADAR_ENTERPRISE_ENT_01_REST_API_URL=https://new-url:9443
export RADAR_ENTERPRISE_ENT_01_USERNAME=newuser
export RADAR_ENTERPRISE_ENT_01_PASSWORD=newpass
export RADAR_ENTERPRISE_ENT_01_INSECURE=true

For single Standalone deployment:

export REDIS_HOST=redis.example.com
export REDIS_PORT=6379
export REDIS_PASSWORD=secret

Authentication

The agent requires authentication with the Radar server:

Via configuration:

server:
  api_key: "your-api-key"  # Automatically sets ACCESS_KEY

Via environment variable:
```
export ACCESS_KEY=your-api-key
```

The agent will automatically set the ACCESS_KEY environment variable from the config's api_key field if not already set.

Validation

Validate your configuration:

# Validate entire configuration
radar-agent --validate

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

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

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

Migration from Legacy Formats

Old Format (pre-v2)

# Old format
grpc_endpoint: "http://localhost:50051"
deployments:
  - name: "enterprise"
    type: "enterprise"
    rest_api_url: "https://host:9443"
    username: "admin"
    password: "pass"

New Format (v2+)

# New format
server:
  grpc_endpoint: "http://localhost:50051"
  api_key: "your-key"

deployments:
  - name: "enterprise"
    type: "enterprise"  # Now case-insensitive
    id: "ent-01"
    credentials:
      rest_api:  # or enterprise_api for compatibility
        url: "https://host:9443"
        username: "admin"
        password: "pass"
        insecure: true  # For self-signed certs

Removed Fields

These fields are no longer supported:

send_interval - Removed for simplicity
max_batch_size - Removed for simplicity
auto_discover - Not implemented

Command Line Reference

Synopsis

radar-agent [OPTIONS] [COMMAND]

Global Options

Option	Environment	Description	Default
`-c, --config <PATH>`	-	Configuration file path	`radar-agent.yml`
`--json-logs`	-	Enable JSON formatted logs	false
`-l, --log-level <LEVEL>`	`RUST_LOG`	Log level: trace, debug, info, warn, error	`info`
`--once`	-	Run once and exit	false
`--dry-run`	-	Collect but don't submit	false
`--validate`	-	Validate config and exit	false
`--output-file [PATH]`	-	Write collection to file (offline mode). Auto-generates filename if PATH not specified	-
`--output-dir <DIR>`	-	Override default output directory for offline collections	-
`--redact <LEVEL>`	-	Redaction level: none, credentials, all	`all`

Subcommands

validate

Validate a specific deployment configuration and test connectivity.

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

# With custom config
radar-agent --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-agent test --deployment my-redis

# Test with debug logging
radar-agent --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-agent submit --file /path/to/collection.json

# With custom config for server settings
radar-agent --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-agent

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

# Run once and exit
radar-agent --once

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

Offline Collection

# Collect to auto-generated file with full redaction
radar-agent --once --output-file

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

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

# Collect with credentials-only redaction
radar-agent --once --output-file --redact credentials

# Collect with no redaction (debug only)
radar-agent --once --output-file --redact none

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

Validation

# Validate entire configuration
radar-agent --validate

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

Debugging

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

# JSON formatted logs
radar-agent --json-logs

# Test collection without submission
radar-agent --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):

# Enterprise deployment with ID "ent-01"
export ENT_01_REST_API_URL=https://enterprise:9443
export ENT_01_USERNAME=admin
export ENT_01_PASSWORD=secret
export ENT_01_INSECURE=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-agent
RUST_LOG=radar_agent=debug,tonic=warn radar-agent

Exit Codes

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

Signal Handling

The agent handles the following signals gracefully:

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

During shutdown:

Current collection completes
Pending submissions are sent
Connections are closed
Final metrics are logged

Keyboard shortcuts

Radar Agent Documentation