Metadata-Version: 2.4
Name: debug-log-server
Version: 0.1.0
Summary: Debug log collection and query service based on FastAPI
Author-email: dengshi <dengshi@mercator.cn>
License: MIT
Project-URL: Homepage, https://github.com/dengshihub/debuglogger
Project-URL: Documentation, https://github.com/dengshihub/debuglogger#readme
Project-URL: Repository, https://github.com/dengshihub/debuglogger.git
Project-URL: Issues, https://github.com/dengshihub/debuglogger/issues
Keywords: debug,log,logging,fastapi,monitoring,error-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"

# Debug Log Server

Debug log collection and query service based on FastAPI.

## 📦 Installation

### From PyPI

```bash
pip install debug-log-server
```

### From Source

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

## 🚀 Quick Start

### Start Server

```bash
# 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:**
```json
{
  "logs": [
    {
      "sessionId": "session-123",
      "timestamp": 1717564800000,
      "type": "console",
      "level": "log",
      "message": "Hello World",
      "url": "https://example.com"
    }
  ],
  "source": "frontend"
}
```

**Response:**
```json
{
  "status": "ok",
  "received": 1
}
```

### GET /api/debug-log/list

List all log files.

**Query Parameters:**
- `source`: Filter by source (optional)

**Response:**
```json
{
  "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:**
```json
{
  "source": "frontend",
  "entries": [
    {
      "sessionId": "session-123",
      "timestamp": 1717564800000,
      "type": "console",
      "level": "log",
      "message": "Hello World"
    }
  ]
}
```

## 🐳 Docker

### Build Image

```bash
docker build -t debug-log-server .
```

### Run Container

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

### Docker Compose

```yaml
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

```python
# 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

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

```python
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:

```python
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

```bash
curl http://localhost:8000/
```

### Log Statistics

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

## 🧪 Testing

### Install Test Dependencies

```bash
pip install debug-log-server[dev]
```

### Run Tests

```bash
pytest tests/
```

### Test with httpx

```python
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

```python
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

```javascript
// 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

```ini
# /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
```

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

### Nginx Reverse Proxy

```nginx
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](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](../CONTRIBUTING.md) for details.

## 📞 Support

- 📖 [Documentation](https://github.com/dengshihub/debuglogger#readme)
- 🐛 [Issue Tracker](https://github.com/dengshihub/debuglogger/issues)
- 💬 [Discussions](https://github.com/dengshihub/debuglogger/discussions)
