Redistail

A command-line utility for monitoring Redis messages in real-time, similar to how tail -f works for log files. Redistail supports both Redis Pub/Sub channels and Redis Streams, making it an essential tool for debugging and monitoring Redis-based applications.

Originally part of the effect-redis library, it is now available as a standalone package for easier installation and use.

Table of Contents

• Installation
• Quick Start
• Usage
  • Pub/Sub Monitoring
  • Stream Monitoring
  • Multi-day Monitoring
• Configuration
• Examples
• Environment Variables
• Output Format
• Troubleshooting
• Advanced Usage

Installation

Global Installation

Install redistail globally to make the redistail command available everywhere on your system:

# Using npm
npm install -g @ceschiatti/redistail

# Using pnpm
pnpm add -g @ceschiatti/redistail

# Using bun
bun add -g @ceschiatti/redistail

Local Installation

If you're working within a project:

# Using npm
npm install @ceschiatti/redistail

# Using pnpm
pnpm add @ceschiatti/redistail

# Using bun
bun add @ceschiatti/redistail

# Run locally using npx
npx redistail --help

Verify Installation

redistail --version
redistail --help

Quick Start

Monitor a Pub/Sub Channel

redistail pubsub my-channel

Monitor a Redis Stream

redistail stream my-stream

Monitor a Stream from a Specific Date

redistail stream my-stream --from "2026-01-09T10:00:00Z"

With Custom Redis Connection

REDIS_HOST=redis.example.com redistail pubsub notifications

Usage

Basic Syntax

redistail <CONNECTION_TYPE> <TOPIC_NAME> [OPTIONS]

Arguments

• CONNECTION_TYPE: Either pubsub or stream
• TOPIC_NAME: The channel name (for Pub/Sub) or stream key (for Streams)

Options

• -h, --help: Show help message
• -v, --version: Show version information
• --from <date>: (Stream mode only) Retrieve messages starting from a specific date/time

Connection Types

Pub/Sub Monitoring

Monitor Redis Pub/Sub channels for real-time message broadcasting:

redistail pubsub channel-name

• Subscribes to the specified channel
• Displays messages as they are published
• Shows timestamp, channel name, and message content
• Continues running until interrupted (Ctrl+C)

Stream Monitoring

Monitor Redis Streams for persistent message queues:

redistail stream stream-name

• Reads from the stream starting from the latest entry
• Uses blocking XREAD to wait for new entries
• Shows timestamp, entry ID, and all message fields
• Maintains continuity across reconnections

Stream Date/Time Filter

Retrieve historical messages from a specific date/time and then transition to real-time monitoring:

redistail stream stream-name --from "2026-01-09T10:00:00Z"

Features:

• Retrieves all messages from the specified date/time onwards
• Displays historical messages first in chronological order
• Seamlessly transitions to real-time monitoring
• No messages are lost during the transition
• Only available for stream mode (not pub/sub)

Multi-day Stream Monitoring (Cedro Style)

Redistail features a specialized mode for monitoring daily partitioned streams (common in the Cedro protocol). If you provide a partial stream name and a date filter, Redistail will automatically traverse consecutive daily streams.

Stream Name Formats:

• Partial (3 fields): stream:<type>:<ticker> (e.g., stream:raw:WING26)
• Full (6 fields): stream:<type>:<ticker>:<year>:<month>:<day> (e.g., stream:raw:WING26:2026:01:13)

How Multi-day Monitoring Works: When you run redistail stream stream:raw:WING26 --from yesterday, Redistail will:

1. Construct the stream names for yesterday, today, and any dates in between.
2. Sequentialy read all historical messages from yesterday's stream.
3. Transition to today's stream and read its historical messages.
4. Finally, enter real-time monitoring on today's stream.

Example:

# Monitor WING26 trades starting from yesterday, automatically switching streams
redistail stream stream:raw:WING26 --from yesterday

Supported Date Formats:

# Convenient keywords
redistail stream events --from today
redistail stream events --from yesterday

# ISO 8601 format (recommended)
redistail stream events --from "2026-01-09T10:00:00Z"
redistail stream events --from "2026-01-09"

