Server Pulse

Monitor Django and other web services directly from VS Code. Server Pulse displays real-time service status in your status bar, automatically detects errors from logs (including Python tracebacks), and supports Docker container monitoring.

Features

🔍 Intelligent Log Monitoring

• Python Traceback Parsing: Automatically detects and parses Python tracebacks, including:
  • Standard Traceback (most recent call last): format
  • Exception in thread format (e.g., Django threading errors)
  • Chained exceptions with During handling of the above exception messages
• Multi-Stream Processing: Separate handling of stdout and stderr streams prevents interference
• ANSI Code Handling: Automatically strips ANSI escape codes and Docker container prefixes for clean pattern matching

🐳 Docker Support

• Automatic Detection: Finds docker-compose.yml files and auto-detects running containers
• Live Log Streaming: Monitors container logs via docker logs -f command
• Container Prefix Normalization: Strips container prefixes (e.g., web-1 | ) from log lines
• Smart Container Name Prediction: Automatically predicts container names for services without explicit container_name
• Custom vs Predicted Names: Clear UI indication of custom vs auto-generated container names

🎯 Service State Detection

• Pattern-Based Matching: Configurable regex patterns detect service states:
  • Starting: Service initialization detected
  • Ready: Service is running and accepting connections
  • Restarting: File changes or manual restart detected
  • Error: Errors, exceptions, or tracebacks detected
• Django Auto-Detection: Automatically finds Django projects via manage.py

🏥 Health Monitoring

• Flexible Health Checks: Choose between TCP port checks or HTTP health endpoints
• Adaptive Checking: Fast checks during startup/errors, slow checks when stable
• Per-Service Configuration: Enable/disable health checks per service

📊 Real-Time Status Bar

• Visual Indicators: Icons and colors show current service state at a glance
• Detailed Tooltips: Hover for uptime, port info, and last error
• Multi-Service Support: Monitor multiple services simultaneously

Installation

From VS Code Marketplace

1. Open VS Code
2. Press Ctrl+P / Cmd+P
3. Type ext install ubpat16.serverpulse
4. Press Enter

From Source

git clone https://github.com/ubpat16/serverpulse.git
cd serverpulse
npm install
npm run compile
# Press F5 to launch Extension Development Host

Quick Start

Automatic Service Detection

Server Pulse automatically detects services in your workspace:

1. Django Projects: Finds manage.py files and detects Django applications
2. Docker Services: Finds docker-compose.yml files and parses service configurations
3. Interactive Setup: When first opened, prompts you to configure detected services

The extension will show a setup wizard on first use, allowing you to:

• Select which detected services to monitor
• Choose specific Docker containers from compose files
• Configure health check endpoints and ports

Manual Configuration

You can also manually configure services in VS Code settings (Ctrl+, / Cmd+,):

{
  "serverpulse.services": [
    {
      "name": "My Django App",
      "type": "django",
      "port": 8000,
      "healthCheckPath": "/health/"
    }
  ]
}

Configuration

Basic Service Configuration

{
  "serverpulse.services": [
    {
      "name": "API Server",
      "type": "django",
      "port": 8000,
      "logFile": "/path/to/logs/django.log",
      "healthCheckPath": "/api/health/",
      "enableHealthCheck": true
    }
  ]
}

Docker-Based Service

{
  "serverpulse.services": [
    {
      "name": "web",
      "type": "django",
      "port": 8000,
      "useDocker": {
        "pathToComposeFile": "${workspaceFolder}/docker-compose.yml",
        "selectedContainerName": "web"
      }
    }
  ]
}

Server Pulse will automatically run docker logs web -f to monitor container output.

Container Name Handling: If your docker-compose.yml doesn't specify container_name for a service, Server Pulse will predict the container name (typically {service_name}_1). The setup wizard clearly indicates whether a container name is custom or predicted.

Custom Log Patterns

{
  "serverpulse.logPatterns": {
    "django": {
      "starting": "Starting development server|runserver|Starting ASGI",
      "ready": "Starting development server at|Listening on TCP",
      "restarting": "Watching for file changes|Reloading",
      "error": "Traceback|ERROR|CRITICAL|Exception"
    }
  }
}

Configuration Options

Global Settings

Setting	Type	Default	Description
serverpulse.autoDetect	boolean	true	Auto-detect Django servers via manage.py
serverpulse.checkInterval	number	5	Port check interval in seconds (1-60)
serverpulse.enableHealthCheck	boolean	true	Enable HTTP health checks globally
serverpulse.defaultHealthCheckPath	string	""	Default health check path for all services

Service Configuration

Property	Type	Required	Description
name	string	✓	Service identifier shown in status bar
type	string	✓	Service type: "django" or "generic"
port	number	✓	Port number to monitor
logFile	string		Path to log file to watch
healthCheckPath	string		HTTP endpoint for health checks (e.g., /health/)
enableHealthCheck	boolean		Override global health check setting
logPatterns	object		Custom regex patterns for state detection
useDocker	object		Docker configuration (see Docker section)
logServers	array		Custom log server commands

Docker Configuration (useDocker)

Property	Type	Description
pathToComposeFile	string	Path to docker-compose.yml (supports ${workspaceFolder})
selectedContainerName	string	Container name to monitor

Commands

Access commands via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• Server Pulse: Refresh Service Detection - Re-scan for services
• Server Pulse: Configure Services - Open settings
• Server Pulse: Show Service Logs - View service status details

Architecture

Server Pulse consists of several coordinated components:

