Skip to main content

Platform architecture

This page explains how the full AtherOps platform fits together: agents, backend services, and storage. It is a reference for anyone who wants to understand what happens between the agent on your host and the data you query in the UI.

Components​

ComponentRoleRepo
atherops-otel-agentLinux host agent — wraps otelcol-contrib, signs telemetry via loopback proxyobservability/otel-agent
atherops-k8s-otel-agentKubernetes DaemonSet agent — same wrapper/proxy pattern, monitors a clusterobservability/k8s-otel-agent
atherops-backendIngest + query proxy; enforces org_id scoping on every write and readobservability/backend
atherops-apiIdentity and fleet control: accounts, JWT, install tokens, remote configobservability/api
alertingAlert rule storage + evaluation via vmalert; GET /rules/{id}/statusobservability/alerting
VictoriaMetricsMetric time-series store (PromQL-compatible)—
ClickHouseLog and trace store (columnar, 30-day TTL)—
PostgreSQLIdentity, fleet, dashboards, alert rules—

Topology​

The diagram below shows both agent types and how they connect to the platform.

What the wrapper does​

Both atherops-otel-agent and atherops-k8s-otel-agent follow the same pattern:

  1. Render collector config. Your config.yaml is a simple operator-facing file. The wrapper converts it to full OpenTelemetry Collector YAML. You never write collector YAML by hand.
  2. Supervise the collector. The wrapper starts otelcol-contrib, polls its health check on :13133, and restarts it on crash.
  3. Sign and forward telemetry. The collector sends plaintext OTLP to a loopback proxy (:9599) only. The proxy attaches HMAC credentials (X-Key-Hash, X-Timestamp, X-Signature) before forwarding to the backend. The raw API key never crosses the network.
  4. Manage identity. Register with an install token, persist the returned key (Linux: /etc/atherops/credentials.json; K8s: K8s Secret), heartbeat periodically.
  5. Converge on remote config. Poll the platform for config updates and target collector version; re-render and restart to match.

Multi-tenant isolation​

Every stored signal (metric, log, span) carries an org_id the server derives from the authenticated API key. No agent can write into another tenant's data. See Multi-tenant isolation for details.

Legacy agents​

The original K8s DaemonSet agent (agent/) and the original Linux host agent (linux-agent/) are frozen and receive no new development. They remain as reference implementations. The active agents are atherops-otel-agent and atherops-k8s-otel-agent.

See also​