# RFC 2822 format
redistail stream events --from "Fri, 09 Jan 2026 10:00:00 GMT"

# Simple date formats
redistail stream events --from "Jan 9 2026"
redistail stream events --from "2026/01/09"

Use Cases:

1. Debugging: Review messages from when an issue started

   redistail stream error-logs --from "2026-01-09T14:30:00Z"

2. Audit Trail: Check all events since a specific time

   redistail stream user-actions --from "2026-01-09"

3. Replay Events: Process historical events and continue with new ones

   redistail stream orders --from "2026-01-09T00:00:00Z" | ./process-orders.sh

4. Gap Analysis: Catch up on missed messages

   # Get messages from the last hour
   redistail stream notifications --from "2026-01-09T20:00:00Z"

Behavior:

• Future Date: If the date is in the future, a warning is logged and monitoring starts from the latest entry
• Old Date: If the date is before the oldest message, all available messages are retrieved
• Empty Stream: If no messages exist, monitoring proceeds directly to real-time mode
• Invalid Format: Clear error message with examples of valid formats

Examples:

# Get all messages from today (starting at midnight)
redistail stream events --from today

# Get all messages from yesterday
redistail stream logs --from yesterday

# Get messages from today at midnight
redistail stream events --from "2026-01-09T00:00:00Z"

# Get messages from the last 24 hours
redistail stream logs --from "2026-01-08"

# Combine with environment variables
REDIS_HOST=prod.redis.com redistail stream orders --from "Jan 9 2026"

Error Handling:

# Invalid date format
$ redistail stream events --from "invalid-date"
❌ CLI Error: Invalid date format: "invalid-date". Supported formats:
  - Keywords: "today" or "yesterday"
  - ISO 8601: "2026-01-09T10:00:00Z" or "2026-01-09"
  - RFC 2822: "Fri, 09 Jan 2026 10:00:00 GMT"
  - Simple: "Jan 9 2026" or "2026/01/09"

# Using --from with pubsub (not supported)
$ redistail pubsub channel --from "2026-01-09"
❌ CLI Error: The --from option is only available for stream mode, not pubsub mode

# Missing date value
$ redistail stream events --from
❌ CLI Error: The --from option requires a date argument. Example: --from "2026-01-09T10:00:00Z"

Configuration

Redistail can be configured through environment variables to work with different Redis instances and customize display options.

Redis Connection

Configure Redis connection settings:

# Basic connection
export REDIS_HOST=localhost
export REDIS_PORT=6379

# Or use a complete connection URL
export REDIS_URL=redis://username:[email protected]:6380

# Connection timeouts and retries
export REDIS_TIMEOUT=5000
export REDIS_RETRY_ATTEMPTS=3
export REDIS_RETRY_DELAY=1000

Display Options

Customize output formatting:

# Enable/disable colored output
export REDISTAIL_COLORS=true

# Enable/disable timestamps
export REDISTAIL_TIMESTAMPS=true

# Enable/disable JSON pretty-printing
export REDISTAIL_PRETTY_JSON=true

Monitoring Options

Configure monitoring behavior:

# Blocking timeout for stream reads (milliseconds)
export REDISTAIL_BLOCK_TIMEOUT=5000

# Maximum reconnection attempts
export REDISTAIL_MAX_RECONNECT_ATTEMPTS=5

Examples

Basic Pub/Sub Monitoring

Monitor a simple notification channel:

redistail pubsub notifications

Output:

2024-01-07 15:30:45.123 [notifications] Welcome to the system!
2024-01-07 15:30:47.456 [notifications] New user registered: [email protected]
2024-01-07 15:30:50.789 [notifications] System maintenance scheduled for tonight

Multi-day Data Recovery

Recover missed trade data from a partial stream name starting from a past date:

# Get all WING26 raw data from the last 3 days and switch to real-time
redistail stream stream:raw:WING26 --from "2026-01-16"

Output:

