godot_dev_tools 0.2.0: app_errors reporter addon

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-11-17 21:40:55 +01:00
parent 1ea7dfd6d5
commit 50781df0bc
9 changed files with 437 additions and 3 deletions

View File

@ -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/<app>.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,

View File

@ -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/<app>.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()

View File

@ -0,0 +1 @@
uid://8royr22sfg7a

View File

@ -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

View File

@ -0,0 +1 @@
uid://ck74fh55cpf8f

View File

@ -1,4 +1,4 @@
; Release of the dev_tools addon. The git tag is godot-dev-tools-v<version>.
[addon]
version = "0.1.1"
version = "0.2.0"

View File

@ -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.

View File

@ -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")

View File

@ -0,0 +1 @@
uid://brlqp63lcn6c3