OtelContext

Turn traces, logs, and metrics into one clear view of your services.

Self-hosted OpenTelemetry collection, incident triage, and service mapping in one Go binary.

OtelContext helps you answer the question that starts most incidents: what is broken, and what does it affect? Send it standard OpenTelemetry data and it connects service relationships, errors, latency, logs, and traces in a map built for investigation.

It starts with SQLite and no external services. When you need more, the main telemetry database can use PostgreSQL, MySQL, or SQL Server.

[!IMPORTANT] OtelContext is pre-1.0. Read the changelog before upgrading.

What you get

• A live service map that shows dependencies, health, latency, and active anomalies.
• Incident context in one place with related traces, logs, metrics, and impact analysis.
• Seven MCP tools for investigating your system from an AI client or coding agent.
• Standard OTLP input over gRPC and HTTP, so existing SDKs and Collectors can send data directly.
• A simple first run with one binary and a local SQLite database.
• Self-hosted data with retention controls, health probes, and Prometheus metrics.

Quick start

1. Install a release

Download the archive for your platform from GitHub Releases, or install the latest release with Go:

go install github.com/RandomCodeSpace/otelcontext@latest

2. Start OtelContext

otelcontext

That is enough for a local trial. OtelContext creates OtelContext.db, listens for OTLP gRPC on 4317, and serves the UI and HTTP endpoints on 8080.

Open http://localhost:8080.

Authentication is off by default so the browser UI works immediately. Keep this first run on your machine. Before exposing it to a network, follow Secure a deployment.

3. Send telemetry

Point an OpenTelemetry SDK or Collector at either endpoint:

To confirm the connection without setting up an application, send one sample error log:

curl -fsS http://localhost:8080/v1/logs \
  -H "Content-Type: application/json" \
  -d "{
    \"resourceLogs\": [{
      \"resource\": {\"attributes\": [{
        \"key\": \"service.name\",
        \"value\": {\"stringValue\": \"readme-demo\"}
      }]},
      \"scopeLogs\": [{\"logRecords\": [{
        \"timeUnixNano\": \"$(date +%s)000000000\",
        \"severityNumber\": 17,
        \"severityText\": \"ERROR\",
        \"body\": {\"stringValue\": \"OtelContext is receiving data\"}
      }]}]
    }]
  }"

ERROR is used because the default storage threshold keeps WARN and ERROR logs.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch: {}

exporters:
  otlp/otelcontext:
    endpoint: otelcontext:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/otelcontext]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/otelcontext]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/otelcontext]

Investigate with MCP

Connect an MCP client to http://localhost:8080/mcp to investigate the same telemetry from an agent. The tools can:

• Build an anomaly timeline.
• Show the service map and service health.
• Analyze likely root causes and downstream impact.
• Reconstruct a trace graph.
• Search logs with bounded results.

Trace-based answers say whether the supporting exemplar is complete, partial, or no longer retained. OtelContext does not present a partial trace as the whole story.

Upgrade without guessing

The same binary can check and upgrade its database before it starts any receiver or background work:

./otelcontext migrate status
./otelcontext migrate up

If the database came from an older release that predates migration tracking, identify it once before upgrading:

./otelcontext migrate baseline --from v0.3.1
# or: --from v0.4.0-beta.2
./otelcontext migrate up

The baseline command validates the database first; it does not repair or guess. Create a complete OtelContext backup before upgrading, and keep the previous signed binary until migrate status reports result=ready. Versioned production checks are available for SQLite and unpartitioned PostgreSQL 16. MySQL, SQL Server, and PostgreSQL daily partitioning keep their existing preview AutoMigrate path.

For a one-host Linux deployment, use the shipped systemd unit and environment example and follow the install, upgrade, and rollback runbook. Direct execution remains supported for local use.

Back up and restore

After stopping OtelContext cleanly, use the same binary and environment as the service:

otelcontext backup create --out /absolute/path/to/backups

The published bundle keeps the main database, any mode-required aggregate database, the dead-letter queue, generated TLS identity, and a hashed manifest together. Restore into new database and sidecar paths; the command will not overwrite the source or an existing target:

otelcontext backup restore --bundle /absolute/path/to/backups/otelcontext-backup-...

Restore starts the same candidate briefly, waits for /ready, and shuts it down again. Keep the old binary, configuration, data, and bundle until the restored deployment passes your checks. The backup and restore runbook covers database-specific tools, fresh-target setup, validation, and rollback.

Secure a deployment

Set at least one authentication method before exposing OtelContext:

• API_KEY for a shared operator credential.
• AUTH_TRUST_EXTERNAL=true when a trusted reverse proxy owns authentication and tenant identity.

Example:

export API_KEY="$(openssl rand -hex 32)"
./otelcontext

Clients then send Authorization: Bearer <key>. Production mode also requires protected, authenticated gRPC unless you set an explicit waiver.

The browser UI does not currently store an API key. For an authenticated browser deployment, put OtelContext behind a same-origin proxy that authenticates the user and injects the credential for REST, MCP, and WebSocket traffic.

See the operations guide for database, TLS, retention, proxy, and health-check setup.

Common configuration

OtelContext reads environment variables and an optional .env file in its working directory.

Start with .env.example. The default legacy mode is the right choice for a first run. Aggregate modes are for measured high-volume deployments; review the aggregate gate report before enabling them.

git clone https://github.com/RandomCodeSpace/otelcontext.git
cd otelcontext

CGO_ENABLED=0 go build -o otelcontext .

go build ./...
go vet ./...
go test -race -timeout 180s ./...

Project links

• Releases
• Changelog
• Operations guide
• Contributing
• Security policy
• Aggregate design glossary
• Release gate protocol

License

OtelContext is available under the MIT License.