📅 Multi-day mode: stream:raw:WING26 from 2026-01-16T00:00:00.000Z
⏳ Iterating through daily streams, then transitioning to real-time...
🔗 Connected to Stream: stream:raw:WING26:2026:01:16
... (historical messages from Jan 16)
🔗 Connected to Stream: stream:raw:WING26:2026:01:17
... (historical messages from Jan 17)
🔗 Connected to Stream: stream:raw:WING26:2026:01:18
... (historical messages from Jan 18)
📡 Transitioning to real-time monitoring...

Stream Monitoring with JSON Messages

Monitor a stream containing structured data:

redistail stream user-events

Output:

2024-01-07 15:31:12.345 [user-events:1704636672345-0] event=login user=alice timestamp=1704636672345
2024-01-07 15:31:15.678 [user-events:1704636675678-0] event=purchase user=bob amount=29.99 product=premium-plan
2024-01-07 15:31:18.901 [user-events:1704636678901-0] event=logout user=alice session_duration=300

Remote Redis Instance

Connect to a remote Redis server:

REDIS_HOST=redis.production.com REDIS_PORT=6380 redistail pubsub alerts

Authenticated Redis Connection

Use Redis with authentication:

REDIS_URL=redis://myuser:[email protected]:6379 redistail stream orders

Custom Display Settings

Monitor with custom formatting:

# Disable colors and timestamps for clean output
REDISTAIL_COLORS=false REDISTAIL_TIMESTAMPS=false redistail pubsub logs

JSON Message Pretty-Printing

When messages contain JSON, redistail automatically formats them:

redistail pubsub api-events

Input message: {"user":"alice","action":"login","timestamp":1704636672345}

Output:

2024-01-07 15:31:12.345 [api-events] {
  "user": "alice",
  "action": "login",
  "timestamp": 1704636672345
}

Multiple Instances

Run multiple redistail instances to monitor different channels:

# Terminal 1: Monitor user events
redistail stream user-events

# Terminal 2: Monitor system notifications
redistail pubsub system-notifications

# Terminal 3: Monitor error logs
redistail pubsub error-logs

Development Workflow

Common development patterns:

# Monitor application logs during development
redistail pubsub app-logs &

# Monitor user activity in another terminal
redistail stream user-activity &

# Start your application
npm run dev

# Stop monitoring (kill background processes)
jobs
kill %1 %2

Environment Variables

Redis Connection Variables

| Variable | Default | Description | |----------|---------|-------------| | REDIS_HOST | 127.0.0.1 | Redis server hostname | | REDIS_PORT | 6379 | Redis server port | | REDIS_URL | - | Complete Redis connection URL (overrides host/port) | | REDIS_TIMEOUT | 5000 | Connection timeout in milliseconds | | REDIS_RETRY_ATTEMPTS | 3 | Number of connection retry attempts | | REDIS_RETRY_DELAY | 1000 | Delay between retry attempts in milliseconds |

Display Variables

| Variable | Default | Description | |----------|---------|-------------| | REDISTAIL_COLORS | true | Enable colored output | | REDISTAIL_TIMESTAMPS | true | Show timestamps in output | | REDISTAIL_PRETTY_JSON | true | Pretty-print JSON content |

Monitoring Variables

| Variable | Default | Description | |----------|---------|-------------| | REDISTAIL_BLOCK_TIMEOUT | 5000 | Stream blocking timeout in milliseconds | | REDISTAIL_MAX_RECONNECT_ATTEMPTS | 5 | Maximum reconnection attempts |

Configuration Examples

Production Environment

# .env.production
REDIS_URL=redis://prod-user:[email protected]:6380
REDISTAIL_COLORS=false
REDISTAIL_TIMESTAMPS=true
REDISTAIL_MAX_RECONNECT_ATTEMPTS=10

Development Environment

# .env.development
REDIS_HOST=localhost
REDIS_PORT=6379
REDISTAIL_COLORS=true
REDISTAIL_PRETTY_JSON=true
REDISTAIL_BLOCK_TIMEOUT=1000

CI/CD Environment

# Minimal output for automated systems
REDISTAIL_COLORS=false
REDISTAIL_TIMESTAMPS=false
REDISTAIL_PRETTY_JSON=false

Output Format

Pub/Sub Messages

[TIMESTAMP] [CHANNEL] MESSAGE_CONTENT

Example:

