godot-runtime-telemetry-lab 0.1.0__tar.gz

godot_runtime_telemetry_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Godot Runtime Telemetry Lab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

godot_runtime_telemetry_lab-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: godot-runtime-telemetry-lab
+Version: 0.1.0
+Summary: Summarize and compare Godot runtime telemetry, frame budgets, and scenario performance evidence.
+Author: Godot Runtime Telemetry Lab contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NonniGB/godot-production-toolkit/tree/main/godot-runtime-telemetry-lab
+Project-URL: Issues, https://github.com/NonniGB/godot-production-toolkit/issues
+Keywords: godot,telemetry,performance,profiler,gamedev,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Godot Runtime Telemetry Lab
+
+`godot-runtime-telemetry-lab` summarizes and compares lightweight runtime
+telemetry from Godot scenario runs, smoke tests, soak tests, or project-owned
+debug exporters. It is designed for CI artifacts and release reviews, not as a
+replacement for Godot's built-in profiler.
+
+## Install
+
+```powershell
+python -m pip install godot-runtime-telemetry-lab
+```
+
+From a source checkout:
+
+```powershell
+python -m pip install -e .\godot-runtime-telemetry-lab
+```
+
+## Quick Start
+
+```powershell
+godot-telemetry-lab summarize reports\runtime --format markdown --output reports\runtime.md
+godot-telemetry-lab compare reports\baseline reports\current --format json --output reports\runtime-compare.json
+```
+
+## Input Shape
+
+The tool accepts `.json` or `.csv` files. JSON files can contain a list of
+samples, or an object with a `samples`, `frames`, or `events` list.
+
+```json
+{
+  "samples": [
+    {"scenario": "menu", "frame_ms": 12.4, "physics_ms": 2.1, "memory_mb": 180},
+    {"scenario": "menu", "frame_ms": 18.8, "physics_ms": 2.5, "memory_mb": 181}
+  ]
+}
+```
+
+Recognized numeric fields are `frame_ms`, `physics_ms`, `memory_mb`, `nodes`,
+and `draw_calls`. Unknown fields are ignored by the first release.
+
+## Commands
+
+- `summarize`: reports sample counts, frame percentiles, and budget findings.
+- `compare`: compares current telemetry with a baseline and reports regressions.
+
+## Outputs
+
+- `text`: local terminal report.
+- `json`: CI and scripts.
+- `markdown`: PR comments and release notes.

godot_runtime_telemetry_lab-0.1.0/README.md

@@ -0,0 +1,53 @@
+# Godot Runtime Telemetry Lab
+
+`godot-runtime-telemetry-lab` summarizes and compares lightweight runtime
+telemetry from Godot scenario runs, smoke tests, soak tests, or project-owned
+debug exporters. It is designed for CI artifacts and release reviews, not as a
+replacement for Godot's built-in profiler.
+
+## Install
+
+```powershell
+python -m pip install godot-runtime-telemetry-lab
+```
+
+From a source checkout:
+
+```powershell
+python -m pip install -e .\godot-runtime-telemetry-lab
+```
+
+## Quick Start
+
+```powershell
+godot-telemetry-lab summarize reports\runtime --format markdown --output reports\runtime.md
+godot-telemetry-lab compare reports\baseline reports\current --format json --output reports\runtime-compare.json
+```
+
+## Input Shape
+
+The tool accepts `.json` or `.csv` files. JSON files can contain a list of
+samples, or an object with a `samples`, `frames`, or `events` list.
+
+```json
+{
+  "samples": [
+    {"scenario": "menu", "frame_ms": 12.4, "physics_ms": 2.1, "memory_mb": 180},
+    {"scenario": "menu", "frame_ms": 18.8, "physics_ms": 2.5, "memory_mb": 181}
+  ]
+}
+```
+
+Recognized numeric fields are `frame_ms`, `physics_ms`, `memory_mb`, `nodes`,
+and `draw_calls`. Unknown fields are ignored by the first release.
+
+## Commands
+
+- `summarize`: reports sample counts, frame percentiles, and budget findings.
+- `compare`: compares current telemetry with a baseline and reports regressions.
+
+## Outputs
+
+- `text`: local terminal report.
+- `json`: CI and scripts.
+- `markdown`: PR comments and release notes.

