Skip to content
Oriel

Architecture

Oriel is one binary with selectable runtime roles. Operators decide whether to run all roles in one process or split query, ingest, and worker capacity across separate processes.

Required components

Section titled “Required components”
  • Oriel binary
  • PostgreSQL metadata database
  • ClickHouse telemetry database
  • Valkey runtime cache/pub-sub store
  • Optional TLS proxy
  • Optional OIDC identity provider

Runtime roles

Section titled “Runtime roles”

Deploy Oriel as one binary first. The documented default is:

Terminal window
oriel serve --role=all

The binary starts these subsystems:

Subsystem Purpose
Ingest OTLP gRPC and HTTP receivers.
Query UI, API, feature-flag evaluation API, health checks, readiness, OpenAPI, and metrics scrape route.
Worker Alert and SLO evaluation, service-map rollups, flag-staleness scans, and experiment analysis.
Self-observability Optional in-process telemetry for Oriel itself.

Oriel supports split roles for scale-out:

Terminal window
oriel serve --role=ingest
oriel serve --role=query
oriel serve --role=worker

Split roles share PostgreSQL, ClickHouse, and Valkey. They do not share local process state.

Feature flag definitions, segments, SDK keys, and targeting live in PostgreSQL. SDK rulesets are cached in Valkey by ruleset version, and SDK streams use Valkey Pub/Sub for low-latency fanout while PostgreSQL remains authoritative. When the API and ingest pipeline run in the same process, feature flag evaluations and environment-scoped changes are also emitted into ClickHouse as ordinary project telemetry.

Verify the process

Section titled “Verify the process”

Check liveness:

Terminal window
curl -fsS http://localhost:6743/healthz

Check readiness:

Terminal window
curl -fsS http://localhost:6743/readyz

Readiness verifies dependency reachability and schema compatibility when the query role is running.

Recover dependency failures

Section titled “Recover dependency failures”
  • If readyz returns ORL-5002, run oriel migrate up with the same config as the service.
  • If ClickHouse is unavailable, query and ingest paths that need telemetry storage will fail until the database is reachable.
  • If PostgreSQL is unavailable, auth, metadata, and token paths will fail.
  • If Valkey is unavailable, Oriel is not ready and the serve process fails at startup.
  • Prefer fixing dependency reachability before restarting Oriel repeatedly.