2024-01-07 15:30:45.123 [notifications] User alice logged in

Stream Messages

[TIMESTAMP] [STREAM_KEY:ENTRY_ID] FIELD1=VALUE1 FIELD2=VALUE2 ...

Example:

2024-01-07 15:31:12.345 [events:1704636672345-0] user=alice action=login ip=192.168.1.100

Color Coding

When colors are enabled (REDISTAIL_COLORS=true):

• Gray: Timestamps
• Cyan: Pub/Sub channel names
• Magenta: Stream names and entry IDs
• Yellow: Field names in streams
• White: Message content and field values
• Red: Error messages

Error Messages

Errors are displayed on stderr with clear descriptions:

❌ Error: Connection failed to redis://localhost:6379
❌ Error: Invalid topic name: cannot be empty
❌ Error: Maximum retry attempts (5) exceeded

Troubleshooting

Common Issues

Connection Refused

Problem: Error: Connection failed to redis://localhost:6379

Solutions:

1. Verify Redis is running: redis-cli ping
2. Check Redis configuration: redis-cli info server
3. Verify host and port: REDIS_HOST=localhost REDIS_PORT=6379 redistail --help
4. Test with redis-cli: redis-cli -h localhost -p 6379 ping

Authentication Failed

Problem: Error: Authentication failed

Solutions:

1. Include credentials in URL: REDIS_URL=redis://user:pass@host:port
2. Check Redis AUTH configuration: redis-cli config get requirepass
3. Verify username/password are correct

No Messages Appearing

Problem: Redistail connects but shows no messages

Solutions:

1. Verify the channel/stream exists:

   # For Pub/Sub
   redis-cli publish test-channel "test message"
      
   # For Streams
   redis-cli xadd test-stream * field value

2. Check if you're monitoring the correct topic name
3. Ensure messages are being published to the topic
4. For streams, verify entries exist: redis-cli xlen stream-name

Permission Denied

Problem: Error: Permission denied for command

Solutions:

1. Check Redis ACL permissions: redis-cli acl whoami
2. Verify user has subscribe permissions: redis-cli acl getuser username
3. Use a user with appropriate permissions

High Memory Usage

Problem: Redistail consuming too much memory

Solutions:

1. Reduce block timeout: REDISTAIL_BLOCK_TIMEOUT=1000
2. Monitor smaller streams or channels
3. Disable JSON pretty-printing: REDISTAIL_PRETTY_JSON=false
4. Use multiple instances for different topics instead of one large stream

Network Issues

Intermittent Disconnections

Problem: Frequent connection drops

Solutions:

1. Increase retry attempts: REDISTAIL_MAX_RECONNECT_ATTEMPTS=10
2. Adjust retry delay: REDIS_RETRY_DELAY=2000
3. Check network stability between client and Redis server
4. Monitor Redis server logs for connection issues

Slow Performance

Problem: Messages appear with delay

Solutions:

1. Reduce block timeout: REDISTAIL_BLOCK_TIMEOUT=1000
2. Check Redis server performance: redis-cli --latency
3. Monitor network latency: ping redis-host
4. Verify Redis server isn't overloaded: redis-cli info stats

Configuration Issues

Environment Variables Not Working

Problem: Environment variables seem to be ignored

Solutions:

1. Verify variable names are correct (case-sensitive)
2. Export variables in current shell: export REDIS_HOST=myhost
3. Check variable values: echo $REDIS_HOST
4. Use inline variables: REDIS_HOST=myhost redistail pubsub test

Colors Not Displaying

Problem: Output appears without colors

Solutions:

1. Enable colors explicitly: REDISTAIL_COLORS=true
2. Check terminal color support: echo $TERM
3. Test with a color-supporting terminal
4. Verify output isn't being piped: redistail pubsub test | cat (disables colors)

Debugging Steps

Enable Verbose Logging

While redistail doesn't have a verbose mode, you can debug connection issues:

# Test Redis connection manually
redis-cli -h $REDIS_HOST -p $REDIS_PORT ping

# Monitor Redis server logs
redis-cli monitor

# Check Redis configuration
redis-cli config get "*"

Test with Simple Commands

