Skip to content

grex

grex is an OpAMP control plane for OpenTelemetry Collector fleets. It implements the server side of the OpAMP specification and gives operators a read-only view of fleet health: connected collectors, identity, health, and effective configuration.

  otelcol agents / gateways
  (OpAMP over WS, optional mTLS)
           │
           ▼
  OpAMP gateway collector(s)  ──►  grex  ──►  browser (web UI)
  (optional multiplexing)            │
           │                         ├── JSON read API
  direct agents (optional)  ─────────┤
                                     └── Prometheus /metrics + /metrics/fleet

Who these docs are for

Audience Start here Goal
Operators (UI users) User guide Understand fleet status in the web UI
Administrators Admin guide Install, configure, secure, and scrape grex
Developers Developer guide Build, test, and extend grex (primary focus of this site)
Everyone Getting started Run grex and see a fleet in minutes

Deep coverage of metrics, logs, and traces lives under Observability.

What grex does (and does not) do in 1.0

Does:

  • Accept OpAMP connections from collectors (WebSocket and plain HTTP)
  • Support OpAMP gateway multiplexing (com.bindplane.opamp-gateway)
  • Maintain an in-memory fleet registry (identity, health, effective config, …)
  • Serve a read-only web UI and JSON API
  • Expose Prometheus metrics on a dedicated telemetry listener
  • Terminate TLS and require client mTLS on the OpAMP listener when configured

Does not (yet):

  • Push remote configuration, restarts, or package upgrades from the UI
  • Persist fleet state across restarts (agents re-report on reconnect)
  • Multi-tenancy (one fleet per grex instance)
  • UI/API authentication (mTLS and OIDC are planned; the UI listener is open today)
  • OTLP export of grex’s own telemetry (Prometheus scrape only)

The living product plan is under SPEC (design). That document changes frequently.

Quick start

No install required — open the static fleet demo on this site (sample data generated in your browser).

just compose-up
deploy/compose/smoke.sh
# UI: http://127.0.0.1:8080

See Compose stack.

cp config.example.yaml config.yaml
go run ./cmd/grex -config config.yaml
# UI :8080 · telemetry :9090 · OpAMP :4320

See Getting started.

helm repo add grex https://dennisme.github.io/grex/charts/
helm install grex grex/grex -n grex --create-namespace

See Deploy with Helm. Chart values: reference.

Documentation map

  • Demo — static sample fleet UI (no grex process)
  • Getting started — tutorials to a first success
  • User — fleet UI for operators
  • Admin — deploy (binary, Compose, Helm), config, TLS, lifecycle
  • Releases — binaries, images, Helm, and changelog
  • Developer — architecture, packages, API, UI, tests
  • Observability — metrics catalog, scrape layout, logs, traces
  • Reference — CLI, HTTP endpoints, Helm values
  • SPEC — living design documents

Why "grex"?

Latin: grex, gregis (n.) — flock, herd, group

The same root gives English gregarious and congregate. Fitting for a control plane that manages a flock of OpenTelemetry Collectors as one fleet.

License

Apache-2.0. Source: github.com/dennisme/grex.