foundation-performance-observability

name	foundation-performance-observability
description	Foundational skill for performance and observability across Godot domains. Defines budgets, profiling loop, and regression controls for CPU/GPU/memory/runtime behavior.
tier	core
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/performance/general_optimization.rst","godot-docs/tutorials/performance/cpu_optimization.rst","godot-docs/tutorials/performance/gpu_optimization.rst","godot-docs/tutorials/scripting/debug/the_profiler.rst"]
tags	["performance","observability","profiling"]
depends_on	[]

Foundation Performance and Observability

Use When

• Building or modifying systems in rendering, physics, navigation, UI, networking, IO, or tooling.
• You need repeatable performance budgets and measurable outcomes.

Outcomes

• Performance budgets are defined and measurable.
• Profiling data drives optimization priorities.
• Regressions are detected through repeatable checks.

Required Rules

• Set explicit performance budget before optimization work.
• Profile first, optimize second.
• Track CPU and GPU hotspots separately.
• Treat stutter/frame pacing issues as first-class defects.
• Add regression checks when changing high-risk code paths.

Workflow

1. Define target budgets for frame time, memory, and load times.
2. Capture baseline profiler evidence for impacted scenes/systems.
3. Implement focused optimizations mapped to measured hotspots.
4. Re-profile under same conditions and compare against baseline.
5. Record regressions and remaining risk with next actions.

Validation

• Baseline and post-change profiles are captured with same scenario setup.
• CPU/GPU bottlenecks are identified separately in reports.
• Performance budget pass/fail status is explicit after changes.

Failure Modes

• Optimization is done without baseline data and provides no measurable gain.
• CPU and GPU issues are conflated, leading to ineffective fixes.
• Performance checks run on different scenarios and create false confidence.

Local Doc Anchors

• godot-docs/tutorials/performance/general_optimization.rst
• godot-docs/tutorials/performance/cpu_optimization.rst
• godot-docs/tutorials/performance/gpu_optimization.rst
• godot-docs/tutorials/scripting/debug/the_profiler.rst