# Glossary — Observability & Monitoring

The canonical vocabulary for this course. Opinionated and repo-flavoured. Once a term is
defined here, every lesson uses it this way. Terms marked *(Part N)* are taught in that part.
Repo-specific values are confirmed in [repo-observability-map.md](./repo-observability-map.md).

---

### Observability
The property of being able to understand a system's internal state from its external outputs
(metrics, logs, traces) — enough to answer questions you didn't anticipate. Broader than
monitoring (predefined dashboards/alerts). *"Monitoring tells you the known-unknowns;
observability lets you explore the unknown-unknowns."*

### The three pillars *(Lesson 1)*
**Metrics** (numbers over time — alert on these), **traces** (the path of one request across
services — find *where*), **logs** (event records — the *context* to resolve it). Metrics
alert; traces localize; logs explain.

### Golden signals *(Lesson 1)*
Latency, traffic, errors, saturation — the four SRE signals that catch most issues. **RED**
(Rate, Errors, Duration) is the request-centric subset; **USE** (Utilization, Saturation,
Errors) is the resource-centric one.

### Metric *(Lesson 2)*
A named, timestamped numerical measurement with labels (dimensions), e.g.
`istio_requests_total{code="200", service="bob"}`. Stored as a time series.

### Prometheus *(Lesson 2)*
The open-source metrics system: it **pulls** (scrapes) metrics from targets' HTTP `/metrics`
endpoints, stores them as time series, and queries them with **PromQL**. *Repo: self-hosted
under `platforms/monitoring/prometheus`.*

### Metric types *(Lesson 2)*
**Counter** (monotonic ↑, e.g. requests_total), **Gauge** (up/down, e.g. memory), **Histogram**
(bucketed observations + sum + count — for latency percentiles), **Summary** (client-side
quantiles). Counter + histogram cover most cases.

### Pull model / scrape *(Lessons 2–3)*
Prometheus **pulls** metrics on an interval from targets it discovers (vs push). *Repo:
discovers pods via the `prometheus.io/scrape` annotation.*

### `/metrics` endpoint *(Lesson 3)*
The HTTP endpoint a service exposes for Prometheus to scrape (text exposition format). *Repo:
served by the Go services; the port is set in the workload metadata.*

### Labels / cardinality *(Lessons 2–3)*
Key-value dimensions on a metric. Every unique label combination is a separate time series —
too many (**high cardinality**, e.g. user IDs as labels) blows up storage. A key gotcha.

### PromQL *(Lesson 4)*
Prometheus's query language. Core: `rate(counter[5m])` (per-second rate), aggregation
(`sum by (…)`), `histogram_quantile(0.99, …)` (p99 latency).

### Recording rule *(Lesson 4)*
A precomputed PromQL expression saved as a new time series — speeds up dashboards/alerts that
reuse an expensive query.

### Alerting rule *(Lessons 4, 7)*
A PromQL condition that, when true for a duration, fires an **alert** (with labels/annotations)
sent to Alertmanager/OnCall. *Repo: the `istio-basic` group on `istio_requests_total`, etc.*

### Thanos *(Lesson 5)*
A set of components that give Prometheus **long-term storage** (upload TSDB blocks to object
storage), a **global query** view across many Prometheis, **deduplication** (HA pairs), and
**downsampling**. Components: sidecar, store, query, compactor, ruler. *Repo:
`platforms/monitoring/thanos`.*

### Object storage (for metrics) *(Lesson 5)*
A GCS bucket where Thanos stores metric blocks for cheap, long retention (vs Prometheus's local
disk). *Provisioned by Terraform, Course 7.*

### Grafana *(Lesson 6)*
The visualization layer — dashboards built from **datasources** (Prometheus/Thanos-query,
Jaeger, …). Not a data store itself. *Repo: fronted by the monitoring ingress gateway.*

### Datasource *(Lesson 6)*
A backend Grafana queries (e.g. Thanos Query for metrics, Jaeger for traces).

### Alertmanager *(Lesson 7)*
Receives fired alerts from Prometheus/Thanos-ruler and handles **grouping, deduplication,
silencing, and routing** to receivers (Slack, email, PagerDuty/OnCall).

### Grafana OnCall *(Lesson 7)*
On-call scheduling + escalation + paging — turns an alert into "wake the right person," with
rotations and escalation policies. *Repo: the paging layer.*

### SLI / SLO / error budget *(Lesson 8)*
**SLI** = a measured indicator (e.g. % requests < 300ms). **SLO** = the target (e.g. 99.5%).
**Error budget** = 100% − SLO (the allowed failure). **Burn rate** = how fast you're spending
it. Alert on burn rate, not raw errors.

### Span / trace *(Lesson 9)*
A **span** is one timed operation (with attributes + parent link); a **trace** is the tree of
spans for one request across services. Traces localize *where* a request slowed/failed.

### OpenTelemetry (OTel) *(Lessons 9–10)*
The vendor-neutral standard + SDKs for producing traces/metrics/logs, and the **Collector** that
receives/processes/exports them. *Repo: `internal/golibs/tracer`; the OTel Collector in
`monitoring`.*

### OTel Collector *(Lesson 10)*
A pipeline: **receivers** (ingest, e.g. Zipkin/OTLP) → **processors** (batch/sample) →
**exporters** (send to a backend, e.g. Jaeger). *Repo: `opentelemetry-collector.monitoring`.*

### Jaeger *(Lesson 10)*
The distributed-tracing backend: stores + visualizes traces so you can inspect one request's
span tree.

### Sampling *(Lesson 10)*
Keeping only a fraction of traces (head/tail) to control cost. *Repo: Istio traces at 100%
sampling — unusually high.*

### Structured logging / Cloud Logging *(Lesson 11)*
Logs as JSON (fields, not free text) so they're queryable. *Repo: Go services log structured
JSON to stdout → GKE → **GCP Cloud Logging**. No Loki.*

### Correlation *(Lessons 9, 11, 12)*
Linking the three pillars — a metric spike → the traces in that window → the logs for those
requests (via trace/span IDs). The whole point of the stack together.

### Kiali *(Lesson 12)*
The Istio mesh dashboard: live service graph, traffic health, and config validation — reading
this stack's Prometheus + the mesh. *Repo: `platforms/monitoring` / the mesh.*

### `pushgateway` *(Lesson 3)*
A component that lets short-lived jobs *push* metrics (since Prometheus can't scrape something
that already exited). *Repo: `prometheus-pushgateway` for BDD test metrics.*