mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-18 20:34:33 +01:00
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:
parent
1ea7dfd6d5
commit
50781df0bc
@ -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,
|
||||
|
||||
202
godot_dev_tools/addons/app_errors/error_reporter.gd
Normal file
202
godot_dev_tools/addons/app_errors/error_reporter.gd
Normal 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()
|
||||
1
godot_dev_tools/addons/app_errors/error_reporter.gd.uid
Normal file
1
godot_dev_tools/addons/app_errors/error_reporter.gd.uid
Normal file
@ -0,0 +1 @@
|
||||
uid://8royr22sfg7a
|
||||
27
godot_dev_tools/addons/app_errors/reporter_logger.gd
Normal file
27
godot_dev_tools/addons/app_errors/reporter_logger.gd
Normal 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
|
||||
1
godot_dev_tools/addons/app_errors/reporter_logger.gd.uid
Normal file
1
godot_dev_tools/addons/app_errors/reporter_logger.gd.uid
Normal file
@ -0,0 +1 @@
|
||||
uid://ck74fh55cpf8f
|
||||
@ -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"
|
||||
|
||||
@ -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.
|
||||
|
||||
180
godot_dev_tools/tests/test_error_reporter.gd
Normal file
180
godot_dev_tools/tests/test_error_reporter.gd
Normal 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")
|
||||
1
godot_dev_tools/tests/test_error_reporter.gd.uid
Normal file
1
godot_dev_tools/tests/test_error_reporter.gd.uid
Normal file
@ -0,0 +1 @@
|
||||
uid://brlqp63lcn6c3
|
||||
Loading…
Reference in New Issue
Block a user