Blueplane Server Management

Overview

The Blueplane telemetry processing server is controlled via scripts/server_ctl.py. This skill covers all server lifecycle operations, log monitoring, and status checking.

Quick Reference

# Start/Stop/Restart
python scripts/server_ctl.py start              # Start in foreground
python scripts/server_ctl.py start --daemon     # Start in background (daemon)
python scripts/server_ctl.py stop               # Graceful shutdown
python scripts/server_ctl.py stop --force       # Force kill
python scripts/server_ctl.py restart            # Stop then start
python scripts/server_ctl.py restart --daemon   # Restart as daemon

# Status & Monitoring
python scripts/server_ctl.py status             # Check if running
python scripts/server_ctl.py status --verbose   # Detailed status

# View Logs
tail -f ~/.blueplane/server.log                 # Live log monitoring
tail -n 100 ~/.blueplane/server.log             # Last 100 lines

Commands

start - Start Server

Starts the Blueplane telemetry processing server.

Usage:

python scripts/server_ctl.py start [--daemon] [--verbose]

Options:

• --daemon, -d: Run server in background (daemon mode)
• --verbose, -v: Enable verbose output

Examples:

# Start in foreground (good for debugging)
python scripts/server_ctl.py start

# Start as daemon (good for production)
python scripts/server_ctl.py start --daemon
python scripts/server_ctl.py start -d

# Start with verbose output
python scripts/server_ctl.py start -d -v

When to Use:

• Foreground: When debugging, testing, or need immediate feedback
• Daemon: For long-running operation, production, or background processing

stop - Stop Server

Gracefully stops the running server with optional force kill.

Usage:

python scripts/server_ctl.py stop [--force] [--timeout TIMEOUT] [--verbose]

Options:

• --force, -f: Force kill if graceful shutdown fails
• --timeout TIMEOUT, -t TIMEOUT: Timeout in seconds (default: 30)
• --verbose, -v: Enable verbose output

Examples:

# Graceful shutdown (preferred)
python scripts/server_ctl.py stop

# Force kill if stuck
python scripts/server_ctl.py stop --force
python scripts/server_ctl.py stop -f

# Custom timeout
python scripts/server_ctl.py stop --timeout 60

# Verbose stop with force fallback
python scripts/server_ctl.py stop -v -f

Shutdown Process:

1. Sends SIGTERM (graceful shutdown signal)
2. Waits for timeout period (default 30s)
3. If --force specified and still running, sends SIGKILL
4. Cleans up PID file

restart - Restart Server

Stops the server (if running) and starts it again.

Usage:

python scripts/server_ctl.py restart [--daemon] [--force] [--timeout TIMEOUT] [--verbose]

Options:

• Combines all options from stop and start
• --daemon, -d: Restart in daemon mode
• --force, -f: Force kill during stop if needed
• --timeout TIMEOUT, -t TIMEOUT: Stop timeout in seconds
• --verbose, -v: Enable verbose output

Examples:

# Restart in foreground
python scripts/server_ctl.py restart

# Restart as daemon (most common)
python scripts/server_ctl.py restart --daemon
python scripts/server_ctl.py restart -d

# Force restart with custom timeout
python scripts/server_ctl.py restart -d -f -t 60

# Verbose restart
python scripts/server_ctl.py restart -d -v

When to Restart:

• After code changes
• After configuration updates
• After Redis schema changes
• When server is unresponsive but stop alone won't work

status - Check Server Status

Check if the server is running and get health information.

Usage:

python scripts/server_ctl.py status [--verbose]

Options:

• --verbose, -v: Show detailed status information

Examples:

# Basic status check
python scripts/server_ctl.py status

# Detailed status with health checks
python scripts/server_ctl.py status --verbose
python scripts/server_ctl.py status -v

Output Includes:

• Process status (running/stopped)
• PID information
• Server uptime
• Verbose mode adds:
  • Redis connection status
  • Database file status
  • Consumer group information
  • Recent activity metrics

Log Management

Log File Location

~/.blueplane/server.log

Common Log Commands

# Watch logs in real-time (best for monitoring)
tail -f ~/.blueplane/server.log

# Last N lines
tail -n 50 ~/.blueplane/server.log      # Last 50 lines
tail -n 100 ~/.blueplane/server.log     # Last 100 lines

# Search logs
grep "ERROR" ~/.blueplane/server.log
grep "Claude Code" ~/.blueplane/server.log
grep -i "redis" ~/.blueplane/server.log  # Case insensitive

# Filter by component
grep "event_consumer" ~/.blueplane/server.log
grep "jsonl_monitor" ~/.blueplane/server.log
grep "database_monitor" ~/.blueplane/server.log

# View logs with timestamps
tail -f ~/.blueplane/server.log | grep "$(date +%Y-%m-%d)"

# Count errors
grep -c "ERROR" ~/.blueplane/server.log
grep -c "WARNING" ~/.blueplane/server.log

Log Levels

