Self-hosted observability server with 75+ MCP tools.
Ingest logs, connect Postgres, monitor servers — then debug it all from Claude, Cursor, or any MCP client.

Quick Start · MCP Tools · Features · Deploy · Docs

Your AI coding assistant can read your code — but it's blind to what's happening in production. OpenTrace fixes that.

• No more copy-pasting stack traces, log snippets, or query plans into chat
• No cloud vendor required — single binary, SQLite storage, runs anywhere
• MCP-native — not an afterthought API wrapper; every feature is designed as an MCP tool with guided workflows
• Your data stays yours — fully self-hosted, no telemetry, no external calls

Docker (fastest):

docker run -d --name opentrace -p 8080:8080 -v opentrace-data:/data ghcr.io/adham90/opentrace:latest

From source:

git clone https://github.com/adham90/opentrace.git && cd opentrace
cp .env.example .env
go build -o opentrace ./cmd/opentrace && ./opentrace

Open localhost:8080 — first visit triggers admin setup.

Then connect it to your AI assistant:

// .mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop)
{
  "mcpServers": {
    "opentrace": {
      "type": "stdio",
      "command": "/path/to/opentrace",
      "args": ["mcp"]
    }
  }
}

Now ask your assistant: "What errors are happening in production?"

OpenTrace exposes 75+ tools over MCP (stdio + SSE). The server sends guided instructions at handshake time and returns suggested_tools with pre-filled arguments, so your AI assistant knows what to call next.

Tools return suggested_tools with pre-filled arguments, chaining naturally:

diagnose → error_detail → log_search (with exception_class pre-filled)
                        → trace_lookup (with trace_id pre-filled)

db_query_stats → explain_query (with slowest query pre-filled)

triage_alerts → investigate → log_search (with service + error level)

Your AI assistant follows these suggestions automatically — no prompt engineering needed.

See the full MCP integration guide for setup instructions and complete tool reference.

Real-time log stream with attention zone showing active alerts. Click any log entry to expand details. Filter by level, service, or free-text search.

Built-in setup page with copy-paste configs for Claude Code, Cursor, Windsurf, and any MCP client. Includes a one-line install command.

Every tool is browsable in the web UI with descriptions, access levels, and connector requirements.

Ingest structured logs via HTTP, search with SQLite FTS5. Filter by service, level, environment, trace ID, commit hash, exception class, or any metadata field.

curl -X POST http://localhost:8080/api/logs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "service": "payment-api",
    "level": "error",
    "message": "Payment gateway timeout after 30s",
    "environment": "production",
    "event_type": "payment.failed",
    "metadata": {"transaction_id": "tx_abc123"}
  }'

Official client libraries handle async dispatch, batching, PII scrubbing, and graceful shutdown — your app never blocks or crashes due to OpenTrace:

All three clients share the same safety-first design: never raise/throw to the host app, bounded queues, smart truncation, and W3C trace context propagation.

Connect read-only to your production Postgres databases. All queries are validated SELECT-only via SQL AST parsing, with configurable timeouts and row limits. Introspection tools read from pg_stat_* views — no application changes needed.

Threshold monitors on log-derived metrics: error_rate, error_count, response_time, p95_response, sql_count, cache_hit_rate, heartbeat, log_count. Supports cron schedules, consecutive-breach requirements, and auto-resolve when metrics return to baseline.

Lightweight agent (opentrace agent) collects CPU, memory, disk, network, and load metrics via gopsutil and pushes to the dashboard. Agent docs.

Platform		Notes
DigitalOcean		~$5/mo
Railway		Free tier
Render		Free tier

# Development
docker compose up -d

# Production (with auto-updates via Watchtower)
docker compose -f docker-compose.prod.yml up -d

Download from GitHub Releases:

curl -L https://github.com/adham90/opentrace/releases/latest/download/opentrace_linux_amd64.tar.gz | tar xz
./opentrace

fly launch --copy-config --no-deploy
fly deploy

[Unit]
Description=OpenTrace
After=network.target

[Service]
Type=simple
ExecStart=/opt/opentrace/opentrace
EnvironmentFile=/opt/opentrace/.env
Restart=always

[Install]
WantedBy=multi-user.target

All configuration via environment variables (.env file):

See .env.example for the full list including TLS, CORS, retention, and proxy settings.

                         ┌────────────────────────────┐
  ┌──────────┐           │       Web UI (HTMX)        │         ┌────────────┐
  │ VM Agent │──metrics─▶│  Alerts │ Logs │ Watches    │◀─browse─│  You / CI  │
  └──────────┘           └────────────┬───────────────┘         └────────────┘
                                      │
  ┌──────────┐           ┌────────────▼───────────────┐         ┌────────────┐
  │ Your App │──logs────▶│     HTTP Server (Chi)       │◀─stdio─│Claude/MCP  │
  └──────────┘           │    REST API + MCP Server    │        │  Client    │
                         └────────────┬───────────────┘         └────────────┘
                                      │
             ┌────────────────────────┼────────────────────────┐
             │                        │                        │
   ┌─────────▼──────────┐  ┌─────────▼────────┐    ┌──────────▼─────────┐
   │  Connector Layer    │  │  Watch Engine     │    │  Postgres          │
   │  Logs + DB + Metrics│  │  Threshold Alerts │    │  (your databases)  │
   └─────────┬──────────┘  └─────────┬────────┘    └────────────────────┘
             │                        │
             └────────────┬───────────┘
                          │
           ┌──────────────▼───────────────────┐
           │       SQLite (WAL + FTS5)         │
           │  Logs │ Errors │ Watches │ Alerts │
           │  Metrics │ Sessions │ Journeys    │
           └──────────────────────────────────┘

Design decisions:

• SQLite — Zero dependencies. Single-file database with FTS5 for full-text log search.
• MCP-first — Every feature is an MCP tool, not just a REST endpoint. Tools include guided suggestions so AI assistants navigate workflows without prompt engineering.
• Read-only DB access — Queries against your Postgres are validated SELECT-only via SQL AST parsing.
• Single binary — Web server, MCP server, and VM agent in one binary. No runtime dependencies.

go test -short -race ./...              # unit tests (no Docker)
go test -race ./...                     # full suite (needs Docker for Postgres)
OPENTRACE_DEV=true ./opentrace          # live template reload

See CONTRIBUTING.md for development setup and guidelines.

MIT