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
- Configure API_KEYS in production - Prevent unauthorized access
- Enable rate limiting - Prevent API abuse
- Use HTTPS - Recommended with Nginx reverse proxy
- Backup database regularly -
logs.dbcontains 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
Metadata
Release files for agent-trace-log 0.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_trace_log-0.0.2.tar.gz | 63.5 kB | Without provenance | Details for agent_trace_log-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_trace_log-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for agent_trace_log-0.0.2-py3-none-any.whl |
Total release size: 136.8 kB
Release files / agent_trace_log-0.0.2.tar.gz
| Download URL | agent_trace_log-0.0.2.tar.gz |
|---|---|
| Size | 63.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
47a06b99fc087a1646bf71672d1c05116cee5e829098eac3dbad2c574b94f1ae
|
|
BLAKE2b-256 checksum How to use checksums |
03ba1756b71b252d26745b99f0b00cc779b810f8f605e9fa1bbc0b7b19ed7cfc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.0
|
Release files / agent_trace_log-0.0.2-py3-none-any.whl
| Download URL | agent_trace_log-0.0.2-py3-none-any.whl |
|---|---|
| Size | 73.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
624c8e0aa768a07f5d36d00891309244a23d6d05b8f1956e61352e247f708f9e
|
|
BLAKE2b-256 checksum How to use checksums |
fda9ad7b69f74e0a828e14e7b4d1641cdf339bb29a070a9079c5e43afc9a6c01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.0
|
Security for agent-trace-log 0.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.