Querying with PromQL

A dashboard shows a 0.3% error rate. The service is actually producing 4%. The query has no syntax error, Prometheus runs it without the slightest warning, and the number on screen has been wrong since the day it was created. The cause comes down to a single character: the rate window is shorter than the scrape interval, and the expression can't find enough points to compute anything on half of the series. PromQL doesn't protect you from this kind of mistake — there is no warning message for a query that is technically valid but semantically absurd.

That is the particularity of this language: mistakes don't show up as exceptions but as plausible numbers. Adding up gauges from two instances, applying rate to a metric that isn't a counter, computing a percentile from poorly chosen histogram buckets: each of these errors produces a smooth, credible curve that nobody will question until the next incident. This lesson covers the five constructs you'll need every day, then spends the rest of its time on the pitfalls, because that is where the reliability of everything you build next is decided.