OpenSkillIndex← back to search
claude-codedevops

Claude-skill-registry blueplane

Manage Blueplane telemetry server using server_ctl.py for starting, stopping, restarting, viewing logs, and checking system status. Essential for development workflow and debugging.

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/blueplane" ~/.claude/skills/majiayu000-claude-skill-registry-blueplane && rm -rf "$T"
manifest: skills/data/blueplane/SKILL.md
tags
#server-management#telemetry#python#debugging#automation
source content

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