Logs use Python logging levels:

• DEBUG: Detailed diagnostic information
• INFO: General informational messages
• WARNING: Warning messages for potential issues
• ERROR: Error messages for failures
• CRITICAL: Critical failures

Background Log Monitoring

# Run tail in background and monitor periodically
tail -f ~/.blueplane/server.log &

# Kill background tail
pkill -f "tail -f.*server.log"

System Health Checks

Check Redis Streams

# Check stream lengths
redis-cli XLEN telemetry:message_queue
redis-cli XLEN telemetry:message_queue
redis-cli XLEN cdc:events

# Check consumer groups
redis-cli XINFO GROUPS telemetry:message_queue
redis-cli XINFO GROUPS cdc:events

# Check pending messages
redis-cli XPENDING telemetry:message_queue processors

Check Database

# Check database file
ls -lh ~/.blueplane/telemetry.db

# SQLite query examples
sqlite3 ~/.blueplane/telemetry.db "SELECT COUNT(*) FROM claude_raw_traces;"
sqlite3 ~/.blueplane/telemetry.db "SELECT COUNT(*) FROM cursor_raw_traces;"

Check Process

# Check if process is running
ps aux | grep server.py

# Check PID file
cat ~/.blueplane/server.pid

# Check resource usage
ps aux | grep server.py | awk '{print $3, $4, $11}'  # CPU, MEM, COMMAND

Typical Workflows

Development Workflow

# 1. Make code changes
# 2. Restart server to pick up changes
python scripts/server_ctl.py restart --daemon

# 3. Monitor logs for issues
tail -f ~/.blueplane/server.log

# 4. Check status
python scripts/server_ctl.py status --verbose

Debugging Issues

# 1. Check if server is running
python scripts/server_ctl.py status -v

# 2. View recent logs
tail -n 200 ~/.blueplane/server.log | grep -i error

# 3. Stop server
python scripts/server_ctl.py stop

# 4. Clear any stale state (optional)
rm ~/.blueplane/server.pid

# 5. Start in foreground to see live output
python scripts/server_ctl.py start

# 6. Once working, restart as daemon
python scripts/server_ctl.py restart -d

Production Deployment

# 1. Stop existing server gracefully
python scripts/server_ctl.py stop --timeout 60

# 2. Verify stopped
python scripts/server_ctl.py status

# 3. Start as daemon
python scripts/server_ctl.py start --daemon

# 4. Verify running
python scripts/server_ctl.py status --verbose

# 5. Monitor logs briefly
tail -n 50 ~/.blueplane/server.log

After Configuration Changes

# Changes to config files in ~/.blueplane/ or config/
python scripts/server_ctl.py restart --daemon

# Monitor to ensure clean restart
tail -f ~/.blueplane/server.log
# Look for "Server started successfully" message

Important Files & Directories

~/.blueplane/
├── server.log          # Main log file
├── server.pid          # PID file (JSON format with metadata)
├── telemetry.db        # SQLite database
├── config.yaml         # Configuration (if present)
└── workspace_cache.db  # Workspace mappings cache

scripts/
├── server_ctl.py       # Server control CLI (this skill)
└── start_server.py     # Actual server implementation

Troubleshooting

Server Won't Start

# Check if already running
python scripts/server_ctl.py status

# Check for stale PID file
cat ~/.blueplane/server.pid
ps aux | grep $(cat ~/.blueplane/server.pid | jq -r .pid)

# Force cleanup
python scripts/server_ctl.py stop --force
rm ~/.blueplane/server.pid

# Try starting again
python scripts/server_ctl.py start

Server Won't Stop

# Try force stop
python scripts/server_ctl.py stop --force

# If still stuck, manual kill
kill -9 $(cat ~/.blueplane/server.pid | jq -r .pid)
rm ~/.blueplane/server.pid

Server Running But Not Processing

# Check status with verbose
python scripts/server_ctl.py status --verbose

# Check Redis connection
redis-cli PING

# Check consumer groups
redis-cli XINFO GROUPS telemetry:message_queue

# Restart server
python scripts/server_ctl.py restart --daemon

High CPU/Memory Usage

# Check resource usage
ps aux | grep server.py

# Check stream lengths (may be backlog)
redis-cli XLEN telemetry:message_queue
redis-cli XLEN cdc:events

# Check logs for errors
grep -i "error\|warning" ~/.blueplane/server.log | tail -50

# Consider restarting
python scripts/server_ctl.py restart --daemon

Best Practices

1. Always use daemon mode for long-running operation

   python scripts/server_ctl.py restart --daemon
   

2. Use foreground mode when debugging

   python scripts/server_ctl.py start  # No --daemon
   

3. Check status after restart

   python scripts/server_ctl.py restart -d && sleep 2 && python scripts/server_ctl.py status -v
   

4. Monitor logs after changes

   python scripts/server_ctl.py restart -d && tail -f ~/.blueplane/server.log
   

