From 50781df0bc62bb9b2dee6f47dfdc615e0aa07bb8 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Tue, 17 Nov 2026 21:40:55 +0100 Subject: [PATCH] godot_dev_tools 0.2.0: app_errors reporter addon Co-Authored-By: Claude Opus 5.5 --- godot_dev_tools/README.md | 24 ++- .../addons/app_errors/error_reporter.gd | 202 ++++++++++++++++++ .../addons/app_errors/error_reporter.gd.uid | 1 + .../addons/app_errors/reporter_logger.gd | 27 +++ .../addons/app_errors/reporter_logger.gd.uid | 1 + .../addons/dev_tools/dev_tools.cfg | 2 +- godot_dev_tools/lint.sh | 2 +- godot_dev_tools/tests/test_error_reporter.gd | 180 ++++++++++++++++ .../tests/test_error_reporter.gd.uid | 1 + 9 files changed, 437 insertions(+), 3 deletions(-) create mode 100644 godot_dev_tools/addons/app_errors/error_reporter.gd create mode 100644 godot_dev_tools/addons/app_errors/error_reporter.gd.uid create mode 100644 godot_dev_tools/addons/app_errors/reporter_logger.gd create mode 100644 godot_dev_tools/addons/app_errors/reporter_logger.gd.uid create mode 100644 godot_dev_tools/tests/test_error_reporter.gd create mode 100644 godot_dev_tools/tests/test_error_reporter.gd.uid diff --git a/godot_dev_tools/README.md b/godot_dev_tools/README.md index ea10295..9bf98b6 100644 --- a/godot_dev_tools/README.md +++ b/godot_dev_tools/README.md @@ -37,7 +37,7 @@ the tag (shallow), then link or copy `godot_dev_tools/addons/dev_tools` to `res://addons/dev_tools` and gitignore that path: ```bash -git clone --depth 1 --branch godot-dev-tools-v0.1.1 https://github.com/kuhyx/utils "$cache" +git clone --depth 1 --branch godot-dev-tools-v0.2.0 https://github.com/kuhyx/utils "$cache" ln -sfn "$cache/godot_dev_tools/addons/dev_tools" addons/dev_tools # CI: cp -a instead ``` @@ -56,6 +56,28 @@ if options.dev and ResourceLoader.exists(ADDON): Exclude `addons/dev_tools/*` from every export preset, and keep the host glue out of exports too. +## Error and slow-wait reporting (`addons/app_errors/`) + +The Godot reporter of kuhy's shared app-errors pipeline (utils +`DOCS-app-errors.md`), released under the same tag. Unlike dev_tools, mount it +in **every** build and keep it in exports: player errors are the point. + +```gdscript +const ERRORS := "res://addons/app_errors/error_reporter.gd" + +if ResourceLoader.exists(ERRORS): + var rep: Node = (load(ERRORS) as GDScript).new() + rep.setup("car-rental-sim", "kuhyx/car-rental-sim") + add_child(rep) + # rep.report_wait("level.load", msec), or begin_wait / end_wait +``` + +Script errors and `push_error` arrive through an `OS.add_logger` logger. Any +frame over 1 s becomes the wait `godot.frame`. Reports go to +`~/.local/state/app-errors-spool/.jsonl` on desktop Linux, and nothing is +written on web. The `app-errors` ingest timer turns them into board tickets. +Nothing shows on screen. + ## The host interface `setup(host)` takes ONE object of the game's own: any Object, no base class, diff --git a/godot_dev_tools/addons/app_errors/error_reporter.gd b/godot_dev_tools/addons/app_errors/error_reporter.gd new file mode 100644 index 0000000..f332849 --- /dev/null +++ b/godot_dev_tools/addons/app_errors/error_reporter.gd @@ -0,0 +1,202 @@ +extends Node +## Reports every error and every wait over 1 s of a Godot game to kuhy's shared +## app-errors pipeline (utils DOCS-app-errors.md). Mount it like dev_tools, but +## in every build, not only --dev runs: player errors are the point. +## +## var rep: Node = (load("res://addons/app_errors/error_reporter.gd") as GDScript).new() +## rep.setup("car-rental-sim", "kuhyx/car-rental-sim") +## add_child(rep) +## rep.report_wait("level.load", msec) # or begin_wait / end_wait +## +## Script errors and push_error arrive through an OS logger; a frame over 1 s is +## reported as the wait `godot.frame`. Each report is one JSON line in +## $XDG_STATE_HOME/app-errors-spool/.jsonl, which the PC's app-errors +## ingest turns into a board ticket. Desktop only (a web build has no spool), +## shows nothing on screen, and never reports from inside a report. Identical +## errors within WINDOW_SEC are dropped; at most MAX_PER_MINUTE are written. +## No class_name (the addon stays out of the global class cache). + +const ReporterLogger = preload("res://addons/app_errors/reporter_logger.gd") +const SLOW_KIND := "perf.slow" +const MARK := "res://" +const WINDOW_SEC := 30.0 +const MAX_PER_MINUTE := 20 +const MAX_SLOW_PER_MINUTE := 30 +const THRESHOLD_MS := 1000 +const KINDS := { + Logger.ERROR_TYPE_ERROR: "godot.error", + Logger.ERROR_TYPE_SCRIPT: "uncaught.gdscript", + Logger.ERROR_TYPE_SHADER: "godot.shader", +} + +## Seconds since the epoch (tests replace it). +var clock: Callable = Time.get_unix_time_from_system +## Folder of the spool; empty writes nothing (a web build). +var spool_dir := default_spool_dir() +var logger: Logger + +var _app := "" +var _repo := "" +var _build := 0 +var _version := "" +var _mutex := Mutex.new() +var _busy := false +var _seen := {} +var _minutes := {} +var _serial := 0 +var _frames := 0 + + +## The spool folder: $XDG_STATE_HOME (else ~/.local/state)/app-errors-spool; +## empty off desktop Linux. +static func default_spool_dir() -> String: + if not OS.has_feature("linuxbsd"): + return "" + var base := OS.get_environment("XDG_STATE_HOME") + if base == "": + base = OS.get_environment("HOME").path_join(".local/state") + return base.path_join("app-errors-spool") + + +## Names the game: `app` as the board shows it, `repo` as owner/name, and the +## build number when the game knows one. +func setup(app: String, repo: String, build := 0, version := "") -> void: + _app = app + _repo = repo + _build = build + _version = version + + +func _enter_tree() -> void: + logger = ReporterLogger.new(_on_error) + OS.add_logger(logger) + + +func _exit_tree() -> void: + OS.remove_logger(logger) + logger = null + + +func _process(delta: float) -> void: + _check_frame(delta) + + +## A frame that took over a second is a wait the player saw (the first frame +## is the boot, before the window shows anything). +func _check_frame(delta: float) -> void: + _frames += 1 + if _frames > 1 and delta * 1000.0 > THRESHOLD_MS: + _slow("godot.frame", roundi(delta * 1000.0), "frame-%d" % _frames) + + +## Reports a finished wait of `msec` on `operation` when it took over 1 s. +func report_wait(operation: String, msec: int) -> void: + if msec > THRESHOLD_MS: + _serial += 1 + _slow(operation, msec, "%s-%d" % [operation, _serial]) + + +## Starts timing a wait on `operation`; pass the result to end_wait. +func begin_wait(operation: String) -> Dictionary: + return {"operation": operation, "started": clock.call(), "ended": false} + + +## Ends a wait from begin_wait; repeat calls do nothing. +func end_wait(wait: Dictionary) -> void: + if wait.ended: + return + wait.ended = true + report_wait(wait.operation, roundi((clock.call() - wait.started) * 1000.0)) + + +func _on_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + error_type: int, + backtraces: Array[ScriptBacktrace] +) -> void: + if not KINDS.has(error_type): + return + var stack: Array[String] = [] + for bt in backtraces: + for i in bt.get_frame_count(): + stack.append( + ( + "%s:%d in %s" + % [bt.get_frame_file(i), bt.get_frame_line(i), bt.get_frame_function(i)] + ) + ) + if stack.is_empty() and file.begins_with(MARK): + stack.append("%s:%d in %s" % [file, line, function]) + var message := rationale if rationale != "" else code + _report(KINDS[error_type], message, stack) + + +func _report(kind: String, message: String, stack: Array[String]) -> void: + _mutex.lock() + if _busy: + _mutex.unlock() + return + _busy = true + var now: float = clock.call() + var key := "%s|%s" % [kind, message] + for seen_key in _seen.keys(): + if now - _seen[seen_key] >= WINDOW_SEC: + _seen.erase(seen_key) + if not _seen.has(key) and _allowed("error", MAX_PER_MINUTE, now): + _seen[key] = now + _write({"kind": kind, "error": message, "stack": stack}, now) + _busy = false + _mutex.unlock() + + +func _slow(operation: String, msec: int, wait_id: String) -> void: + _mutex.lock() + var now: float = clock.call() + if _allowed("slow", MAX_SLOW_PER_MINUTE, now): + var entry := { + "kind": SLOW_KIND, + "error": "%s waited %d ms" % [operation, msec], + "operation": operation, + "durationMs": msec, + "waitId": wait_id, + "still": false, + } + _write(entry, now) + _mutex.unlock() + + +func _allowed(bucket: String, cap: int, now: float) -> bool: + var minute: Array = _minutes.get(bucket, [now, 0]) + if now - minute[0] >= 60.0: + minute = [now, 0] + if minute[1] >= cap: + return false + _minutes[bucket] = [minute[0], minute[1] + 1] + return true + + +## Appends one entry; a missing spool folder is made, a failure drops it. +func _write(entry: Dictionary, now: float) -> void: + if spool_dir == "": + return + var ms := int(fmod(now, 1.0) * 1000.0) + entry.at = "%s.%03dZ" % [Time.get_datetime_string_from_unix_time(int(now)), ms] + entry.repo = _repo + entry.mark = MARK + entry.build = _build + if _version != "": + entry.version = _version + DirAccess.make_dir_recursive_absolute(spool_dir) + var path := spool_dir.path_join("%s.jsonl" % _app) + var file := FileAccess.open(path, FileAccess.READ_WRITE) + if file == null: + file = FileAccess.open(path, FileAccess.WRITE) + if file == null: + return + file.seek_end() + file.store_line(JSON.stringify(entry, "", true)) + file.close() diff --git a/godot_dev_tools/addons/app_errors/error_reporter.gd.uid b/godot_dev_tools/addons/app_errors/error_reporter.gd.uid new file mode 100644 index 0000000..7380eeb --- /dev/null +++ b/godot_dev_tools/addons/app_errors/error_reporter.gd.uid @@ -0,0 +1 @@ +uid://8royr22sfg7a diff --git a/godot_dev_tools/addons/app_errors/reporter_logger.gd b/godot_dev_tools/addons/app_errors/reporter_logger.gd new file mode 100644 index 0000000..5f1a390 --- /dev/null +++ b/godot_dev_tools/addons/app_errors/reporter_logger.gd @@ -0,0 +1,27 @@ +extends Logger +## Forwards engine and script errors to the error reporter. The engine may call +## a logger from any thread, so it only hands over; the reporter locks. +## No class_name (the addon stays out of the global class cache). + +var _sink: Callable + + +func _init(sink: Callable) -> void: + _sink = sink + + +func _log_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + _editor_notify: bool, + error_type: int, + script_backtraces: Array[ScriptBacktrace] +) -> void: + _sink.call(function, file, line, code, rationale, error_type, script_backtraces) + + +func _log_message(_message: String, _error: bool) -> void: + pass diff --git a/godot_dev_tools/addons/app_errors/reporter_logger.gd.uid b/godot_dev_tools/addons/app_errors/reporter_logger.gd.uid new file mode 100644 index 0000000..3962590 --- /dev/null +++ b/godot_dev_tools/addons/app_errors/reporter_logger.gd.uid @@ -0,0 +1 @@ +uid://ck74fh55cpf8f diff --git a/godot_dev_tools/addons/dev_tools/dev_tools.cfg b/godot_dev_tools/addons/dev_tools/dev_tools.cfg index 79d2db9..60f8036 100644 --- a/godot_dev_tools/addons/dev_tools/dev_tools.cfg +++ b/godot_dev_tools/addons/dev_tools/dev_tools.cfg @@ -1,4 +1,4 @@ ; Release of the dev_tools addon. The git tag is godot-dev-tools-v. [addon] -version = "0.1.1" +version = "0.2.0" diff --git a/godot_dev_tools/lint.sh b/godot_dev_tools/lint.sh index 2d4a43f..fbf66d8 100755 --- a/godot_dev_tools/lint.sh +++ b/godot_dev_tools/lint.sh @@ -19,7 +19,7 @@ main() { exit 1 } done - mapfile -t files < <(find "$HERE/addons/dev_tools" "$HERE/tests" -name '*.gd' -type f | sort) + mapfile -t files < <(find "$HERE/addons/dev_tools" "$HERE/addons/app_errors" "$HERE/tests" -name '*.gd' -type f | sort) # One process per tool, not xargs -P: parallel gdtoolkit processes race to # create their grammar cache dir (os.makedirs EEXIST) on a cold cache and # report a file as unopenable. diff --git a/godot_dev_tools/tests/test_error_reporter.gd b/godot_dev_tools/tests/test_error_reporter.gd new file mode 100644 index 0000000..2b486e8 --- /dev/null +++ b/godot_dev_tools/tests/test_error_reporter.gd @@ -0,0 +1,180 @@ +extends GutTest +## The app_errors addon: engine and script errors and slow waits become spool +## lines in the shape utils app_errors ingests (app_errors/README.md "Entry"). + +const Reporter = preload("res://addons/app_errors/error_reporter.gd") +const TmpDir = preload("res://tests/tmp_dir.gd") + +var _dir := TmpDir.path("app_errors") +var _rep: Node + + +func before_each() -> void: + _rep = Reporter.new() + _rep.spool_dir = ProjectSettings.globalize_path(_dir) + _rep.setup("car-rental-sim", "kuhyx/car-rental-sim", 12, "0.4.0") + _rep.clock = func() -> float: return 1800000000.0 + add_child_autofree(_rep) + + +func after_each() -> void: + TmpDir.remove_tree(_dir) + + +func _lines() -> Array: + var path := _dir.path_join("car-rental-sim.jsonl") + if not FileAccess.file_exists(path): + return [] + var out := [] + for line in FileAccess.get_file_as_string(path).split("\n", false): + out.append(JSON.parse_string(line)) + return out + + +func _none() -> Array[ScriptBacktrace]: + var out: Array[ScriptBacktrace] = [] + return out + + +func _script_error(message: String) -> void: + _rep.logger._log_error( + "_ready", "res://scripts/car.gd", 77, message, "", false, Logger.ERROR_TYPE_SCRIPT, _none() + ) + + +func test_script_error_is_one_entry() -> void: + _script_error("Invalid access to property 'x'") + var lines := _lines() + assert_eq(lines.size(), 1) + var entry: Dictionary = lines[0] + assert_eq(entry.kind, "uncaught.gdscript") + assert_eq(entry.error, "Invalid access to property 'x'") + assert_eq(entry.repo, "kuhyx/car-rental-sim") + assert_eq(entry.mark, "res://") + assert_eq(int(entry.build), 12) + assert_eq(entry.version, "0.4.0") + assert_eq(entry.at, "2027-01-15T08:00:00.000Z") + assert_eq(entry.stack, ["res://scripts/car.gd:77 in _ready"]) + + +func test_push_error_uses_the_script_backtrace() -> void: + var bts := _none() + bts.append(ScriptBacktrace.new()) + _rep.logger._log_error( + "push_error", + "core/variant/variant_utility.cpp", + 1023, + "deliberate", + "", + false, + Logger.ERROR_TYPE_ERROR, + bts + ) + var entry: Dictionary = _lines()[0] + assert_eq(entry.kind, "godot.error") + assert_eq(entry.error, "deliberate") + assert_eq(entry.stack, [], "an empty backtrace and a C++ file give no frames") + + +func test_rationale_wins_over_code() -> void: + _rep.logger._log_error( + "f", + "res://a.gd", + 1, + "p_index < 0", + "Index out of range", + false, + Logger.ERROR_TYPE_ERROR, + _none() + ) + assert_eq(_lines()[0].error, "Index out of range") + + +func test_warnings_are_ignored() -> void: + _rep.logger._log_error("f", "res://a.gd", 1, "w", "", false, Logger.ERROR_TYPE_WARNING, _none()) + _rep.logger._log_message("hello", false) + assert_eq(_lines(), []) + + +func test_identical_errors_are_deduplicated() -> void: + for i in 5: + _script_error("same") + assert_eq(_lines().size(), 1) + + +func test_rate_cap_per_minute() -> void: + for i in Reporter.MAX_PER_MINUTE + 4: + _script_error("e%d" % i) + assert_eq(_lines().size(), Reporter.MAX_PER_MINUTE) + + +func test_report_wait_over_threshold() -> void: + _rep.report_wait("level.load", 2000) + _rep.report_wait("level.load", 400) + var lines := _lines() + assert_eq(lines.size(), 1, "a wait under 1 s writes nothing") + var entry: Dictionary = lines[0] + assert_eq(entry.kind, "perf.slow") + assert_eq(entry.operation, "level.load") + assert_eq(int(entry.durationMs), 2000) + assert_eq(entry.error, "level.load waited 2000 ms") + + +func test_begin_and_end_wait() -> void: + var t := [1800000000.0] + _rep.clock = func() -> float: return t[0] + var wait: Dictionary = _rep.begin_wait("shop.open") + t[0] += 1.5 + _rep.end_wait(wait) + _rep.end_wait(wait) + assert_eq(_lines().size(), 1) + assert_eq(int(_lines()[0].durationMs), 1500) + + +func test_long_frame_is_a_stall() -> void: + _rep._check_frame(0.016) + _rep._check_frame(2.5) + var lines := _lines() + assert_eq(lines.size(), 1) + assert_eq(lines[0].operation, "godot.frame") + assert_eq(int(lines[0].durationMs), 2500) + + +func test_no_spool_dir_writes_nothing() -> void: + _rep.spool_dir = "" + _script_error("x") + assert_eq(_lines(), []) + + +func test_logger_is_removed_on_exit() -> void: + var rep: Node = Reporter.new() + rep.spool_dir = ProjectSettings.globalize_path(_dir) + rep.setup("x", "kuhyx/x") + add_child(rep) + var logger: Logger = rep.logger + assert_not_null(logger) + remove_child(rep) + assert_null(rep.logger) + rep.free() + + +func test_default_spool_dir_follows_xdg() -> void: + var saved := OS.get_environment("XDG_STATE_HOME") + OS.set_environment("XDG_STATE_HOME", "/tmp/xdg-state") + assert_eq(Reporter.default_spool_dir(), "/tmp/xdg-state/app-errors-spool") + OS.unset_environment("XDG_STATE_HOME") + assert_eq( + Reporter.default_spool_dir(), + OS.get_environment("HOME").path_join(".local/state/app-errors-spool") + ) + if saved != "": + OS.set_environment("XDG_STATE_HOME", saved) + + +func test_real_push_error_reaches_the_spool() -> void: + push_error("deliberate test error") + assert_push_error("deliberate test error") + var errors := [] + for entry in _lines(): + errors.append(entry.error) + assert_has(errors, "deliberate test error") diff --git a/godot_dev_tools/tests/test_error_reporter.gd.uid b/godot_dev_tools/tests/test_error_reporter.gd.uid new file mode 100644 index 0000000..cadc0c4 --- /dev/null +++ b/godot_dev_tools/tests/test_error_reporter.gd.uid @@ -0,0 +1 @@ +uid://brlqp63lcn6c3