A full-stack, self-hosted observability platform built on OpenTelemetry — traces, logs, metrics, alerting, dashboards, and natural-language querying, in one product.
- Native telemetry ingestion — the ingest gateway accepts OTLP over gRPC and HTTP plus Prometheus Remote Write. Gauge, Sum, and Histogram metric types are fully supported; ExponentialHistogram and Summary are modeled but not yet ingested (see docs/signal-support.md).
- Unified query experience — traces, logs, and metrics are correlated through shared identities (tenant, service, environment, trace/span IDs) and explorable from one frontend, including a natural-language query layer and a Monaco-based multi-signal query workbench.
- Alerting and SLOs — threshold, composite, and burn-rate alert rules with a webhook notification channel.
- Multi-tenant by design — tenant/environment scoping, OpenFGA-backed authorization, and Zitadel-backed identity out of the box.
- Rust data plane, React frontend — see spec/02-architecture.md for the full architecture and spec/adr/README.md for the decision log.
The current release is 0.1.0. ROADMAP.md is the authoritative, outcome-based path
from the shipped evaluation baseline through a stable 1.0.0 self-hosted contract.
Observable 0.1 is intended for evaluation and small non-critical deployments. Storage schemas, APIs, Helm values, and upgrade procedures may change without backward compatibility before 1.0.
The full specification is located in the spec/ directory, indexed in spec/README.md. See docs/signal-support.md for the signal-support matrix and known limitations. For operating an evaluation deployment, see the evaluation guide, deployment guide, resource requirements, and API stability policy.
See CONTRIBUTING.md for the development workflow, and CODE_OF_CONDUCT.md for community expectations. Report security issues per SECURITY.md, not as public issues.
This project is licensed under the MIT License.
Mandatory instructions for any AI agent interacting with this repository can be found in AGENTS.md. (The legacy AGENT.md, GEMINI.md, and CLAUDE.md files are now pointers to the canonical instructions).
The entire stack is started with a single command. All service images are built locally from source — no registry login needed. The first run compiles the Rust backend, which typically takes 3–10 minutes depending on your machine; subsequent starts reuse the Docker layer cache and are nearly instant.
You need Docker Compose and GNU Make. See resource requirements before starting the stack on a constrained machine.
# Recommended: build images then start (required on first run or after pulling new code)
make dev
# Equivalent:
docker compose up -d --build
# Start only (if images are already built from a previous run)
docker compose up -d
# Force a full rebuild from scratch
docker compose up -d --build --no-cacheA Makefile wraps the most common commands:
make dev # remove setup containers, then docker compose up -d --build
make dev-down # docker compose down
make db-migrate # re-run postgres/clickhouse setup to apply any new migrations
make reset-volumes # wipe all persistent volumes and start fresh
make smoke-test # run end-to-end smoke tests
make lint # cargo fmt/clippy + npm lint
make test # cargo test + frontend typecheckAfter pulling new code that adds migrations, run
make db-migrateto apply them without a full restart.
When the stack is ready, open the frontend and sign in with the development account:
| Field | Value |
|---|---|
| URL | http://localhost:5173 |
| Username | admin@observable.localhost |
| Password | Dev@Admin1234! |
These credentials are for the local Docker Compose environment only. Override the development
password with OBSERVABLE_DEV_ADMIN_PASSWORD when needed.
| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Ingest gateway (HTTP/OTLP) | http://localhost:4318 |
| Ingest gateway (gRPC/OTLP) | grpc://localhost:4317 |
| Ingest gateway (platform API) | http://localhost:4321 |
| Query API | http://localhost:8090 |
| Auth service | http://localhost:4319 |
| Admin service | http://localhost:4324 |
| Alert evaluator | http://localhost:4322 |
| Storage writer | http://localhost:4320 |
| Stream processor | http://localhost:4323 |
| OpenFGA (authorization) | http://localhost:8083 |
| Zitadel (identity provider) | http://localhost:8082 |
| ClickHouse (HTTP) | http://localhost:8123 |
| Redpanda (Kafka-compatible) | localhost:9092 |
⚠️ Port conflict with the kind testbench cluster The kind testbench (bash scripts/testbench.sh) binds host port 8080 for the Observable frontend ingress. Docker Compose binds 8083 for OpenFGA. These don't overlap, but if a stale kind cluster is running it may hold other ports too. Stop it before runningdocker compose up -d:kind delete cluster --name observable-test
# Stop all containers (keeps volumes)
docker compose down
# Stop and delete all data volumes (full reset)
docker compose down -v
# or
make reset-volumesdocker compose up smoke-test --abort-on-container-exit
# or
make smoke-testFor end-to-end testing with real OTel traffic and the Observable frontend, use the kind testbench.
First run — start the cluster once and keep it alive:
# Builds images, deploys everything, keeps cluster after Ctrl+C
bash scripts/testbench.sh --keep-clusterURLs once ready:
- Observable frontend: http://localhost:8080/
- Testbench shop: http://localhost:3000/
Subsequent changes — hot-reload a single service in seconds:
# Rebuild and redeploy only what changed
bash scripts/dev-reload.sh --service query-api
bash scripts/dev-reload.sh --service frontend
bash scripts/dev-reload.sh --service testbench-api
# Also run unit tests after reload
bash scripts/dev-reload.sh --service query-api --run-testsThe cluster keeps running between reloads. Docker layer caching makes rebuilds fast (typically 5–30 s for Rust services, <10 s for Node.js testbench images).
Valid --service values: query-api, stream-processor, ingest-gateway,
storage-writer, auth-service, alert-evaluator, backend (all Rust),
frontend, testbench-api, testbench-frontend, testbench-worker,
testbench-loadgen, testbench (all testbench), all (default).
Tear down when done:
kind delete cluster --name observable-testSee spec/10-process.md for the official development process and engineering standards.
The demos/ directory contains example applications that showcase Observable in action.
| Demo | Description | Status |
|---|---|---|
| otel-demo | The OpenTelemetry Demo microservices app, reconfigured to route through the Observable ingest gateway. | Canonical onboarding demo |
The otel-demo is the recommended starting point for evaluating Observable with realistic multi-service traffic.