┌─────────────────────────────────────────────────────────┐
│                     Extension Host                       │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────┐    ┌──────────────┐                  │
│  │ LogWatcher   │───▶│ Traceback    │                  │
│  │              │    │ Parser       │                  │
│  │ - File Watch │    └──────────────┘                  │
│  │ - Docker Logs│                                       │
│  │ - Streams    │    ┌──────────────┐                  │
│  └──────────────┘    │ PortChecker  │                  │
│         │            │              │                  │
│         │            │ - TCP Check  │                  │
│         │            │ - HTTP Health│                  │
│         │            └──────────────┘                  │
│         │                   │                           │
│         └───────┬───────────┘                           │
│                 ▼                                       │
│         ┌──────────────┐                               │
│         │ Status       │                               │
│         │ Manager      │                               │
│         │              │                               │
│         │ - State      │                               │
│         │ - Uptime     │                               │
│         └──────────────┘                               │
│                 │                                       │
│                 ▼                                       │
│         ┌──────────────┐                               │
│         │ StatusBar    │                               │
│         │ (UI)         │                               │
│         └──────────────┘                               │
│                                                           │
└─────────────────────────────────────────────────────────┘

• LogWatcher: Monitors log files, Docker containers, and command output
• TracebackParser: Intelligently parses Python tracebacks from log streams
• PortChecker: Performs TCP/HTTP health checks at configurable intervals
• StatusManager: Coordinates log events and port checks to determine overall state
• StatusBar: Displays service status with visual indicators in VS Code status bar
• ServiceDetectionService: Automatically discovers Django projects and Docker configurations
• ServiceConfigurationManager: Handles interactive service setup and configuration management
• Logger: Centralized logging and user notification system

Interactive Setup

Server Pulse includes an interactive setup wizard that runs when you first open a workspace with detectable services.

First-Time Setup Process

1. Auto-Detection: The extension scans your workspace for:

   • Django projects (manage.py files)
   • Docker Compose configurations (docker-compose.yml files)

2. Service Selection: Choose which detected services to monitor from a quick-pick menu

3. Container Selection (for Docker Compose): Select specific containers from your compose file. The UI shows:

   • Custom container names (from container_name in compose file)
   • Predicted container names (auto-generated, e.g., web_1)

4. Health Check Configuration: Set up health monitoring:

   • Port number for the service
   • HTTP health check endpoint (optional)

Container Name Prediction

For Docker Compose services without explicit container_name:

• Server Pulse predicts: {service_name}_1
• Example: web service → web_1 container
• The setup wizard clearly indicates predicted vs. custom names

Troubleshooting

Service Not Detected

Problem: Django service not showing in status bar

Solutions:

• Ensure manage.py exists in workspace
• Check that serverpulse.autoDetect is enabled
• Try manually configuring the service in settings
• Run "Server Pulse: Refresh Service Detection" command

Docker Logs Not Working

Problem: Docker container logs not being monitored

Solutions:

• Verify Docker is running: docker ps
• Check container name matches selectedContainerName
• Ensure docker-compose.yml path is correct
• Verify user has Docker permissions
• Container Name Issues: If using predicted container names, verify they match actual running containers. Add explicit container_name to your compose file for reliability

Patterns Not Matching

Problem: Service state not updating when logs appear

Solutions:

1. Open VS Code Developer Console (Help > Toggle Developer Tools)
2. Look for [LogWatcher] messages showing:
   • Initialized with patterns: - Verify patterns loaded
   • Checking line against patterns: - See what lines are checked
   • Matched X pattern - Confirm pattern matches
3. Check for container prefixes: logs like web-1 | Starting... are automatically normalized
4. Verify regex patterns in configuration are valid

Error State Not Showing

Problem: Traceback appears but status shows "Starting" or "Ready"

Solutions:

• Check console for [LogWatcher] Collecting traceback messages
• Ensure traceback ends with a line like Exception: or Error:
• Verify the error pattern includes Traceback and Exception
• Check if port health check is overriding error state

Debug Logging

Enable detailed logging by opening VS Code Developer Console:

1. Go to Help > Toggle Developer Tools
2. Select Console tab
3. Filter by LogWatcher, StatusManager, or TracebackParser
4. Look for state transitions and pattern matching activity

Common log messages:

• [LogWatcher] Initialized with patterns: - Pattern configuration
• [LogWatcher] Collecting traceback - Traceback detection in progress
• [LogWatcher] Parsed traceback from - Completed traceback
• [LogWatcher] Matched X pattern - Pattern successfully matched
• [StatusManager] Log state change: - State transition details

Examples

Django with Docker Compose

{
  "serverpulse.services": [
    {
      "name": "Django API",
      "type": "django",
      "port": 8000,
      "useDocker": {
        "pathToComposeFile": "${workspaceFolder}/docker-compose.yml",
        "selectedContainerName": "web"
      },
      "healthCheckPath": "/api/health/"
    }
  ]
}

Note: If your docker-compose.yml doesn't specify container_name, Server Pulse will predict the container name (usually {service_name}_1). During setup, you'll see clear indicators of whether container names are custom or predicted.

Multiple Services

{
  "serverpulse.services": [
    {
      "name": "Backend",
      "type": "django",
      "port": 8000,
      "healthCheckPath": "/health/"
    },
    {
      "name": "Frontend",
      "type": "generic",
      "port": 3000,
      "logPatterns": {
        "starting": "webpack.*compiling",
        "ready": "Compiled successfully|Local:.*http",
        "error": "Failed to compile|ERROR"
      }
    }
  ]
}

TCP-Only Monitoring (No HTTP)

{
  "serverpulse.services": [
    {
      "name": "Redis",
      "type": "generic",
      "port": 6379,
      "enableHealthCheck": false
    }
  ]
}

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for version history and release notes.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Requirements

• VS Code 1.74.0 or higher
• Docker (optional, for container monitoring)
• Python/Django (for Django-specific features)

---

Made with ❤️ for developers who want to keep an eye on their services without leaving their editor.