performance_monitor.gd

Go to the documentation of this file.

extends RefCounted
 
 
 
const DataCacheManager = preload("res://scripts/systems/dataCacheManager/data_cache_manager.gd")
 
var enabled:bool = true
var max_frame_samples:int = 240
var timers:Dictionary = {}
var active_timers:Dictionary = {}
var counters:Dictionary = {}
var gauges:Dictionary = {}
var marks:Array = []
var frame_samples:Array = []
var data_cache_manager = DataCacheManager.new()
 
 
func configure(options:Dictionary = {}) -> void:
    enabled = bool(options.get("enabled", enabled))
    max_frame_samples = max(1, int(options.get("max_frame_samples", max_frame_samples)))
    _trim_frame_samples()
 
 
func reset() -> void:
    timers.clear()
    active_timers.clear()
    counters.clear()
    gauges.clear()
    marks.clear()
    frame_samples.clear()
 
 
func start_timer(id:String) -> void:
    if not enabled or id.is_empty():
        return
    active_timers[id] = Time.get_ticks_usec()
 
 
func stop_timer(id:String, metadata:Dictionary = {}) -> Dictionary:
    if not enabled or id.is_empty():
        return {}
    if not active_timers.has(id):
        return {}
    var start_usec:int = int(active_timers.get(id, Time.get_ticks_usec()))
    active_timers.erase(id)
    var duration_usec:int = max(0, Time.get_ticks_usec() - start_usec)
    return record_duration(id, duration_usec, metadata)
 
 
func record_duration(id:String, duration_usec:int, metadata:Dictionary = {}) -> Dictionary:
    if not enabled or id.is_empty():
        return {}
    var normalized_duration:int = max(0, duration_usec)
    var aggregate:Dictionary = timers.get(id, {
        "count": 0,
        "total_usec": 0,
        "min_usec": normalized_duration,
        "max_usec": normalized_duration,
        "last_usec": 0,
        "last_metadata": {}
    })
    aggregate["count"] = int(aggregate.get("count", 0)) + 1
    aggregate["total_usec"] = int(aggregate.get("total_usec", 0)) + normalized_duration
    aggregate["min_usec"] = min(int(aggregate.get("min_usec", normalized_duration)), normalized_duration)
    aggregate["max_usec"] = max(int(aggregate.get("max_usec", normalized_duration)), normalized_duration)
    aggregate["last_usec"] = normalized_duration
    aggregate["last_metadata"] = metadata.duplicate(true)
    timers[id] = aggregate
    return {
        "id": id,
        "duration_usec": normalized_duration,
        "metadata": metadata.duplicate(true)
    }
 
 
func increment(id:String, amount:int = 1) -> int:
    if not enabled or id.is_empty():
        return int(counters.get(id, 0))
    var next_value:int = int(counters.get(id, 0)) + amount
    counters[id] = next_value
    return next_value
 
 
func set_gauge(id:String, value:Variant) -> void:
    if not enabled or id.is_empty():
        return
    gauges[id] = value
 
 
func mark(id:String, metadata:Dictionary = {}) -> Dictionary:
    if not enabled or id.is_empty():
        return {}
    var entry:Dictionary = {
        "id": id,
        "at_usec": Time.get_ticks_usec(),
        "metadata": metadata.duplicate(true)
    }
    marks.append(entry)
    return entry
 
 
func sample_frame(delta:float) -> Dictionary:
    if not enabled:
        return {}
    var normalized_delta:float = max(0.0, delta)
    var fps:float = 0.0
    if normalized_delta > 0.0:
        fps = 1.0 / normalized_delta
    var sample:Dictionary = {
        "delta": normalized_delta,
        "fps": fps,
        "at_usec": Time.get_ticks_usec()
    }
    frame_samples.append(sample)
    _trim_frame_samples()
    return sample
 
 
func capture_node_counts(root_node:Node, id:String = "nodes") -> Dictionary:
    if not enabled or root_node == null:
        return {}
    var counts:Dictionary = {
        "total": 0,
        "control": 0,
        "canvas_item": 0,
        "visible": 0,
        "hidden": 0
    }
    _count_node(root_node, counts)
    for key in counts.keys():
        set_gauge("%s.%s" % [id, str(key)], counts.get(key))
    return counts
 
 
func capture_provider_stats(id:String, provider:Object) -> Dictionary:
    if not enabled or id.is_empty() or provider == null:
        return {}
    var stats:Dictionary = _provider_stats(provider)
    for key in stats.keys():
        var value:Variant = stats.get(key)
        if value is int or value is float:
            set_gauge("%s.%s" % [id, str(key)], value)
    return stats
 
 
func measure_callable(id:String, action:Callable, metadata:Dictionary = {}) -> Dictionary:
    if not enabled or id.is_empty() or not action.is_valid():
        return {}
    var start_usec:int = Time.get_ticks_usec()
    var result:Variant = action.call()
    var sample:Dictionary = record_duration(id, max(0, Time.get_ticks_usec() - start_usec), metadata)
    sample["result"] = result
    return sample
 
 
