Architecture

Prerequisites

Operators should know which components run in their environment:

• Oriel binary
• PostgreSQL metadata database
• ClickHouse telemetry database
• Valkey runtime cache/pub-sub store
• Optional TLS proxy
• Optional OIDC identity provider

Steps

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

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:

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

Check liveness:

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

Check readiness:

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

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

Rollback/Recover

• 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.