Profiling

Collect CPU profiles, memory (heap) profiles, and goroutine profiles for Terragrunt.

profiling - What it does

When enabled, Terragrunt allows collecting runtime profiles using CLI flags (or the corresponding TG_PROFILE_* environment variables):

• --profile-cpu / TG_PROFILE_CPU: write a CPU profile
• --profile-mem / TG_PROFILE_MEM: write a heap memory profile
• --profile-goroutine / TG_PROFILE_GOROUTINE: write a goroutine profile (stack traces of all goroutines)
• --profile-dir / TG_PROFILE_DIR: collect all of the above into a single directory using conventional filenames

Example:

terragrunt --experiment=profiling --profile-dir /tmp/profiles run --all -- plan

This is primarily intended for performance investigation and debugging of Terragrunt itself.

The experiment can also be enabled with TG_EXPERIMENT=profiling, which is convenient when driving profiling entirely through environment variables.

profiling - How to provide feedback

Provide feedback on the Terragrunt GitHub Discussions or by opening an issue.

profiling - Criteria for stabilization

To transition the profiling experiment to a stable release, the following should be addressed:

• Validate that profiling reliably covers Terragrunt runs across different invocation styles.
• Ensure documentation (CLI flags + env vars) is complete and accurate.
• Gather feedback on the chosen flag names (--profile-*).
• Decide whether additional profile types (block, mutex, etc.) should be exposed.
• Confirm the interaction with --experiment-mode and TG_EXPERIMENT is ergonomic.