# Workload Hotspot CPU Contribution Estimate

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "workload-hotspot-cpu-contribution-estimate-2026-08-18",
  "problems": [
    {
      "problemId": "scenario-does-not-quantify-target-sql-share-of-cpu-increase",
      "summary": "The workload-hotspot Scenario could align a target SQL with a hot TiKV but lacked a stable CPU-time normalization and refinement rule to estimate how much of the node CPU increase that SQL explained.",
      "status": "optimized_verified",
      "applicability": "Workload-hotspot diagnosis with aligned TopSQL CPU time and TiDB or TiKV process CPU evidence inside one canonical incident window.",
      "issueKeys": ["TCID-12986"],
      "sourceRefs": ["https://tidb.atlassian.net/browse/TCID-12986#problem:workload-hotspot-cpu-contribution-estimate"],
      "signalTextIncludesAny": ["partial contributor", "explained CPU increase", "TopSQL CPU diff", "AI was more cautious"],
      "observedThrough": "2026-08-19",
      "effectiveAt": "2026-08-19T03:10:30Z",
      "verifiedAt": "2026-08-19T03:22:15Z",
      "attemptedAction": "Keep full-window SQL CPU share separate from phase-delta CPU-increase attribution; when a ticket explicitly asks what caused one node's CPU increase, prioritize one same-instance normalized baseline/hot refinement that compares supplied-SQL, leading-SQL, and TopSQL-scope average-core deltas with the process-CPU delta before backend residual analysis.",
      "evidenceUrl": "https://github.com/tidbcloud/aisupport/pull/1009"
    }
  ]
}
-->

- Owner: Scenario Diagnostic Agent, with neutral units from the Clinic Provider Executor
- Source: TCID-12986 human-versus-AI attribution review
- Implementation status: merged and deployed to staging
- Effectiveness status: optimized_verified

## Bounded problem

TopSQL `cpu_ms` and process CPU were both available, but the Scenario did not
normalize them to the same quantity. It could establish identity and temporal
alignment yet stop at a cautious qualitative contributor statement, while the
human compared changes and concluded that the target explained only part of
the TiKV CPU increase.

## Implemented change

- Treat TopSQL `cpu_ms` as accumulated CPU time across cores. Never multiply it
  by core count; divide by window seconds and 1000 to obtain average cores.
- Allow a typed TopSQL query to select a narrower absolute phase inside the
  canonical incident window.
- Treat full-window share as resident-load dominance only; it cannot close an
  explicit question about contribution to a CPU increase.
- For an explicit increase starting at one clock time, have the Scenario Router
  include the immediately preceding fifteen-minute baseline and the fifteen
  minutes starting at the onset in the canonical diagnostic range. The
  Scenario and Evidence Agent may select phases only inside that fixed range.
- After the same-instance process series establishes comparable phases, spend
  the next adaptive refinement on normalized baseline/hot process CPU and
  node-scoped TopSQL distributions. Retain the supplied SQL, leading node-local
  SQL, and scope total in both phases.
- Compare target, leading-SQL, and scope TopSQL average-core deltas with the
  process-CPU delta before using another refinement on backend residuals.
- Preserve non-positive target delta, ratio-above-one, and unstable-denominator
  outcomes explicitly instead of forcing a percentage.

## Verification evidence

- The earlier TCID-12986 read replay `e03b724f-6bbe-4e41-8ddc-b85f61f99a38` completed both
  `query-latency` and `workload-hotspot` scenarios with complete Clinic
  evidence acquisition and no failure codes. It did not create a round-2
  batch because the complete full-window bound already changed the relevant
  decision from possible primary driver to partial contributor. That proves
  CPU-unit normalization and resident-load bounding, but it does not verify the
  stated phase-delta CPU-increase criterion.
- The supplied SQL used 8,433,616 integrated TiKV CPU-ms in 900 seconds:
  `8,433,616 / 900 / 1000 = 9.3707` average CPU cores. Its observed TiKV
  Top20 share was at most 4.3041%, while another SQL used 160,256,263 CPU-ms.
  The resulting diagnosis states that the supplied SQL explains its own
  30–36.8 second latency and contributed to the event, but does not explain
  the broader TiKV-13 CPU increase by itself.
- The initial Evidence batch stayed on the canonical window and did not create
  opening, middle, or closing phases. Unit and contract tests also prove that
  epoch-second and timezone-explicit RFC3339 subwindows remain available for
  the one adaptive round when a full-window bound cannot decide the diagnosis.
