Skip to content

Improve CPU hotspot explainability for repeated work#20

Merged
V3RON merged 2 commits into
masterfrom
issue-18-cpu-hotspot-explainability
May 13, 2026
Merged

Improve CPU hotspot explainability for repeated work#20
V3RON merged 2 commits into
masterfrom
issue-18-cpu-hotspot-explainability

Conversation

@V3RON
Copy link
Copy Markdown
Contributor

@V3RON V3RON commented May 12, 2026

agent-cdp users can now tell whether a CPU hotspot's cost came from repeated short runs, delegated child work, or inclusive total time without exporting the raw profile to another tool.

Summary

  • add --min-total-ms to profile cpu hotspots so inclusive-time filtering matches the existing self-time filter
  • enrich profile cpu hotspot with repeated-run summaries, delegated child time, top callers/callees, and exact hotspot bucket distribution
  • keep the sample-based caveat explicit while updating CLI help, the core skill, and focused tests for the new inspection flow

Backward Compatibility

  • Existing commands and daemon workflows stay the same; this only adds an optional hotspot filter and richer hotspot detail output.
  • Default CLI output remains text-first and existing session/profile artifacts are unchanged.
  • The main compatibility risk is for scripts that parse profile cpu hotspot text output exactly; the command is still the same, but the human-readable lines are richer.

Risks

  • Caller/callee attribution is still sample-based, so recursive or highly interleaved stacks can look approximate rather than exact invocation counts.
  • Hotspot time distribution is based on normalized buckets, which improves explainability but still should not be interpreted as exact wall-clock timing.
  • Any consumer depending on the previous exact profile cpu hotspot text formatting may need to adjust.

Fixes #18

Manual Testing

  1. Start the daemon, select a target, and record a CPU profile around a workload with repeated synchronous work.
  2. Run agent-cdp profile cpu hotspots --sort totalMs --min-total-ms 50 and verify that inclusive-time filtering surfaces hotspots whose cost mostly lives in children.
  3. Pick a hotspot from that list and run agent-cdp profile cpu hotspot --id HOTSPOT_ID; verify that the output calls out repeated runs, delegated child time, top callers/callees, and active time ranges.
  4. Re-run with and without --verbose and verify that the extra explanatory fields remain sample-based summaries rather than exact timing claims.

@V3RON V3RON merged commit 2107999 into master May 13, 2026
4 checks passed
@V3RON V3RON deleted the issue-18-cpu-hotspot-explainability branch May 13, 2026 15:14
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.

Improve CPU hotspot explainability for repeated work

1 participant