Skip to content

Add authored Poison Wait alert-notebook template (#4223) - #4424

Merged
erikdarlingdata merged 2 commits into
devfrom
fix/4223-notebook-poison-wait
Sep 26, 2026
Merged

erikdarlingdata merged 2 commits into
devfrom
fix/4223-notebook-poison-wait

Conversation

@erikdarlingdata

@erikdarlingdata erikdarlingdata commented Sep 26, 2026 •

Copy link
Copy Markdown
Owner

Refs #4223.

Why

Poison Wait's alert-notebook link fell back to the mechanical read-list conversion instead of an authored, forensic layout, and its wait type (THREADPOOL, RESOURCE_SEMAPHORE, ...) lived only in prose (the detail heading / detail_text), not as data a template could branch on.

What changes

  • AlertContext gains a WaitType member, persisted as a trailing/nullable field on AlertContextDto (same backward-compatible shape as Route/Routing) with a TryReadWaitType reader. Both engines' Poison Wait fire sites set it: SQL Server's AlertEngine.CheckPoisonWaitsAsync (the worst-graded finding's WaitType) and PostgreSQL's DarlingWorker.EvaluatePgPoisonWaitAsync (finding.Subject) — the same value each engine's mute context already keys on.
  • New AlertNotebookEndpoint.Templates.PoisonWait.cs registers authored/poison-wait for the "Poison Wait" metric (both engines).
  • One row added to s_authoredTemplates, kept sorted.
  • Two tests used "High CPU" as their example of a metric that stays on the mechanical notebook; High CPU gets its own notebook in Add the authored High CPU alert-notebook template (#4223) #4420, so both now use "tempdb Space", which no Alert notebooks: authored templates for the remaining families, including custom rules and analysis findings #4223 family covers.

Cell list (RESOURCE_SEMAPHORE firing):

Cell Type Notes
Header, Status header/status as every family
Top waits (SQL Server) read get_wait_stats
Top waits (PostgreSQL) read get_pg_wait_stats wrong-engine read answers "not applicable" on its own
Waiting tasks read get_waiting_tasks
Resource semaphore read get_resource_semaphore ONLY when wait type == RESOURCE_SEMAPHORE (ordinal, case-insensitive)
Memory grants read get_memory_grants same gate
Wait time over time panel, wait_stats/wait_time_ms (sum), filtered to the wait type when known
Wait trend read get_wait_trend bound to the incident's exact wait type; omitted (replaced by a markdown note) when no wait type is known, since the read requires one

Test plan

New Darling/Darling.Tests/AlertNotebookTemplatePoisonWaitTests.cs (13 facts/theories): routing, RESOURCE_SEMAPHORE gate (present + absent, case-insensitive), get_wait_trend's wait_type equals the row's exactly, the no-wait-type degrade (omits trend, adds a note, same cell count), ValidateNotebookDefinition passes both with and without a wait type, and the context-serializer round-trip (WaitType persists and rehydrates; legacy JSON with no member reads null).

RED on dev: AuthoredTemplate_PoisonWait_IsNotNull fails today because "Poison Wait" has no registered row (AuthoredTemplate returns null).

GREEN: dotnet Darling.Tests.dll -class Darling.Tests.AlertNotebookTemplatePoisonWaitTests -class Darling.Tests.AlertNotebookAuthoredTemplateTests -class Darling.Tests.AlertNotebookEndpointTests -class Darling.Tests.DocCommentHygieneTests on macOS: Total 159, Failed 0.

Both test projects build clean: Darling.Tests and Lite.Tests at 0 errors (-p:EnableWindowsTargeting=true). Lite.Tests/Darling.Tests themselves are Windows-only and were not run beyond the in-process class list above; CI decides the rest. Full suite was not run given the time budget — the class list above covers everything the family's shared theories and this PR's own file touch.

CHANGELOG entry

SECTION: Added
ENTRY:

Poison Wait's firing context now carries the wait type as structured
data (AlertContext.WaitType, set at both engines' fire sites), and
Poison Wait gets its own authored notebook template instead of the
mechanical read-list fallback: header/status, both engines' top-waits
reads, waiting tasks, the resource-semaphore and memory-grant reads
gated on the firing wait type, a wait-time timeline, and a wait trend
bound to the exact wait type (or a note when none is known).

Refs #4223.
@erikdarlingdata
erikdarlingdata marked this pull request as ready for review September 26, 2026 15:09
@erikdarlingdata
erikdarlingdata merged commit b476262 into dev Sep 26, 2026
15 of 16 checks passed
@erikdarlingdata
erikdarlingdata deleted the fix/4223-notebook-poison-wait branch September 26, 2026 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant