--- title: Glossary description: Definitions of the observability, telemetry and Home Assistant terms used across the m7kni.io project documentation. --- # 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.