godot_runtime_telemetry_lab-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "godot-runtime-telemetry-lab"
+version = "0.1.0"
+description = "Summarize and compare Godot runtime telemetry, frame budgets, and scenario performance evidence."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Godot Runtime Telemetry Lab contributors" }]
+keywords = ["godot", "telemetry", "performance", "profiler", "gamedev", "ci"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Utilities"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/NonniGB/godot-production-toolkit/tree/main/godot-runtime-telemetry-lab"
+Issues = "https://github.com/NonniGB/godot-production-toolkit/issues"
+
+[project.scripts]
+godot-telemetry-lab = "godot_runtime_telemetry_lab.cli:entrypoint"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

godot_runtime_telemetry_lab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab/__init__.py

@@ -0,0 +1,3 @@
+"""Runtime telemetry summaries for Godot projects."""
+
+__version__ = "0.1.0"

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab/__main__.py

@@ -0,0 +1,5 @@
+from .cli import entrypoint
+
+
+if __name__ == "__main__":
+    entrypoint()

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab/cli.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from .telemetry import compare, render, summarize
+
+VERSION_LABEL = "godot-telemetry-lab 0.1.0"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Summarize and compare Godot runtime telemetry.")
+    parser.add_argument("--version", action="version", version=VERSION_LABEL)
+    subparsers = parser.add_subparsers(dest="command")
+
+    summarize_parser = subparsers.add_parser("summarize", help="Summarize JSON or CSV telemetry samples.")
+    summarize_parser.add_argument("path")
+    _add_common_args(summarize_parser)
+
+    compare_parser = subparsers.add_parser("compare", help="Compare current telemetry with a baseline.")
+    compare_parser.add_argument("baseline")
+    compare_parser.add_argument("current")
+    compare_parser.add_argument("--regression-ratio", type=float, default=1.25)
+    _add_common_args(compare_parser)
+
+    args = parser.parse_args(argv)
+    if args.command == "summarize":
+        report = summarize(Path(args.path), args.frame_budget_ms)
+    elif args.command == "compare":
+        report = compare(Path(args.baseline), Path(args.current), args.frame_budget_ms, args.regression_ratio)
+    else:
+        parser.print_help()
+        return 2
+
+    _emit(render(report, args.format), args.output)
+    return _exit_code(report, args.fail_on)
+
+
+def entrypoint() -> None:
+    raise SystemExit(main())
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--frame-budget-ms", type=float, default=16.67)
+    parser.add_argument("--format", choices=["text", "json", "markdown"], default="text")
+    parser.add_argument("--output")
+    parser.add_argument("--fail-on", choices=["none", "warning", "error"], default="error")
+
+
+def _emit(rendered: str, output: str | None) -> None:
+    if output:
+        output_path = Path(output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered + "\n", encoding="utf-8")
+    else:
+        print(rendered)
+
+
+def _exit_code(report: dict[str, object], fail_on: str) -> int:
+    summary = report["summary"]
+    if fail_on == "none":
+        return 0
+    if fail_on == "warning":
+        return 1 if int(summary["errors"]) + int(summary["warnings"]) > 0 else 0
+    return 1 if int(summary["errors"]) > 0 else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab/telemetry.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from statistics import mean
+from typing import Any
+
+from . import __version__
+
+
+NUMERIC_FIELDS = ("frame_ms", "physics_ms", "memory_mb", "nodes", "draw_calls")
+
+
+def summarize(path: Path, frame_budget_ms: float = 16.67) -> dict[str, Any]:
+    samples = load_samples(path)
+    summary = _summary(samples)
+    findings = _findings(summary, frame_budget_ms)
+    return {
+        "tool": "godot-runtime-telemetry-lab",
+        "tool_version": __version__,
+        "schema_version": "1.0",
+        "kind": "runtime_telemetry_summary",
+        "summary": summary,
+        "findings": findings,
+    }
+
+
+def compare(baseline: Path, current: Path, frame_budget_ms: float = 16.67, regression_ratio: float = 1.25) -> dict[str, Any]:
+    baseline_report = summarize(baseline, frame_budget_ms)
+    current_report = summarize(current, frame_budget_ms)
+    findings = list(current_report["findings"])
+    baseline_p95 = float(baseline_report["summary"]["frame_ms"]["p95"])
+    current_p95 = float(current_report["summary"]["frame_ms"]["p95"])
+    if baseline_p95 > 0 and current_p95 >= baseline_p95 * regression_ratio:
+        findings.append(
+            {
+                "rule_id": "frame_p95_regression",
+                "severity": "warning",
+                "message": (
+                    f"Frame p95 rose from {baseline_p95:.2f} ms to {current_p95:.2f} ms "
+                    f"at a {regression_ratio:g}x regression threshold."
+                ),
+                "rule_help": "Compare recent runtime, rendering, loading, and scenario changes before updating the baseline.",
+            }
+        )
+    return {
+        "tool": "godot-runtime-telemetry-lab",
+        "tool_version": __version__,
+        "schema_version": "1.0",
+        "kind": "runtime_telemetry_compare",
+        "baseline": baseline_report["summary"],
+        "current": current_report["summary"],
+        "summary": {
+            "errors": sum(1 for finding in findings if finding["severity"] == "error"),
+            "warnings": sum(1 for finding in findings if finding["severity"] == "warning"),
+            "samples": current_report["summary"]["samples"],
+        },
+        "findings": findings,
+    }
+
+
+def load_samples(path: Path) -> list[dict[str, Any]]:
+    files = [path] if path.is_file() else sorted(path.glob("*.json")) + sorted(path.glob("*.csv"))
+    samples: list[dict[str, Any]] = []
+    for file_path in files:
+        if file_path.suffix.lower() == ".csv":
+            samples.extend(_load_csv(file_path))
+        elif file_path.suffix.lower() == ".json":
+            samples.extend(_load_json(file_path))
+    return samples
+
+
+def render(report: dict[str, Any], output_format: str) -> str:
+    if output_format == "json":
+        return json.dumps(report, indent=2, sort_keys=True)
+    if output_format == "markdown":
+        return _markdown(report)
+    return _text(report)
+
+
+def _load_json(path: Path) -> list[dict[str, Any]]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(data, list):
+        return [item for item in data if isinstance(item, dict)]
+    if isinstance(data, dict):
+        for key in ("samples", "frames", "events"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return [item for item in value if isinstance(item, dict)]
+        return [data]
+    return []
+
+
+def _load_csv(path: Path) -> list[dict[str, Any]]:
+    with path.open("r", encoding="utf-8", newline="") as handle:
+        return [dict(row) for row in csv.DictReader(handle)]
+
+
+def _summary(samples: list[dict[str, Any]]) -> dict[str, Any]:
+    scenarios = sorted({str(sample.get("scenario", "default")) for sample in samples})
+    return {
+        "samples": len(samples),
+        "scenarios": scenarios,
+        "errors": 0,
+        "warnings": 0,
+        **{field: _metric(samples, field) for field in NUMERIC_FIELDS},
+    }
+
+
+def _metric(samples: list[dict[str, Any]], field: str) -> dict[str, float]:
+    values = sorted(_number(sample.get(field)) for sample in samples if _number(sample.get(field)) is not None)
+    if not values:
+        return {"min": 0.0, "avg": 0.0, "p95": 0.0, "max": 0.0}
+    return {
+        "min": values[0],
+        "avg": mean(values),
+        "p95": _percentile(values, 0.95),
+        "max": values[-1],
+    }
+
+
+def _findings(summary: dict[str, Any], frame_budget_ms: float) -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+    p95 = float(summary["frame_ms"]["p95"])
+    if p95 > frame_budget_ms:
+        findings.append(
+            {
+                "rule_id": "frame_p95_over_budget",
+                "severity": "warning",
+                "message": f"Frame p95 is {p95:.2f} ms, above the {frame_budget_ms:g} ms budget.",
+                "rule_help": "Inspect scenario phases and recent rendering or script changes around the slow frames.",
+            }
+        )
+    return findings
+
+
+def _number(value: object) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _percentile(values: list[float], fraction: float) -> float:
+    if len(values) == 1:
+        return values[0]
+    index = round((len(values) - 1) * fraction)
+    return values[index]
+
+
+def _text(report: dict[str, Any]) -> str:
+    summary = report["summary"]
+    lines = [
+        "Godot Runtime Telemetry Lab",
+        f"Samples: {summary['samples']} | Errors: {summary['errors']} | Warnings: {summary['warnings']}",
+        f"Frame p95: {summary['frame_ms']['p95']:.2f} ms | max: {summary['frame_ms']['max']:.2f} ms",
+    ]
+    for finding in report["findings"]:
+        lines.append(f"- {finding['severity'].upper()} {finding['rule_id']}: {finding['message']}")
+    return "\n".join(lines)
+
+
+def _markdown(report: dict[str, Any]) -> str:
+    summary = report["summary"]
+    lines = [
+        "# Godot Runtime Telemetry",
+        "",
+        "| Metric | Value |",
+        "|---|---:|",
+        f"| Samples | {summary['samples']} |",
+        f"| Frame p95 ms | {summary['frame_ms']['p95']:.2f} |",
+        f"| Frame max ms | {summary['frame_ms']['max']:.2f} |",
+        f"| Warnings | {summary['warnings']} |",
+        "",
+        "## Findings",
+        "",
+    ]
+    if not report["findings"]:
+        lines.append("No telemetry findings.")
+    else:
+        lines.extend(["| Severity | Rule | Message |", "|---|---|---|"])
+        for finding in report["findings"]:
+            lines.append(f"| {finding['severity']} | `{finding['rule_id']}` | {finding['message']} |")
+    return "\n".join(lines)

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: godot-runtime-telemetry-lab
+Version: 0.1.0
+Summary: Summarize and compare Godot runtime telemetry, frame budgets, and scenario performance evidence.
+Author: Godot Runtime Telemetry Lab contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NonniGB/godot-production-toolkit/tree/main/godot-runtime-telemetry-lab
+Project-URL: Issues, https://github.com/NonniGB/godot-production-toolkit/issues
+Keywords: godot,telemetry,performance,profiler,gamedev,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Godot Runtime Telemetry Lab
+
+`godot-runtime-telemetry-lab` summarizes and compares lightweight runtime
+telemetry from Godot scenario runs, smoke tests, soak tests, or project-owned
+debug exporters. It is designed for CI artifacts and release reviews, not as a
+replacement for Godot's built-in profiler.
+
+## Install
+
+```powershell
+python -m pip install godot-runtime-telemetry-lab
+```
+
+From a source checkout:
+
+```powershell
+python -m pip install -e .\godot-runtime-telemetry-lab
+```
+
+## Quick Start
+
+```powershell
+godot-telemetry-lab summarize reports\runtime --format markdown --output reports\runtime.md
+godot-telemetry-lab compare reports\baseline reports\current --format json --output reports\runtime-compare.json
+```
+
+## Input Shape
+
+The tool accepts `.json` or `.csv` files. JSON files can contain a list of
+samples, or an object with a `samples`, `frames`, or `events` list.
+
+```json
+{
+  "samples": [
+    {"scenario": "menu", "frame_ms": 12.4, "physics_ms": 2.1, "memory_mb": 180},
+    {"scenario": "menu", "frame_ms": 18.8, "physics_ms": 2.5, "memory_mb": 181}
+  ]
+}
+```
+
+Recognized numeric fields are `frame_ms`, `physics_ms`, `memory_mb`, `nodes`,
+and `draw_calls`. Unknown fields are ignored by the first release.
+
+## Commands
+
+- `summarize`: reports sample counts, frame percentiles, and budget findings.
+- `compare`: compares current telemetry with a baseline and reports regressions.
+
+## Outputs
+
+- `text`: local terminal report.
+- `json`: CI and scripts.
+- `markdown`: PR comments and release notes.

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/godot_runtime_telemetry_lab/__init__.py
+src/godot_runtime_telemetry_lab/__main__.py
+src/godot_runtime_telemetry_lab/cli.py
+src/godot_runtime_telemetry_lab/telemetry.py
+src/godot_runtime_telemetry_lab.egg-info/PKG-INFO
+src/godot_runtime_telemetry_lab.egg-info/SOURCES.txt
+src/godot_runtime_telemetry_lab.egg-info/dependency_links.txt
+src/godot_runtime_telemetry_lab.egg-info/entry_points.txt
+src/godot_runtime_telemetry_lab.egg-info/top_level.txt
+tests/test_runtime_telemetry_lab.py

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+godot-telemetry-lab = godot_runtime_telemetry_lab.cli:entrypoint

godot_runtime_telemetry_lab-0.1.0/src/godot_runtime_telemetry_lab.egg-info/top_level.txt

@@ -0,0 +1 @@
+godot_runtime_telemetry_lab

godot_runtime_telemetry_lab-0.1.0/tests/test_runtime_telemetry_lab.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from contextlib import redirect_stdout
+from io import StringIO
+import json
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from godot_runtime_telemetry_lab.cli import main
+
+
+class RuntimeTelemetryLabTests(unittest.TestCase):
+    def test_summarize_reports_frame_budget_warning(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "telemetry.json"
+            path.write_text(
+                json.dumps({"samples": [{"scenario": "menu", "frame_ms": 12}, {"scenario": "menu", "frame_ms": 24}]}),
+                encoding="utf-8",
+            )
+            stdout = StringIO()
+
+            with redirect_stdout(stdout):
+                exit_code = main(["summarize", str(path), "--frame-budget-ms", "16", "--format", "json", "--fail-on", "none"])
+
+            report = json.loads(stdout.getvalue())
+            self.assertEqual(exit_code, 0)
+            self.assertEqual(report["tool_version"], "0.1.0")
+            self.assertEqual(report["summary"]["samples"], 2)
+            self.assertEqual(report["findings"][0]["rule_id"], "frame_p95_over_budget")
+
+    def test_compare_reports_regression(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            baseline = root / "baseline.json"
+            current = root / "current.json"
+            baseline.write_text(json.dumps([{"frame_ms": 10}, {"frame_ms": 12}]), encoding="utf-8")
+            current.write_text(json.dumps([{"frame_ms": 20}, {"frame_ms": 24}]), encoding="utf-8")
+            stdout = StringIO()
+
+            with redirect_stdout(stdout):
+                exit_code = main(["compare", str(baseline), str(current), "--format", "json", "--fail-on", "none"])
+
+            report = json.loads(stdout.getvalue())
+            self.assertEqual(exit_code, 0)
+            rules = {finding["rule_id"] for finding in report["findings"]}
+            self.assertIn("frame_p95_regression", rules)
+
+
+if __name__ == "__main__":
+    unittest.main()