# Test basic connectivity
redis-cli ping

# Test pub/sub manually
redis-cli subscribe test-channel
# In another terminal:
redis-cli publish test-channel "hello"

# Test streams manually
redis-cli xadd test-stream * message "hello"
redis-cli xread STREAMS test-stream 0

Check System Resources

# Check available memory
free -h

# Check network connectivity
netstat -an | grep 6379

# Check process limits
ulimit -a

Getting Help

If you encounter issues not covered here:

1. Check the GitHub Issues
2. Review Redis server logs
3. Test with the standard redis-cli tool first
4. Create a minimal reproduction case
5. Include environment details (OS, Redis version, Node.js version)

Performance Tips

Optimize for High-Volume Streams

# Reduce output overhead
REDISTAIL_COLORS=false REDISTAIL_TIMESTAMPS=false redistail stream high-volume

# Use shorter block timeouts
REDISTAIL_BLOCK_TIMEOUT=100 redistail stream fast-stream

# Monitor specific time ranges (use redis-cli for historical data)
redis-cli xrange stream-name - + COUNT 100

Monitor Multiple Topics Efficiently

# Use separate processes for different priorities
redistail pubsub critical-alerts &
redistail pubsub info-logs > /dev/null &  # Discard low-priority output

Advanced Usage

Integration with Other Tools

Log Aggregation

# Send output to syslog
redistail pubsub app-logs | logger -t redistail

# Append to log files with timestamps
redistail stream events >> /var/log/redis-events.log

# Filter and process messages
redistail pubsub notifications | grep "ERROR" | mail -s "Redis Errors" [email protected]

Monitoring and Alerting

# Count messages per minute
redistail pubsub events | pv -l -i 60 > /dev/null

# Alert on specific patterns
redistail stream errors | grep "CRITICAL" | while read line; do
  echo "Critical error detected: $line" | mail -s "ALERT" [email protected]
done

# Integration with monitoring systems
redistail pubsub metrics | while read metric; do
  curl -X POST http://monitoring-system/api/metrics -d "$metric"
done

Development Workflows

# Auto-restart on configuration changes
while inotifywait -e modify redis.conf; do
  pkill redistail
  redistail pubsub app-logs &
done

# Conditional monitoring based on environment
if [ "$NODE_ENV" = "development" ]; then
  REDISTAIL_COLORS=true redistail stream debug-events
else
  REDISTAIL_COLORS=false redistail stream production-events | logger
fi

Scripting Examples

Bash Script for Multiple Channels

#!/bin/bash
# monitor-all.sh

CHANNELS=("user-events" "system-logs" "error-alerts")
PIDS=()

# Start monitoring each channel
for channel in "${CHANNELS[@]}"; do
  redistail pubsub "$channel" > "/var/log/redis-$channel.log" &
  PIDS+=($!)
  echo "Started monitoring $channel (PID: $!)"
done

# Wait for interrupt
trap 'kill "${PIDS[@]}"; exit' INT TERM

# Keep script running
wait

Python Integration

#!/usr/bin/env python3
import subprocess
import json
import sys

def monitor_json_stream(stream_name):
    """Monitor a Redis stream and parse JSON messages."""
    cmd = ['redistail', 'stream', stream_name]
    env = {'REDISTAIL_COLORS': 'false', 'REDISTAIL_TIMESTAMPS': 'false'}
    
    with subprocess.Popen(cmd, stdout=subprocess.PIPE, 
                         stderr=subprocess.PIPE, text=True, env=env) as proc:
        try:
            for line in proc.stdout:
                try:
                    # Parse redistail output and extract JSON
                    parts = line.strip().split(' ', 2)
                    if len(parts) >= 3:
                        message_data = parts[2]
                        # Process the message
                        print(f"Processed: {message_data}")
                except Exception as e:
                    print(f"Error processing line: {e}", file=sys.stderr)
        except KeyboardInterrupt:
            proc.terminate()

if __name__ == "__main__":
    monitor_json_stream("api-events")

This comprehensive documentation covers all aspects of using the redistail CLI tool, from basic usage to advanced integration scenarios, troubleshooting common issues, and providing practical examples for different use cases.