Core concepts

A two-minute glossary. Every other doc assumes these terms.

Source

A source is anywhere ObserveKit collects data from. Every source has a name, a type, and its own API key. There are three types:

Type	What it is	How data arrives
Kubernetes	A cluster running the ObserveKit agent as a DaemonSet	Agent ships pod logs, node/container metrics, cluster state, TLS cert posture
Docker	A host running the ObserveKit agent as a container	Agent ships logs + metrics for every container on the host
Service	An OTel-instrumented app — no agent	The app pushes traces/metrics/logs to ObserveKit's OTLP endpoints directly

Pick Kubernetes/Docker when you want infrastructure telemetry with no code changes. Pick Service when you want app-level signals (traces, custom metrics) or your app runs where the agent can't (cloud VMs, Azure WebApps, serverless).

Source vs. service — the distinction that trips people up

A source is the *ingestion + access boundary*. It owns an API key; it's what you scope users to; it's the unit on the Sources page.
A service (service.name) is a label *inside* your telemetry, set by your app's OpenTelemetry SDK. One service source can carry many service.names; one service.name could even span multiple sources.

In the Traces, Metrics, and Logs views you filter by service.name. On the Sources page and for RBAC you work with sources. When you're "not seeing my data," first decide which axis you're filtering on.

Agent

The ObserveKit agent is a small collector you install on a cluster or host. On Kubernetes it runs as a DaemonSet (observekit-agent in the observekit namespace) — one pod per node — reading container logs from /var/log/containers, node/kubelet metrics, and Kubernetes state. It ships to the server over HTTPS, buffering to an on-disk WAL so nothing is lost during a blip. What it collects is trimmed by a config file — see Agent configuration. Installing it: Kubernetes · Docker.

OTLP receiver

OTLP (OpenTelemetry Protocol) is the open standard your app's OTel SDK speaks. ObserveKit exposes an OTLP receiver so any instrumented app can push directly — no agent. Endpoints: POST /v1/traces, /v1/metrics, /v1/logs (HTTP, port 4318) or gRPC on port 4317. Details: Sending data with OpenTelemetry.

API key

Every source has an API key. The agent embeds it at install time; an OTel app sends it on every request as X-API-Key or Authorization: Bearer. Keys are per-source so you can rotate or revoke one without touching the others. Managing them: API keys.

Where your data lives (storage & retention)

ObserveKit stores telemetry in tiers so recent data is fast and old data is cheap:

Hot — ClickHouse. Recent logs, traces, and metrics. This is what every query, chart, and alert reads. Fast.
Cold — MinIO (S3-compatible). Older data aged out of hot, still queryable, cheaper.
Metadata — SQLite. Sources, users, alert rules, dashboards — the configuration, not the telemetry.

Retention defaults: telemetry moves hot → cold at 7 days and is deleted at 90 days. The hot window is also governed by a server setting (storage.hot.retention_hours, default 7 days) and can be overridden per source. Retention is server-managed; see Cost Analytics for how volume and retention drive storage.

Putting it together

 Kubernetes / Docker ──(agent)──┐
                                 ├──▶ Source (API key) ──▶ ClickHouse (hot) ──▶ Logs / Traces / Metrics / Alerts
 Your app ──(OpenTelemetry)─────┘                     └──▶ MinIO (cold)