func capture_provider_delta(id:String, provider:Object, action:Callable, metadata:Dictionary = {}) -> Dictionary:
    if not enabled or id.is_empty() or provider == null:
        return {}
    var before:Dictionary = _provider_stats(provider)
    var timed:Dictionary = measure_callable(id, action, metadata)
    var after:Dictionary = _provider_stats(provider)
    var delta:Dictionary = _numeric_delta(before, after)
    for key in delta.keys():
        set_gauge("%s.delta.%s" % [id, str(key)], delta.get(key))
    for key in after.keys():
        var value:Variant = after.get(key)
        if value is int or value is float:
            set_gauge("%s.after.%s" % [id, str(key)], value)
    return {
        "id": id,
        "before": before,
        "after": after,
        "delta": delta,
        "timing": timed
    }
 
 
func benchmark_scene_instantiation(id:String, packed_scene:PackedScene, parent:Node, iterations:int = 1, metadata:Dictionary = {}) -> Dictionary:
    if not enabled or id.is_empty() or packed_scene == null or parent == null:
        return {}
    var safe_iterations:int = max(1, iterations)
    var samples:Array = []
    var total_usec:int = 0
    var max_usec:int = 0
    var min_usec:int = 0
    var max_nodes:int = 0
    var before_parent_counts:Dictionary = capture_node_counts(parent, "%s.parent_before" % id)
    for index in range(safe_iterations):
        var start_usec:int = Time.get_ticks_usec()
        var instance:Node = packed_scene.instantiate()
        var instantiate_usec:int = max(0, Time.get_ticks_usec() - start_usec)
        total_usec += instantiate_usec
        max_usec = max(max_usec, instantiate_usec)
        min_usec = instantiate_usec if index == 0 else min(min_usec, instantiate_usec)
        if instance != null:
            parent.add_child(instance)
            var node_counts:Dictionary = capture_node_counts(instance, "%s.instance_%d" % [id, index])
            max_nodes = max(max_nodes, int(node_counts.get("total", 0)))
            parent.remove_child(instance)
            instance.free()
        samples.append({
            "iteration": index,
            "instantiate_usec": instantiate_usec
        })
    var average_usec:int = int(round(float(total_usec) / float(safe_iterations)))
    record_duration("%s.instantiate" % id, average_usec, metadata)
    var after_parent_counts:Dictionary = capture_node_counts(parent, "%s.parent_after" % id)
    var result:Dictionary = {
        "id": id,
        "iterations": safe_iterations,
        "total_usec": total_usec,
        "avg_usec": average_usec,
        "min_usec": min_usec,
        "max_usec": max_usec,
        "max_instance_nodes": max_nodes,
        "parent_before": before_parent_counts,
        "parent_after": after_parent_counts,
        "samples": samples
    }
    for key in ["iterations", "total_usec", "avg_usec", "min_usec", "max_usec", "max_instance_nodes"]:
        set_gauge("%s.%s" % [id, key], result.get(key))
    mark("%s.scene_benchmark" % id, {
        "iterations": safe_iterations,
        "avg_usec": average_usec,
        "max_instance_nodes": max_nodes
    })
    return result
 
 
func benchmark_scene_profiles(profiles:Array, parent:Node, options:Dictionary = {}) -> Dictionary:
    var results:Dictionary = {}
    var errors:Array = []
    for profile_value in profiles:
        if not profile_value is Dictionary:
            continue
        var profile:Dictionary = profile_value
        var id:String = str(profile.get("id", ""))
        var scene_path:String = str(profile.get("scene", ""))
        if id.is_empty() or scene_path.is_empty():
            errors.append({"id": id, "scene": scene_path, "error": "missing_id_or_scene"})
            continue
        var loaded_scene = load(scene_path)
        if loaded_scene == null or not loaded_scene is PackedScene:
            errors.append({"id": id, "scene": scene_path, "error": "scene_not_loaded"})
            continue
        var metadata:Dictionary = profile.duplicate(true)
        if options.has("metadata") and options["metadata"] is Dictionary:
            for key in options["metadata"].keys():
                metadata[key] = options["metadata"][key]
        var iterations:int = max(1, int(profile.get("iterations", options.get("iterations", 1))))
        results[id] = benchmark_scene_instantiation(id, loaded_scene, parent, iterations, metadata)
    return {
        "results": results,
        "errors": errors,
        "count": results.size()
    }
 
 
func load_baseline_profiles(file_path:String) -> Array:
    var data:Dictionary = data_cache_manager.load_json(file_path)
    if data is Dictionary and data.get("profiles", []) is Array:
        return data.get("profiles", [])
    return []
 
 
 
func get_cache_stats() -> Dictionary:
    return data_cache_manager.get_cache_stats()
 
 
func format_summary_text() -> String:
    return "\n".join(format_summary_lines())
 
 
func write_summary_file(file_path:String) -> bool:
    if file_path.is_empty():
        return false
    var file = FileAccess.open(file_path, FileAccess.WRITE)
    if file == null:
        return false
    file.store_string(JSON.stringify(get_summary(), "\t"))
    return true
 
 
func get_summary() -> Dictionary:
    return {
        "timers": _timer_summary(),
        "counters": counters.duplicate(true),
        "gauges": gauges.duplicate(true),
        "marks": marks.duplicate(true),
        "frames": _frame_summary()
    }
 
 
