Get started
backwork unifies logs, metrics and traces in one self-hosted dashboard. You can be sending real telemetry in about five minutes — create a project, drop an agent on a host, and point OpenTelemetry at a single endpoint.
Quickstart
Three steps from zero to a live dashboard:
- 1. Create a project in Projects and copy its one-time ingest token.
- 2. Ship telemetry — run the agent for logs & metrics, or set the OTLP env vars for traces.
- 3. Watch it live — the dashboard auto-refreshes, detects incidents and routes alerts.
Projects & tokens
A project is an app or environment you ship telemetry from. Each project has its own ingest token, and all data sent with that token is isolated to your organization. The token is shown once on creation — copy it then, or regenerate a new one (which invalidates the old).
Logs & metrics agent
One command installs a Vector + exporter agent on any host. It forwards that host's container logs and, optionally, host/container metrics:
curl -fsSL https://backwork.dev/install.sh | sh -s -- \ --token <YOUR_INGEST_TOKEN> \ --name $(hostname) \ --metrics host # host | container | all | none
Logs appear under Logs; host metrics (node-exporter) and per-container metrics (cAdvisor) under Metrics.
Traces (OpenTelemetry)
The fastest path is the backwork SDK — it wires OpenTelemetry to your project in one line. Install it, set BACKWORK_TOKEN to your project token, and preload it:
# Node npm i @sirfitz/backwork BACKWORK_TOKEN=<YOUR_INGEST_TOKEN> BACKWORK_SERVICE=my-api \ node --import @sirfitz/backwork/register server.js # Bun bun add @sirfitz/backwork BACKWORK_TOKEN=<YOUR_INGEST_TOKEN> bun --preload @sirfitz/backwork/start run server.ts
Elixir — add {:backwork, "~> 0.1"} to your deps, then:
# config/runtime.exs config :opentelemetry, traces_exporter: :otlp config :opentelemetry_exporter, Backwork.exporter_config() # application.ex — before your supervisor children Backwork.setup(phoenix_adapter: :bandit, ecto: [[:my_app, :repo]])
Prefer raw OpenTelemetry? backwork speaks OTLP natively — point any OTel SDK or Collector at one endpoint with your token, no SDK required:
OTEL_EXPORTER_OTLP_ENDPOINT=https://backwork.dev/otlp OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <YOUR_INGEST_TOKEN> OTEL_SERVICE_NAME=your-service
Spans show up under Traces (with a waterfall), Requests (a flat RED feed) and Metrics → Application performance.
Errors & API
Report exceptions by POSTing them with your project ingest token — backwork fingerprints and groups them under Errors (a new occurrence reopens a resolved group; ignored ones stay muted):
curl -X POST https://backwork.dev/ingest/errors \
-H "Authorization: Bearer <YOUR_INGEST_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"type":"TypeError","message":"Cannot read x of undefined","service":"my-api","stack":"...","environment":"production"}'Read your data over HTTP. Create a read-only API key in the org menu under API keys, then query the bearer-authed, org-scoped JSON API:
curl -H "Authorization: Bearer <API_KEY>" https://backwork.dev/api/v1/errors # also: /api/v1/me · /api/v1/incidents · /api/v1/services
Or use the CLI:
npm i -g @sirfitz/backwork-cli export BACKWORK_API_KEY=<API_KEY> bw errors --status open # also: bw me · bw incidents · bw services · --json
Concepts
Logs are searchable with full-text or LogQL. Metrics are queried with PromQL under the hood. Traces follow a request across services. Requests distil traces into method/route/status/latency. Incidents are detected automatically from container state, metrics and logs. Alerts evaluate rules and notify via Slack, Discord, webhook, email or SMS — and report a no-data state rather than faking “all clear” during an outage.
Self-hosting
backwork is open source and runs anywhere Docker does. Clone the repo and bring the stack up:
git clone https://github.com/SirFitz/backwork.git cd backwork docker compose up -d
Under the hood it composes Loki (logs), VictoriaMetrics (metrics), Jaeger (traces) and Vector (collection) behind the dashboard. Your telemetry never leaves your infrastructure.
Organizations & teams
backwork is multi-tenant. Create organizations, invite members with roles (owner, admin, member, viewer), group them into teams, and issue per-project ingest tokens. Every org's logs, metrics and traces are isolated server-side by an enforced tenant id — see Security for the details.