- Jira internal comment `23357171` was recovered in place with the verified
  `+08:00` window, 9.37-average-core estimate, and 4.30% bound. Readback proved
  `public=false` and no additional comment.
- The first local candidate replay reached a complete eight-query phase
  refinement, but its canonical range began at the reported 17:45 onset. It
  therefore compared 17:45–17:50 with 17:55–18:00 and incorrectly called the
  first after-onset segment a baseline. That trial observed process CPU
  `+1.8921` average cores while `bc6171` changed `-0.4777`, `a862ec` changed
  `-0.0512`, and the TopSQL scope changed only `+0.0189`; those facts describe
  within-incident drift, not attribution of the 17:45 increase. The candidate
  now rejects that phase selection and fixes the earlier Router-owned range.
- The corrected local no-write replay
  `64c3785a-6993-4dcb-8c45-d88c15f41f85` completed with Clinic evidence
  acquisition `complete`, provider capability verified, and no failure codes.
  The Router fixed the range to 17:30–18:00 (+08:00); the workload-hotspot
  refinement then compared equal 09:35–09:45 and 09:45–09:55 UTC phases on
  TiKV-13 instead of comparing two after-onset segments.
- TiKV-13 process CPU increased from 38.2748 to 40.4048 average cores
  (`+2.1300`). The supplied SQL increased from 2.3071 to 3.2111 average cores
  (`+0.9040`, about 42.4% of the process delta), while `a862ec` increased from
  8.0159 to 9.1453 average cores (`+1.1294`, about 53.0%). Total node-scoped
  TopSQL increased by about 2.2361 average cores, roughly 105% of the process
  delta; the diagnosis explicitly retained the above-one measurement/offset
  caveat and the unstable-denominator limitation.
- The Scenario Diagnostic Agent and Scenario Router both used the phase-delta
  result. The final ticket-level diagnosis states that the supplied SQL
  materially but partially contributed, another node-local SQL consumed more,
  and increased SQL workload—not an unproven backend imbalance—best explains
  the modest TiKV-13 CPU rise. This passed the bounded reasoning criterion
  locally before rollout.
- PR #1009 merged as `7a9815f0032e9101238df0aef47e9ffbbe44924a`.
  The staging deploy workflow built that exact image, app-delivery PR #77646
  updated the canonical staging tag, and the live Pod became Ready at
  `2026-08-19T03:10:30Z`; both `/healthz` and `/readyz` returned HTTP 200.
- The post-deploy write replay
  `10a5220e-378c-4168-983c-9643e2b94ed0` completed with Clinic evidence and
  response generation both `complete`. It compared equal 09:30–09:45 and
  09:45–10:00 UTC phases on TiKV-13: process CPU increased by 1.781 average
  cores, the supplied SQL increased by 0.470 cores (about 26.4%), the leading
  node-local SQL increased by 0.737 cores (about 41.4%), and selected-scope
  TopSQL increased by 1.534 cores (about 86.1%).
- The deployed Scenario and Router preserved the resulting conclusion: the
  supplied SQL made a positive but partial contribution, another node-local
  SQL was the stronger remaining CPU candidate, and CPU scale-out was not
  indicated. The run succeeded as `human_required` because the escalated
  ticket and any plan, index, statistics, or SQL change require human review.
- The write replay reused the historical initial owner and updated Jira
  internal comment `23357171` in place. Jira readback proved `public=false`;
  the remote ADF SHA-256 exactly matched the run's expected paired live-comment
  ADF and no duplicate internal comment was created.

## Unresolved gaps

The comparison is unavailable when the Router-owned canonical diagnostic range
does not contain a real pre-increase baseline and hot phase, or the Provider
cannot return aligned instance CPU and target-Digest TopSQL. The Scenario must
preserve that exact limitation instead of widening the fixed range itself.

The 1.781-core process delta is small relative to the within-phase ranges, so
the exact contribution percentages remain bounded estimates rather than exact
CPU accounting. This limitation was preserved in the deployed scenario
decision and does not change the verified partial-contributor classification.

## Next validation action

Retain TCID-12986 as the verified regression and validate the same bounded
phase comparison on the next explicit SQL-to-node-CPU-increase case, especially
when the target SQL delta is non-positive or the TopSQL/process ratio exceeds
one.
