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

bash

# 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:

bash

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

Options:

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

Examples:

bash

# 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:

bash

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:

bash

# 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:

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

`restart` - Restart Server

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

Usage:

bash

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:

bash

# 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:

bash

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

Options:

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

Examples:

bash

# 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

bash

~/.blueplane/server.log

Common Log Commands

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

code

~/.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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

•
Always use daemon mode for long-running operation
bash
```
python scripts/server_ctl.py restart --daemon
```

•

Use foreground mode when debugging

bash

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

•

Check status after restart

bash

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

•

Monitor logs after changes

bash

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

•

Graceful shutdown preferred over force

bash

# Good
python scripts/server_ctl.py stop

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

•

Use verbose mode for detailed debugging

bash

python scripts/server_ctl.py status --verbose

Integration with Development

Git Workflow

After pulling changes:

bash

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

Testing Changes

bash

# 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:

bash

# 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

code

~/.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:

python

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

Blueplane Server Management

Overview

Quick Reference

Commands

start - Start Server

stop - Stop Server

restart - Restart Server

status - Check Server Status

Log Management

Log File Location

Common Log Commands

Log Levels

Background Log Monitoring

System Health Checks

Check Redis Streams

Check Database

Check Process

Typical Workflows

Development Workflow

Debugging Issues

Production Deployment

After Configuration Changes

Important Files & Directories

Troubleshooting

Server Won't Start

Server Won't Stop

Server Running But Not Processing

High CPU/Memory Usage

Best Practices

Integration with Development

Git Workflow

Testing Changes

Pre-commit

Database Overview

Storage Architecture

SQLite Database Schema

1. claude_raw_traces - Claude Code Events

2. cursor_raw_traces - Cursor Events

3. conversations - Unified Conversations Table

4. cursor_sessions - Cursor IDE Sessions

Redis Streams

Decompressing Event Data

See Also

`start` - Start Server

`stop` - Stop Server

`restart` - Restart Server

`status` - Check Server Status

1. `claude_raw_traces` - Claude Code Events

2. `cursor_raw_traces` - Cursor Events

3. `conversations` - Unified Conversations Table

4. `cursor_sessions` - Cursor IDE Sessions