module Lapis::Docs::G_DEBUGGING_AND_DIAGNOSTICS::C_LEAK_AND_DISPATCH_DIAGNOSTICS

Overview

Leak Tracking & Latency Profiling

Comprehensive guide to Lapis's built-in low-overhead diagnostic apparatus for catching memory leaks, measuring virtual method execution latency, tracking signal cascades, and debugging dead-pointer crashes.

Executive Summary & Key Topics

Topic Method / Anchor Description
Diagnostic Modules Overview .topic_00_diagnostic_modules Listing of diagnostic tools available under Godot::Diagnostics.
Godot::Diagnostics::LeakTracker .topic_01_leak_tracker Detecting and identifying surviving Godot node and object leaks.
Godot::Diagnostics::DispatchProfiler .topic_02_dispatch_profiler Measuring virtual method latency and execution bottlenecks.
Godot::Diagnostics::TombstoneTracker .topic_03_tombstone_tracker Explaining dead-pointer crashes with destruction history.
Godot::Diagnostics::SignalSpy .topic_04_signal_spy Intercepting and tracing scene tree signal emissions.

Related Guides & Source References

Defined in:

libgodot/docs/g_debugging_and_diagnostics/c_leak_and_dispatch_diagnostics.cr

Class Method Summary

Class Method Detail

def self.topic_00_diagnostic_modules : Nil #

Diagnostic Modules Overview: Listing of diagnostic tools available under Godot::Diagnostics.

Key Topics & Information

  • Godot::Diagnostics::LeakTracker: Records allocations and dumps uncollected objects
  • Godot::Diagnostics::DispatchProfiler: Nanosecond timing of virtual method dispatches
  • Godot::Diagnostics::TombstoneTracker: Captures destruction callstacks to explain dead pointers
  • Godot::Diagnostics::SignalSpy: Real-time logging of scene tree signal emissions

def self.topic_01_leak_tracker : Nil #

Godot::Diagnostics::LeakTracker: Detecting and identifying surviving Godot node and object leaks.

Compile with -Dleak_tracker or lapis build --leak-tracker to instrument Godot::Object:

require "libgodot"

# Print number of currently active, tracked Godot objects:
puts "Active objects: #{Godot::Diagnostics::LeakTracker.count}"

# Dump all active objects along with their allocation callsite file and line:
Godot::Diagnostics::LeakTracker.dump_active_objects

Output format:

=== Godot Active Object Allocations (2 active) ===
  #1536105194213 Enemy (src/gameplay/spawner.cr:28)
  #1536105194214 Bullet (src/weapons/blaster.cr:64)
==================================================

def self.topic_02_dispatch_profiler : Nil #

Godot::Diagnostics::DispatchProfiler: Measuring virtual method latency and execution bottlenecks.

Compile with -Dprofile_dispatches or lapis build --profile-dispatches to record timing metrics across virtual methods:

Sample output:

=== Virtual Method Dispatch Profiling Report ===
Method               Calls       Total (ms)   Avg (ns)   Min (ns)   Max (ns)
_process             12000       45.20 ms     3766 ns    2100 ns    14500 ns
_physics_process     7200        22.10 ms     3069 ns    1950 ns    11200 ns
_input               450         0.92 ms      2044 ns    1800 ns    5400 ns
================================================

def self.topic_03_tombstone_tracker : Nil #

Godot::Diagnostics::TombstoneTracker: Explaining dead-pointer crashes with destruction history.

When an object is freed by Godot or GDScript and subsequently dereferenced in Crystal, Godot::DisposedObjectError is raised. With -Dtrace_dead_pointers enabled, TombstoneTracker logs the destruction callstack:

Godot::DisposedObjectError: Attempted to access destroyed object #1536105194213 (Enemy)
Object was previously destroyed at:
  src/combat/enemy.cr:42 in 'die'
  src/combat/battle.cr:115 in 'process_turn'

def self.topic_04_signal_spy : Nil #

Godot::Diagnostics::SignalSpy: Intercepting and tracing scene tree signal emissions.

When compiled with -Dtrace_signals or lapis build --trace-signals, every emit_signal call across the scene tree is intercepted and printed:

[SignalSpy] Player#1536105194213 emitted 'health_changed' with 2 args: [85, 100]
[SignalSpy] Door#1536105194215 emitted 'opened' with 0 args: []