debug-log-server 0.1.0

Debug log collection and query service based on FastAPI

Debug Log Server

Debug log collection and query service based on FastAPI.

📦 Installation

From PyPI

pip install debug-log-server

From Source

git clone https://github.com/dengshihub/debuglogger.git
cd debuglogger/backend
pip install -e .

🚀 Quick Start

Start Server

# Basic usage
debug-log-server

# With custom log directory
DEBUG_LOG_DIR=/var/log/debug-logs debug-log-server

# With custom port
debug-log-server --port 9000

# With custom host and port
debug-log-server --host 0.0.0.0 --port 8000

Environment Variables

• DEBUG_LOG_DIR: Log storage directory (default: ./debug-logs)
• DEBUG_AUTH: Enable authentication debug mode (default: false)

📖 API Documentation

POST /api/debug-log

Receive debug logs from frontend.

Request Body:

{
  "logs": [
    {
      "sessionId": "session-123",
      "timestamp": 1717564800000,
      "type": "console",
      "level": "log",
      "message": "Hello World",
      "url": "https://example.com"
    }
  ],
  "source": "frontend"
}

Response:

{
  "status": "ok",
  "received": 1
}

GET /api/debug-log/list

List all log files.

Query Parameters:

• source: Filter by source (optional)

Response:

{
  "logs": [
    {
      "name": "frontend.log",
      "path": "/var/log/debug-logs/frontend/frontend.log",
      "size": 1024,
      "modified": "2024-06-05T10:30:00"
    }
  ]
}

GET /api/debug-log/{source}

Get logs from a specific source.

Query Parameters:

• limit: Maximum number of entries to return (default: 100)

Response:

{
  "source": "frontend",
  "entries": [
    {
      "sessionId": "session-123",
      "timestamp": 1717564800000,
      "type": "console",
      "level": "log",
      "message": "Hello World"
    }
  ]
}

🐳 Docker

Build Image

docker build -t debug-log-server .

Run Container

docker run -d \
  -p 8000:8000 \
  -v /var/log/debug-logs:/app/debug-logs \
  --name debug-log-server \
  debug-log-server

Docker Compose

version: '3.8'

services:
  debug-log-server:
    image: debug-log-server:latest
    ports:
      - "8000:8000"
    volumes:
      - ./debug-logs:/app/debug-logs
    environment:
      - DEBUG_LOG_DIR=/app/debug-logs
    restart: unless-stopped

🔧 Configuration

Basic Configuration

# config.py
import os

LOG_DIR = os.getenv("DEBUG_LOG_DIR", "./debug-logs")
HOST = os.getenv("HOST", "0.0.0.0")
PORT = int(os.getenv("PORT", "8000"))

Advanced Configuration

# config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    log_dir: str = "./debug-logs"
    host: str = "0.0.0.0"
    port: int = 8000
    debug_auth: bool = False
    
    class Config:
        env_prefix = "DEBUG_"

settings = Settings()

🔒 Security

Authentication

The server supports JWT authentication for protected routes:

from fastapi import Depends
from debug_log_server import debug_auth

@app.get("/api/protected")
async def protected_route(token: str = Depends(debug_auth)):
    return {"message": "This is a protected route"}

CORS

CORS is enabled by default for all origins. For production, configure it properly:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-domain.com"],  # Specify allowed origins
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

📊 Monitoring

Health Check

curl http://localhost:8000/

Log Statistics

curl http://localhost:8000/api/debug-log/list

🧪 Testing

Install Test Dependencies

pip install debug-log-server[dev]

Run Tests

pytest tests/

Test with httpx

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_receive_log():
    response = client.post("/api/debug-log", json={
        "logs": [{
            "sessionId": "test",
            "timestamp": 1717564800000,
            "type": "console",
            "message": "test"
        }],
        "source": "test"
    })
    assert response.status_code == 200

📝 Examples

Python Client

import requests

# Send logs
response = requests.post('http://localhost:8000/api/debug-log', json={
    "logs": [{
        "sessionId": "session-123",
        "timestamp": 1717564800000,
        "type": "console",
        "level": "log",
        "message": "Hello from Python"
    }],
    "source": "python-client"
})

print(response.json())

JavaScript Client

// Using fetch
fetch('http://localhost:8000/api/debug-log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    logs: [{
      sessionId: 'session-123',
      timestamp: Date.now(),
      type: 'console',
      level: 'log',
      message: 'Hello from JavaScript'
    }],
    source: 'javascript-client'
  })
})
.then(response => response.json())
.then(data => console.log(data));

🚀 Deployment

Systemd Service

# /etc/systemd/system/debug-log-server.service
[Unit]
Description=Debug Log Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/debug-log-server
Environment="DEBUG_LOG_DIR=/var/log/debug-logs"
ExecStart=/usr/local/bin/debug-log-server
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable debug-log-server
sudo systemctl start debug-log-server

Nginx Reverse Proxy

server {
    listen 80;
    server_name logs.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

📚 Related Projects

• @dengshi/debug-logger: Frontend log collection library (npm)
• playwright-collector: Playwright-based log collector

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions