opentrace

Give your AI assistant eyes into production

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

Why OpenTrace?

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

Quick Start

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?"

MCP Tools

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.

Overview & Triage

Log Intelligence

Database Introspection (Postgres)

Errors (Sentry-like)

Analytics & Journeys

Guided Workflows

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.

Features

Dashboard — Live Logs & Alerts

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.

MCP Setup — Connect in 3 Steps

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

75+ MCP Tools — Organized by Category

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

Log Ingestion

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.

Postgres Connector

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.

Rule-Based Watches

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.

Server Monitoring

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

Deploy

One-Click

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

Docker Compose

# Development
docker compose up -d

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

Binary

Download from GitHub Releases:

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

Fly.io

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

Configuration

All configuration via environment variables (.env file):

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

Architecture

                         ┌────────────────────────────┐
  ┌──────────┐           │       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.

Documentation

Development

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.

License

MIT