Glossary

Terms that recur across these projects, defined once. Every project site's abbreviation list expands acronyms on hover; this page explains what they mean and, where it matters, what people get wrong about them.

Each entry has its own anchor, so you can link straight to one.

Telemetry

OpenTelemetry

A vendor-neutral standard for producing telemetry, covering the wire format, the semantic conventions for naming things, and SDKs in most languages. It describes how telemetry is emitted, not where it is stored — every project here emits OpenTelemetry and none of them require you to use any particular backend.

OTLP

OpenTelemetry Protocol: the wire format telemetry travels in, over gRPC or HTTP. OTLP/HTTP on port 4318 and OTLP/gRPC on port 4317 carry the same data; HTTP is easier to get through a proxy and gRPC is cheaper at volume.

Signal

One of the kinds of telemetry: metrics, traces, logs, and increasingly profiles. The word matters because the four are collected, stored and queried by different systems, and a tool that handles one says nothing about the others.

Span

One timed operation inside a trace — an HTTP request, a database query, a function call. Spans nest, and the tree of them is the trace.

Trace context

The identifiers (traceparent, and optionally tracestate) passed between services so their spans join into one trace. Lose it at a hop and the trace silently splits into two unrelated ones, which looks like two fast requests rather than one slow one.

Resource attributes

Key-value pairs describing the thing emitting telemetry — service.name, host.name, deployment.environment — as opposed to attributes describing a single event. They are attached once and apply to everything that source emits, which is what makes them cheap and makes per-event attributes expensive.

Semantic conventions

OpenTelemetry's agreed names for common attributes: http.request.method rather than whatever you would have called it. Following them is what lets a dashboard written for one service work against another. They also change between versions, which is a routine source of "the dashboard broke and nothing in our code changed".

Cardinality

The number of distinct time series a metric produces — one per unique combination of its label values. This is the single biggest driver of observability cost. A metric with a user_id label has as many series as you have users, and adding one such label to an existing metric multiplies rather than adds.

Exemplar

A pointer from a metric data point to a specific trace that contributed to it, so you can jump from "latency spiked" to one actual slow request. Cheap to attach and disproportionately useful.

Histogram

A metric that records a distribution rather than a single number, so you can ask for percentiles. Classic histograms use fixed buckets you must choose in advance, and a percentile outside your bucket range is unrecoverable. Native (exponential) histograms choose resolution automatically and cost far less per series, but need backend support.

Temporality

Whether a metric reports its value since the last export (delta) or since the process started (cumulative). Prometheus is cumulative, OTLP supports both, and mismatching them produces counters that look like they reset constantly or never move.

Scrape

Prometheus's pull model: the server periodically fetches a metrics endpoint rather than the application pushing. The interval sets your resolution floor — nothing is visible at finer granularity than the scrape interval, no matter how often the underlying value changes.

Collector

An OpenTelemetry process that sits between sources and backends, built from receivers (take data in), processors (batch, filter, rewrite) and exporters (send it on). It is the usual place to do anything you would otherwise have to change every application to do.

Head and tail sampling

Head sampling decides whether to keep a trace at the moment it starts, before anything is known about it — cheap, and blind to whether the request turned out to be interesting. Tail sampling decides once the trace is complete, so it can keep the errors and the slow ones, at the cost of buffering every trace until then.

Instrumentation

The code that produces telemetry. Automatic instrumentation is injected by an agent or library and covers common frameworks; manual instrumentation is what you write for your own logic. Auto-instrumentation covers the plumbing and almost never covers the part you actually need.

Grafana stack

Prometheus

The metrics database and its query language's home. Pull-based, dimensional (labels rather than hierarchical names), and the de facto standard interface — "a Prometheus exporter" means anything exposing /metrics in its text format.

PromQL

Prometheus's query language. Its distinguishing feature is operating on labelled time series as sets, so a single expression can compute a rate per instance and then aggregate across them.

Remote write

The protocol Prometheus uses to forward samples to long-term storage such as Mimir or Grafana Cloud. Distinct from OTLP, and the two carry the same data with different metadata fidelity — remote write has no notion of resource attributes.

