Add Stats Logging System with Build Flag Control #374

wouterlucas · 2025-05-26T09:47:37Z

Summary

This PR adds a comprehensive stats logging system that tracks component, element, and event listener activity throughout the application. The system is fully controlled by a Vite build flag (__BLITS_STATS__), ensuring all stats-related code is optimized out of production builds for maximum performance.

Key Features

Build-Time Flag for Zero Runtime Overhead

Added __BLITS_STATS__ Vite flag to enable/disable stats at build time
Implemented dead code elimination for all stats code when flag is disabled
Exposed BLITS_STATS_ENABLED for use in other modules

Enhanced Statistics Collection

Added metrics tracking for components, elements, event listeners, timeouts, and intervals
Implemented rolling averages (1min, 5min, 15min) for load statistics
Added memory usage tracking (memory used, renderable memory, textures)
Added proper cleanup and guard conditions for all stats operations

Visual Stats Overlay Component

Created StatsOverlay component for real-time stats visualization
Component only renders when stats are enabled (returns null otherwise)
Displays system statistics and renderer memory information
Auto-updates every 500ms for live monitoring

Documentation

Added comprehensive documentation in docs/built-in/stats.md
Updated JSDoc comments throughout the codebase
Documented best practices for stats usage

Implementation Details

Fixed event listener registration bugs (typo: bla.set → eventsMap.set)
Made all increment/decrement calls conditional on the stats flag
Updated launch.js to only start logging if stats are enabled
Added bytesToMb utility function for memory formatting
Used memory information from renderer for additional insights

Testing

Manually tested in development environment with flag enabled
Verified bundle size reduction with flag disabled
Validated that stats overlay properly displays all metrics

Future Improvements

Consider adding CPU usage metrics
Add FPS metrics to the stats overlay
Potential for persistent logging to file for longer-term analysis

This change maintains the high-performance standards of Blits while providing valuable debug and monitoring capabilities for developers during the development process.

github-actions · 2025-05-26T09:48:21Z

Test Results: ❌ FAILED

Run at: 2025-05-26T09:48:06.409Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:


> @lightningjs/[email protected] test
> c8 npm run test:run


> @lightningjs/[email protected] test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/log' imported from /home/runner/work/blits/blits/src/lib/stats.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/log'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (521ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

github-actions · 2025-05-26T09:52:38Z

Test Results: ❌ FAILED

Run at: 2025-05-26T09:48:06.409Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:


> @lightningjs/[email protected] test
> c8 npm run test:run


> @lightningjs/[email protected] test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/log' imported from /home/runner/work/blits/blits/src/lib/stats.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/log'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (521ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

src/lib/stats.js

github-actions · 2025-05-26T11:04:46Z

Test Results: ❌ FAILED

Run at: 2025-05-26T11:04:33.055Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:


> @lightningjs/[email protected] test
> c8 npm run test:run


> @lightningjs/[email protected] test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/log' imported from /home/runner/work/blits/blits/src/lib/stats.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/log'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (498ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

github-actions · 2025-05-26T11:11:20Z

Test Results: ❌ FAILED

Run at: 2025-05-26T11:11:08.325Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:


> @lightningjs/[email protected] test
> c8 npm run test:run


> @lightningjs/[email protected] test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

(node:2169) ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/stats' imported from /home/runner/work/blits/blits/src/lib/eventListeners.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/stats'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (514ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

github-actions · 2025-05-26T12:14:33Z

Test Results: ✅ PASSED

Run at: 2025-05-26T12:14:21.408Z

Summary:
passed: 116 failed: 0 of 116 tests

github-actions · 2025-05-26T12:41:25Z

Test Results: ✅ PASSED

Run at: 2025-05-26T12:41:11.004Z

Summary:
passed: 116 failed: 0 of 116 tests

github-actions · 2025-05-26T14:08:08Z

Test Results: ✅ PASSED

Run at: 2025-05-26T14:07:55.319Z

Summary:
passed: 116 failed: 0 of 116 tests

github-actions · 2025-05-26T16:29:31Z

Test Results: ✅ PASSED

Run at: 2025-05-26T16:29:18.953Z

Summary:
passed: 521 failed: 0 of 521 tests

wouterlucas · 2025-05-26T16:30:09Z

Squashed and rebased against latest master, will need some @DouweCnossen or @erikhaandrikman love on the overlay. Maybe sprites down the road.

github-actions · 2025-05-27T07:35:11Z

Test Results: ✅ PASSED

Run at: 2025-05-27T07:34:57.281Z

Summary:
passed: 521 failed: 0 of 521 tests

github-actions · 2025-05-27T08:16:19Z

Test Results: ✅ PASSED

Run at: 2025-05-27T08:16:07.059Z

Summary:
passed: 116 failed: 0 of 116 tests

…imeouts, and intervals

…erlay

…_ENABLED

…listeners, timeouts and intervals.

github-actions · 2025-05-28T11:57:54Z

Test Results: ✅ PASSED

Run at: 2025-05-28T11:57:41.212Z

Summary:
passed: 521 failed: 0 of 521 tests

jfboeve reviewed May 26, 2025

View reviewed changes

src/lib/stats.js Outdated Show resolved Hide resolved

wouterlucas force-pushed the feat/stats branch from 62e36f5 to a4db86f Compare May 26, 2025 16:28

wouterlucas and others added 13 commits May 28, 2025 13:47

feat: add stats tracking for components, elements, event listeners, t…

81a11f7

…imeouts, and intervals

feat: implement stats tracking and logging mechanism with optional ov…

163f82e

…erlay

fix: update StatsOverlay to conditionally render based on BLITS_STATS…

bc7d073

…_ENABLED

fix: update import statement for Log module to include file extension

74f93a2

feat: Implement Blits Stats for debugging

c48fda1

feat: add force reset and print to stats

737db13

feat: Implement Blits Stats for debugging

78713f2

feat: add force reset and print to stats

c108a74

Added flag to indicate EOL state of component to prevent registering …

3457992

…listeners, timeouts and intervals.

feat: update logging

c9595e1

feat: Implement Blits Stats for debugging

7ddaa79

feat: add force reset and print to stats

c5e2ad8

feat: update logging

9f4460c

wouterlucas force-pushed the feat/stats branch from ee3ecb1 to 9f4460c Compare May 28, 2025 11:57

michielvandergeest self-requested a review as a code owner July 22, 2025 15:51

Add Stats Logging System with Build Flag Control #374

Are you sure you want to change the base?

Add Stats Logging System with Build Flag Control #374

Uh oh!

Conversation

wouterlucas commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Features

Build-Time Flag for Zero Runtime Overhead

Enhanced Statistics Collection

Visual Stats Overlay Component

Documentation

Implementation Details

Testing

Future Improvements

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ❌ FAILED

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ❌ FAILED

Uh oh!

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ❌ FAILED

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ❌ FAILED

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ✅ PASSED

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ✅ PASSED

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ✅ PASSED

Uh oh!

github-actions bot commented May 26, 2025

Test Results: ✅ PASSED

Uh oh!

wouterlucas commented May 26, 2025

Uh oh!

github-actions bot commented May 27, 2025

Test Results: ✅ PASSED

Uh oh!

github-actions bot commented May 27, 2025

Test Results: ✅ PASSED

Uh oh!

github-actions bot commented May 28, 2025

Test Results: ✅ PASSED

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

wouterlucas commented May 26, 2025 •

edited

Loading