Agent-Trace-Log - LLM API Logging & Tracing System

An OpenAI-compatible LLM API proxy service focused on logging and agent behavior observation.

中文文档

Why Agent-Trace-Log?

When learning agent frameworks, you might wonder:

• What prompts does the agent send?
• How does it think and make decisions?
• How are messages passed in multi-turn conversations?

Most proxy APIs or official APIs don't provide log viewing functionality. Agent-Trace-Log makes everything transparent.

Features

• ✅ OpenAI/Anthropic Compatible - Supports both OpenAI and Anthropic API formats
• ✅ Streaming Support - Full SSE streaming response support
• ✅ Complete Logging - Request/response automatically recorded to SQLite database
• ✅ Web Dashboard - Visual log viewing, prompts, and model calls
• ✅ Multi-Provider Support - Configure multiple upstream APIs with flexible switching
• ✅ API Authentication - Supports multiple API key authentication
• ✅ Rate Limiting - Configurable requests per minute limit
• ✅ Model Mapping - Custom model name mapping
• ✅ Docker Deployment - Containerized deployment support
• ✅ pip Installation - Install directly from PyPI

Quick Start

Option 1: Install from PyPI

# Install from PyPI
pip install agent-trace-log

# Start the service
agent-trace-log web

# Specify port
agent-trace-log web --port 9000

Option 2: Install from Source

# Clone the project
git clone https://github.com/xiaozhiagi/agent-trace-log.git
cd agent-trace-log

# Install in development mode
pip install -e .

# Start the service
agent-trace-log web

# Development mode (hot reload)
agent-trace-log web --reload

# Or run directly
python agent_trace_log/main.py

Option 3: Docker Deployment

# Start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

CLI Commands

agent-trace-log                 # Show help
agent-trace-log web                # Start service (default 0.0.0.0:8000)
agent-trace-log web --reload       # Development mode, auto-reload on code changes
agent-trace-log web --port 9000    # Specify port
agent-trace-log web --host 127.0.0.1  # Specify host
agent-trace-log version            # Show version

Configuration

Environment Variables

Variable	Description	Default
BAILOU_API_KEY	Default upstream API key	-
BAILOU_BASE_URL	Default upstream API URL	https://dashscope.aliyuncs.com/compatible-mode/v1
LISTEN_HOST	Listen address	0.0.0.0
LISTEN_PORT	Listen port	8000
API_KEYS	Service API keys (comma-separated)	Empty
RATE_LIMIT_ENABLED	Enable rate limiting	false
RATE_LIMIT	Max requests per minute	60
MODEL_MAPPING	Model mapping (JSON format)	{}
LOG_LEVEL	Log level	INFO
DATABASE_PATH	Database file path	./logs.db
REQUEST_TIMEOUT	Request timeout (seconds)	120

Model Mapping Example

# Map gpt-3.5 to qwen-turbo, gpt-4 to qwen-max
MODEL_MAPPING='{"gpt-3.5": "qwen-turbo", "gpt-4": "qwen-max"}'

API Usage

OpenAI Format

# Chat completion
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "qwen-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Streaming request
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "qwen-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Anthropic Format

curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

也支持 Authorization: Bearer your-api-key 格式，两种认证方式均可。

Other Endpoints

# List models
curl http://localhost:8000/v1/models

# Health check
curl http://localhost:8000/health

Log Query

Web Interface

Visit http://localhost:8000/ to open the dashboard. You can view:

• All request logs
• Complete request/response content
• Token consumption statistics
• Model call distribution

API Endpoints

# Get log list
curl "http://localhost:8000/api/logs?limit=50&offset=0"

# Filter by model
curl "http://localhost:8000/api/logs?model=qwen-turbo"

# Filter by status
curl "http://localhost:8000/api/logs?status=success"

# Get statistics
curl "http://localhost:8000/api/logs/stats"

# Get single log detail
curl "http://localhost:8000/api/logs/req_xxxxxxxxxxxx"

Project Structure

agent-trace-log/
├── agent_trace_log/       # Python package
│   ├── __init__.py      # Package entry point
│   ├── main.py          # FastAPI application
│   ├── cli.py           # CLI entry (agent-trace-log web)
│   ├── config.py        # Configuration management
│   ├── database.py      # Database operations
│   ├── middleware.py    # Middleware (auth, rate limiting)
│   ├── services/
│   │   ├── __init__.py
│   │   ├── proxy.py     # Proxy service
│   │   └── logger.py    # Logging service
│   ├── templates/       # HTML templates
│   │   ├── index.html   # Home dashboard
│   │   ├── logs.html    # Log list
│   │   ├── log_detail.html  # Log detail
│   │   ├── docs.html    # API docs
│   │   ├── usage.html   # Usage guide
│   │   └── health.html  # Health check
│   └── static/          # Static files
│       └── i18n.js      # Internationalization
├── pyproject.toml       # Package configuration
├── requirements.txt     # Python dependencies
├── Dockerfile           # Docker image
├── docker-compose.yml   # Docker Compose config
├── README.md            # English documentation
└── README_zh.md         # Chinese documentation

Security Recommendations

1. Configure API_KEYS in production - Prevent unauthorized access
2. Enable rate limiting - Prevent API abuse
3. Use HTTPS - Recommended with Nginx reverse proxy
4. Backup database regularly - logs.db contains all request records

Nginx Reverse Proxy Example

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost: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;
    }
}

License

MIT License