Skip to content

Add the authored High CPU alert-notebook template (#4223) - #4420

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

erikdarlingdata merged 2 commits into
devfrom
fix/4223-notebook-high-cpu

Conversation

@erikdarlingdata

@erikdarlingdata erikdarlingdata commented Sep 26, 2026 •

Copy link
Copy Markdown
Owner

Refs #4223.

Why

"High CPU" fires on both engines (SQL Server and PostgreSQL) and, like the other alert families, was falling back to a mechanical list of reads instead of getting an authored, forensic-shaped notebook.

What changes

AlertNotebookEndpoint.AuthoredTemplate("High CPU") now returns an authored/cpu template (version 1) with a fixed 7-cell layout:

# Cell Type Detail
1 Header header incident/history summary
2 Status status current status text
3 SQL Server CPU panel cpu_utilization_stats / sqlserver_cpu_utilization, avg, line, hourly buckets
4 PostgreSQL CPU panel pg_cpu_utilization / pg_acu_utilization_pct, avg, line, hourly buckets
5 Top queries by CPU read get_top_queries_by_cpu (hours=24, top=10)
6 Top procedures by CPU read get_top_procedures_by_cpu (hours=24, top=10)
7 Scheduler pressure read get_cpu_scheduler_pressure

Both engines' CPU panels are always present — same "not applicable" convention the mechanical map already uses for this metric (the wrong-engine read/panel just comes back empty).

Both CPU measures are Gauge archetype (point-in-time percent readings), so their valid aggregates are avg/min/max, never count. The shared TimelinePanel core helper hardcodes aggregate: "count" for the per-event deadlock/blocking sources it was built for, so this template adds its own small CpuGaugeTimelinePanel helper (private to the new file) instead of widening the shared one — that would change what every other already-shipped family's panel emits. No annotation overlay is added: none of the available annotation sources (deadlocks, blocked-process reports, long-query completions, default-trace events, system_health events) is a CPU-specific marker, so the panels carry no annotations key.

get_top_queries_by_cpu, get_top_procedures_by_cpu and get_cpu_scheduler_pressure declare no limit param in the read catalog (the first two cap with top instead, the last has no row cap at all), so they're added to s_authoredLimitlessTrendReads alongside get_deadlock_trend.

Two pre-existing tests hardcoded "High CPU" as an example of a metric that stays on the mechanical fallback path; both are updated to use "Poison Wait" instead, which still routes mechanically:

  • AlertNotebookAuthoredTemplateTests.AuthoredTemplate_NonAuthoredMetric_StaysMechanical
  • AlertNotebookEndpointTests.AuthenticatedRequest_ReturnsTheDocumentedNotebookShape

AlertNotebookAuthoredTemplateTests.Budget_ReadCellsHaveLimitsExceptTheTrendRead_ComposedWindowsAreAtMost24h (part of the shared theories, data-driven off the registration table) is extended with the same top-instead-of-limit / no-cap exceptions for the three new reads.

Test plan

New file Darling.Tests/AlertNotebookTemplateCpuTests.cs (3 tests): routing to authored/cpu, the exact 7-cell list with both engines' panels titled and sourced correctly, and the no-matched-incident degrade (same cell count, still validates).

  • RED confirmed against origin/dev (detached worktree): all 3 new tests fail — AuthoredTemplate("High CPU") returns null there (no registration row yet).
  • GREEN on this branch, in-process on macOS (Darling.Tests.dll, no live PG needed — these are pure):
    • AlertNotebookTemplateCpuTests: 3/3 pass.
    • AlertNotebookAuthoredTemplateTests (shared theories, now covering "High CPU" via its MemberData): 40/40 pass.
    • AlertNotebookEndpointTests: 29/29 pass.
    • DocCommentHygieneTests: 77/77 pass.
  • Both test projects build 0 errors / 0 warnings: Darling.Tests.csproj and Lite.Tests.csproj (-p:EnableWindowsTargeting=true). Both target net10.0-windows and cannot run here; CI decides them.
  • Did not run the full repo test suite (time budget); the classes above are the ones this change touches.

CHANGELOG entry

SECTION: Added

ENTRY:

REF:
[#4420]: #4420

High CPU fires on both engines; it now gets an authored 7-cell layout
(header, status, a SQL Server CPU timeline, a PostgreSQL CPU timeline,
top queries/procedures by CPU, scheduler pressure) instead of the
mechanical read list.

Both CPU measures are Gauge archetype, so their timelines use a small
avg/line helper local to the new file rather than widening the shared
TimelinePanel (which is built for count-aggregated per-event sources).

Updates two pre-existing tests that hardcoded "High CPU" as an example
of a metric staying on the mechanical fallback path to use "Poison Wait"
instead, and extends the shared budget theory for the two top-N reads
that cap with 'top' rather than 'limit'.

Refs #4223
@erikdarlingdata
erikdarlingdata marked this pull request as ready for review September 26, 2026 14:39
@erikdarlingdata
erikdarlingdata merged commit a2571bd into dev Sep 26, 2026
15 of 16 checks passed
@erikdarlingdata
erikdarlingdata deleted the fix/4223-notebook-high-cpu branch September 26, 2026 14:39
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