Mimir

Grafana's horizontally scalable long-term store for Prometheus metrics. Speaks PromQL and remote write, so it is a drop-in destination rather than a different query surface.

Loki

Grafana's log store. It indexes only labels, not log contents, which is why it is cheap and why a query that does not narrow by label has to read everything in the time range.

LogQL

Loki's query language. Deliberately PromQL-shaped: select streams by label, then filter and parse, and optionally turn the result into metrics.

Tempo

Grafana's trace store. Retrieval is by trace ID, with search layered on top — which is why exemplars and good log-to-trace correlation matter more here than elaborate trace search.

Recording rule

A precomputed query, evaluated on a schedule and stored as a new series. The fix for a dashboard panel that is correct but too slow, and the thing to reach for before caching.

SLO

Service Level Objective: a target for a measurable indicator over a window, such as "99.9% of requests succeed over 30 days". The useful part is the error budget it implies — the amount of failure you have agreed is acceptable, which turns "is it broken" into an arithmetic question.

RED and USE

Two checklists for what to measure. RED — Rate, Errors, Duration — covers request-driven services. USE — Utilization, Saturation, Errors — covers resources like CPUs, disks and queues. Most gaps in a dashboard are one of the two applied to the wrong kind of thing.

Architecture

Leader election

Ensuring exactly one instance of a replicated service performs a given job, so a poller running three times over does not produce triple the data. Several projects here use a Kubernetes Lease for this, with a no-op implementation for single-instance deployments.

Checkpoint and watermark

The record of how far through a data source a poller has read. The watermark is the position; the checkpoint is where it is persisted so a restart resumes rather than replays. Forward-only watermarks trade the risk of missing late-arriving data for a guarantee of never double-counting.

Backfill

Fetching data for a period already past, usually after an outage. Backends frequently reject samples older than a few hours, so a backfill that looks successful can silently discard most of what it sent.

Drift

Two things that are supposed to match, no longer matching — a vendor API against the client that consumes it, generated documentation against the code it was generated from, a config file against the schema that validates it. It is characteristically silent, which is why the projects here test for it rather than assume it.

Idempotency

An operation producing the same result whether it runs once or five times. Essential anywhere retries exist, because a retry cannot tell the difference between "the request failed" and "the response was lost".

Sources and integrations

Home Assistant

An open-source home automation platform. Its data model is entities (a single value or control, such as a temperature or a switch) grouped under devices, with a config flow as the UI-driven setup path an integration provides.

HACS

Home Assistant Community Store: the mechanism for installing integrations that are not shipped with Home Assistant itself.

Tailnet

A private network of devices joined by Tailscale, addressed directly and authenticated per-device regardless of the physical networks in between.

DERP

Designated Encrypted Relay for Packets — Tailscale's relay, used when two devices cannot open a direct connection. Traffic stays end-to-end encrypted through it, but latency and throughput are notably worse, so the proportion of relayed traffic is worth watching.

CARP

Common Address Redundancy Protocol: how a pair of firewalls share a virtual IP so one can take over from the other. On OPNsense it is the basis of a high-availability pair.

Flow export

Per-connection network records — NetFlow, IPFIX, sFlow — summarising who talked to whom, for how long, and how much. Complementary to packet capture: far cheaper, far less detailed.

Syslog

The long-standing protocol for shipping log lines from network devices. Two incompatible formats are both in use, RFC 3164 (BSD) and RFC 5424, and devices routinely disagree about which they emit.

Microsoft Graph API

The single API surface for Microsoft 365 and Entra ID data. Its throttling is per-resource rather than global, so a client can be rate-limited on one endpoint while another stays fast.

MinHash and LSH

A pair of techniques for finding near-duplicate documents without comparing every pair. MinHash reduces each document to a short signature whose overlap estimates similarity; LSH (Locality-Sensitive Hashing) buckets similar signatures so only plausible candidates are compared. Together they turn a quadratic problem into a tractable one.