func get_state() -> Dictionary:
    return {
        "enabled": enabled,
        "max_frame_samples": max_frame_samples,
        "timers": timers.duplicate(true),
        "counters": counters.duplicate(true),
        "gauges": gauges.duplicate(true),
        "marks": marks.duplicate(true),
        "frame_samples": frame_samples.duplicate(true)
    }
 
 
func apply_state(state:Dictionary) -> void:
    enabled = bool(state.get("enabled", enabled))
    max_frame_samples = max(1, int(state.get("max_frame_samples", max_frame_samples)))
    timers = _dictionary_copy(state.get("timers", {}))
    active_timers.clear()
    counters = _dictionary_copy(state.get("counters", {}))
    gauges = _dictionary_copy(state.get("gauges", {}))
    marks = _array_copy(state.get("marks", []))
    frame_samples = _array_copy(state.get("frame_samples", []))
    _trim_frame_samples()
 
 
func format_summary_lines() -> Array:
    var lines:Array = []
    var summary:Dictionary = get_summary()
    var timer_summary:Dictionary = summary.get("timers", {})
    for timer_id in timer_summary.keys():
        var timer_data:Dictionary = timer_summary.get(timer_id, {})
        lines.append("%s: %s calls, avg %sus" % [
            str(timer_id),
            str(timer_data.get("count", 0)),
            str(timer_data.get("avg_usec", 0))
        ])
    for counter_id in counters.keys():
        lines.append("%s: %s" % [str(counter_id), str(counters.get(counter_id))])
    var frame_summary:Dictionary = summary.get("frames", {})
    if int(frame_summary.get("sample_count", 0)) > 0:
        lines.append("frames: avg %sfps, min %sfps" % [
            str(frame_summary.get("avg_fps", 0.0)),
            str(frame_summary.get("min_fps", 0.0))
        ])
    return lines
 
 
func _timer_summary() -> Dictionary:
    var summary:Dictionary = {}
    for id in timers.keys():
        var aggregate:Dictionary = timers.get(id, {})
        var count:int = max(0, int(aggregate.get("count", 0)))
        var avg_usec:int = 0
        if count > 0:
            avg_usec = int(round(float(aggregate.get("total_usec", 0)) / float(count)))
        var row:Dictionary = aggregate.duplicate(true)
        row["avg_usec"] = avg_usec
        summary[id] = row
    return summary
 
 
func _frame_summary() -> Dictionary:
    if frame_samples.is_empty():
        return {
            "sample_count": 0,
            "avg_delta": 0.0,
            "avg_fps": 0.0,
            "min_fps": 0.0,
            "max_delta": 0.0
        }
    var total_delta:float = 0.0
    var total_fps:float = 0.0
    var min_fps:float = INF
    var max_delta:float = 0.0
    for sample in frame_samples:
        var row:Dictionary = sample
        var delta:float = float(row.get("delta", 0.0))
        var fps:float = float(row.get("fps", 0.0))
        total_delta += delta
        total_fps += fps
        min_fps = min(min_fps, fps)
        max_delta = max(max_delta, delta)
    var sample_count:int = frame_samples.size()
    return {
        "sample_count": sample_count,
        "avg_delta": total_delta / float(sample_count),
        "avg_fps": total_fps / float(sample_count),
        "min_fps": min_fps,
        "max_delta": max_delta
    }
 
 
func _count_node(node:Node, counts:Dictionary) -> void:
    counts["total"] = int(counts.get("total", 0)) + 1
    if node is Control:
        counts["control"] = int(counts.get("control", 0)) + 1
    if node is CanvasItem:
        counts["canvas_item"] = int(counts.get("canvas_item", 0)) + 1
        if node.visible:
            counts["visible"] = int(counts.get("visible", 0)) + 1
        else:
            counts["hidden"] = int(counts.get("hidden", 0)) + 1
    for child in node.get_children():
        _count_node(child, counts)
 
 
func _provider_stats(provider:Object) -> Dictionary:
    if provider == null:
        return {}
    var stats:Dictionary = {}
    if provider.has_method("get_cache_stats"):
        stats = provider.call("get_cache_stats")
    elif provider.has_method("get_stats"):
        stats = provider.call("get_stats")
    return stats
 
 
func _numeric_delta(before:Dictionary, after:Dictionary) -> Dictionary:
    var delta:Dictionary = {}
    for key in after.keys():
        var after_value:Variant = after.get(key)
        if not (after_value is int or after_value is float):
            continue
        var before_value:Variant = before.get(key, 0)
        if not (before_value is int or before_value is float):
            before_value = 0
        delta[key] = after_value - before_value
    return delta
 
 
func _trim_frame_samples() -> void:
    while frame_samples.size() > max_frame_samples:
        frame_samples.pop_front()
 
 
func _dictionary_copy(value:Variant) -> Dictionary:
    if value is Dictionary:
        return value.duplicate(true)
    return {}
 
 
func _array_copy(value:Variant) -> Array:
    if value is Array:
        return value.duplicate(true)
    return []