5. Graceful shutdown preferred over force

   # Good
   python scripts/server_ctl.py stop
   
   # Only if stuck
   python scripts/server_ctl.py stop --force
   

6. Use verbose mode for detailed debugging

   python scripts/server_ctl.py status --verbose
   

Integration with Development

Git Workflow

After pulling changes:

git pull
python scripts/server_ctl.py restart --daemon
tail -f ~/.blueplane/server.log

Testing Changes

# Stop server
python scripts/server_ctl.py stop

# Run tests
pytest tests/

# Restart server
python scripts/server_ctl.py start --daemon

Pre-commit

Before committing changes that affect the server:

# Restart to verify changes work
python scripts/server_ctl.py restart --daemon

# Check logs for errors
tail -n 100 ~/.blueplane/server.log | grep -i error

# Commit if clean
git add . && git commit

Database Overview

Blueplane uses a hybrid storage approach with SQLite for persistent storage and Redis for message queuing and real-time metrics.

Storage Architecture

~/.blueplane/
├── telemetry.db        # SQLite database (primary storage)
├── server.log          # Server logs
├── server.pid          # Process ID file
└── config.yaml         # User configuration (optional)

SQLite Database Schema

The SQLite database (~/.blueplane/telemetry.db) contains the following main tables:

1. claude_raw_traces - Claude Code Events

Stores all events from Claude Code JSONL transcripts.

Key Fields:

• sequence - Auto-incrementing primary key
• event_id - Unique event identifier
• external_id - Claude session/conversation ID
• event_type - Type of event (message, tool_use, system_event, etc.)
• platform - Always 'claude_code'
• timestamp - Event timestamp
• uuid - Claude event UUID (for threading)
• parent_uuid - Parent event UUID (for threading)
• workspace_hash - Workspace identifier
• project_name - Human-readable project name
• message_role - user/assistant (for message events)
• message_model - Model used (e.g., claude-sonnet-4.5)
• input_tokens, output_tokens - Token usage
• event_data - Compressed full event (zlib)

2. cursor_raw_traces - Cursor Events

Stores all events from Cursor database monitoring.

Key Fields:

• sequence - Auto-incrementing primary key
• event_id - Unique event identifier
• external_session_id - Cursor session ID
• event_type - Type of event
• timestamp - Event timestamp
• workspace_hash - Workspace identifier
• database_table - Source table in Cursor DB
• generation_uuid - AI generation identifier
• composer_id - Composer session identifier
• bubble_id - Chat bubble identifier
• event_data - Compressed full event (zlib)

3. conversations - Unified Conversations Table

Tracks conversations across both platforms.

Key Fields:

• id - Internal conversation ID (UUID)
• session_id - NULL for Claude Code, references cursor_sessions.id for Cursor
• external_id - Platform-specific external ID
• platform - 'claude_code' or 'cursor'
• workspace_hash - Workspace identifier
• workspace_name - Human-readable workspace name
• started_at - Conversation start timestamp
• ended_at - Conversation end timestamp (NULL if active)
• interaction_count - Number of interactions
• acceptance_rate - Code acceptance rate
• total_tokens - Total tokens used
• total_changes - Total code changes

Important Platform Differences:

• Claude Code: session_id is always NULL (sessions = conversations)
• Cursor: session_id references a cursor_sessions entry

4. cursor_sessions - Cursor IDE Sessions

Stores Cursor IDE window sessions (Cursor only, no Claude Code sessions).

Key Fields:

• id - Internal session ID (UUID)
• external_session_id - Session ID from Cursor extension
• workspace_hash - Workspace identifier
• workspace_name - Human-readable workspace name
• workspace_path - Full workspace path
• started_at - Session start timestamp
• ended_at - Session end timestamp (NULL if active)

Redis Streams

Redis streams are used for message queuing and event processing:

• telemetry:message_queue - Main event stream (from capture → processing)
• telemetry:message_queue - Legacy stream name
• cdc:events - Change data capture events (database updates)

Decompressing Event Data

The event_data field in raw trace tables is compressed with zlib. To decompress and view full event data:

import sqlite3
import zlib
import json
from pathlib import Path

db_path = Path.home() / '.blueplane' / 'telemetry.db'
conn = sqlite3.connect(str(db_path))

# Get an event
cursor = conn.execute("""
    SELECT event_data FROM claude_raw_traces
    WHERE sequence = ?
""", (1,))

row = cursor.fetchone()
if row:
    compressed_data = row[0]
    decompressed = zlib.decompress(compressed_data)
    event = json.loads(decompressed)
    print(json.dumps(event, indent=2))

See Also

• Redis Streams: Check stream health and consumer groups
• Database Schema: Check SQLite database for data integrity
• Configuration: ~/.blueplane/config.yaml or config/config.yaml
• Log Analysis: Search and filter logs for specific issues
• Session & Conversation Schema: See docs/SESSION_CONVERSATION_SCHEMA.md for detailed schema design