Label each troubleshooting section as a recommended alert - #5046
Open
austonli wants to merge 1 commit into
Open
Conversation
Reading a section on its own, nothing said it corresponded to an alert. It opened with a bare "Metric:" line, so the threshold, for duration, and severity existed only in the tables on the alerting page. Anyone arriving from a firing alert's runbook_url or from search had no way to know what condition was supposed to have triggered it. All 20 sections now open with the full alert definition: **Recommended alert:** temporal_workflow_task_execution_failed with failure_reason=NonDeterminismError Fires on any occurrence, held for 1m. Routed Critical by default. Tune the threshold. Two sections cover more than one alert, and say so: UNIMPLEMENTED and INTERNAL are separate alerts on the same metric, and Workflow Task schedule-to-start has two thresholds. Each of the three pages also opens by saying every section on it is one of the recommended alerts, and that if you arrived from a firing alert, the section you landed on is its runbook. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
austonli
marked this pull request as ready for review
August 6, 2026 19:21
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #5029, which merged before this change was pushed.
Problem
Reading a section on its own, nothing indicated it corresponded to an alert. Each opened with a bare
**Metric:**line, so the threshold,forduration, and severity existed only in the tables on Worker alerting.Anyone arriving from a firing alert's
runbook_url— which is the main path onto these pages — had no way to see what condition was supposed to have triggered it.Change
All 20 sections across the three troubleshooting pages now open with the full alert definition:
Two sections cover more than one alert and say so: UNIMPLEMENTED and INTERNAL are separate alerts on the same metric, and Workflow Task schedule-to-start has two thresholds.
Each page also now opens by stating that every section on it is one of the recommended alerts, and that if you arrived from a firing alert, the section you landed on is its runbook.
Prose only. No thresholds, metric names, tags, anchors, or links changed.
Known trade-off
This duplicates the alert definitions: once in the tables on the alerting page, once per section here. That will drift.
It's the right trade for now, because a runbook that doesn't state its own trigger condition isn't much of a runbook. But when the generated PromQL reference lands with Tiho's ruleset contribution, both should be sourced from the YAML rather than hand-maintained in two places.
Verification
yarn buildexits 0 withonBrokenLinksandonBrokenAnchorsboth set tothrow.check:metricsreports 50 metrics consistent,check:orphansclean.Left as a draft pending review of the approach.
🤖 Generated with Claude Code
┆Attachments: EDU-6898 Label each troubleshooting section as a recommended alert