[iankhou]

Fixes #2084

Description

When a deployment fails, cdk deploy can investigate beyond the CloudFormation error using multiple methods:

• CloudTrail logs (default on)
• CloudFormation hooks API (default off, since info is available in the event stream)
• Logs from custom resource deployments (default on)
• Logs from ECS containers (default on)

Changes

Each of these methods require additional API calls beyond what CloudFormation resource handlers return. This change creates a consolidated interface behind the --investigate flag, which takes comma-separated strings:

• cloudtrail (default off)
• hooks (default off)
• custom-resources (default on)
• ecs (default on)

It also disables CloudTrail logs by default.

Run cdk deploy with the new flag:

# example that enables CloudTrail but disables ECS container logs
cdk deploy MyStack --investigate cloudtrail,no-ecs

Checklist

• This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
  • Release notes for the new version:

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[maintainer-for-aws]

Automated review

A maintainer will still review this — treat the notes below as a starting point.

📌 Commit eb0be6b

This PR adds a --investigate flag to cdk deploy and cdk diagnose (also settable via a top-level investigate key in cdk.json) that lets users choose which failed-stack investigations run — CloudTrail, custom-resource logs, ECS stopped-task logs, and CloudFormation hook details. It introduces a new exported Investigations type and a resolveInvestigations helper in toolkit-lib, replaces the single fetchHookFailureDetails boolean on the internal CloudFormationStackDiagnoser with the richer investigations prop, and flips CloudTrail and hook-detail lookups off by default for interactive deploys while keeping everything on for diagnose. The change is additive on the public API surface, the one deliberate default change (CloudTrail off by default on deploy) is the documented fix for the underlying issue, and the parsing grammar, default resolution, and per-toggle gating are each covered by tests. No issues found on this change.

🔴 0 blocking · 🟡 0 recommended · ⚪ 0 optional

---

Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.20%. Comparing base (5ec9d01) to head (eb0be6b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2122      +/-   ##
==========================================
+ Coverage   92.07%   92.20%   +0.12%     
==========================================
  Files          82       83       +1     
  Lines       13206    13283      +77     
  Branches     1900     1912      +12     
==========================================
+ Hits        12160    12247      +87     
+ Misses       1008      998      -10     
  Partials       38       38              

Flag	Coverage Δ
suite.unit	92.20% <100.00%> (+0.12%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[maintainer-for-aws]

See the review summary comment for the overview; the notes below are inline.

[maintainer-for-aws]

See the review summary comment for the overview; the notes below are inline.