docs: add metric stagnation detection pattern to time aggregation best practices

[decimal-pr-bot]

Summary of Changes

• Added "Detecting Metric Stagnation" subsection to data/docs/alerts-management/user-guides/time-aggregation-best-practices.mdx under the existing "Detecting Continuous Uptrends in Derived Metrics" section
• Covers using running_diff on a gauge metric with Latest temporal aggregation, alerting when result = 0 with "All the time" match type
• Updated frontmatter date

Reasoning

• Users needing heartbeat/stagnation detection assumed raw ClickHouse queries were required, when the Query Builder supports this via running_diff = 0
• The existing section only covered uptrend detection (running_diff > 0) but not the inverse stagnation pattern (running_diff = 0), which uses the same function

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
signoz-web	Ignored	Preview	Sep 7, 2026 12:43pm UTC

[github-actions]

Claude finished @decimal-pr-bot[bot]'s task in 1m 44s —— View job

---

Docs review — Metric stagnation detection

Reviewed with the signoz-docs-pr-review skill against contributing/docs-review.md + docs-authoring.md. One meaningful gap, otherwise solid. Technical claims verified against the repo's own metrics/alerts docs.

Verified as correct

• Latest time aggregation is valid for gauges (data/docs/metrics-management/types-and-aggregation.mdx:72).
• The running_diff = 0 → stagnation logic and All the time match usage are internally consistent.

Findings by severity

P2

• Missing-data case is unaddressed (:111-114). The pattern only catches a metric that keeps reporting a frozen value. If the heartbeat source dies entirely and stops emitting datapoints, All the Time evaluates only against existing samples (evaluation patterns doc — sparse-metrics note), so a fully-down source can produce no alert — the exact case a heartbeat check should catch. Add an Admonition clarifying scope and link a no-data alert for the stopped-emitting case. Fix this →

P3

• Heading nesting (:102). H3 "Detecting Metric Stagnation" lives under H2 "Detecting Continuous Uptrends…", so the parent heading no longer covers its content. Rename the H2 to be scope-neutral (e.g. "Detecting Trends with running_diff") or promote stagnation to its own H2.
• Latest not in the page's own "Common Time Aggregation Methods" table (:14-24). Optional: add a row for consistency, since the new section relies on it.

Personas & fit

SRE / platform engineer building heartbeat/liveness alerts. Content fits the persona and answers a real question (no raw ClickHouse needed). Fit weakens only because the doc implies full stale-detection while the P2 gap means it misses a fully-dead source.

JTBD coverage

• Primary job clear; steps concrete and minimal ✅
• Validation/success signal in SigNoz — thin (no "what you see when it fires"), acceptable for this short addition
• Check feat: update toc generation function #11 (troubleshooting from symptoms) — the missing-data caveat (P2) is the gap here

Checklist coverage

• Frontmatter, prose (no em dashes / AI tells), link conventions ✅
• doc_type: explanation while the section is procedural how-to — pre-existing on this page, not introduced here; no action needed

Open questions / assumptions

• Assumed the intended target is a still-scraped gauge whose value freezes. If the intent includes fully-stopped sources, the P2 caveat is required, not optional.

Onboarding label: skipped — edit to an existing doc (status == modified), not a new send-data page.

---

• Read review playbooks
• Read the changed doc in full context
• JTBD + technical accuracy pass (verified Latest/All the time against repo docs)
• Post inline findings (2)
• Post summary + onboarding-label result
  · branch decimal/stagnation-detection-running-diff-7379