telemetry/core - Telemetry Event Collection System

Reference for extensions.telemetry.core, the central telemetry system that collects, buffers, and persists gameplay events to JSONL files.

Overview

Provides an event-based telemetry system with buffered file output. Events are added as Lua tables with a required name field, automatically timestamped, and flushed to disk in JSONL format every 100 events. Supports activity duration tracking (start/end pairs). Auto-discovers and loads tracker extensions from the telemetry/trackers/ subdirectory.

Exports

Internals

• eventBuffer: string.buffer for efficient event accumulation
• Session ID: YYYY-MM-DDTHH-MM-SSZ_<sha256hash> - unique per session
• File output: /telemetry/<sessionId>.jsonl - one JSON object per line
• Auto-flush: Every 100 events triggers a file write
• No-op mode: When eventBuffer is nil, addEvent returns immediately (zero overhead)
• Debug mode: Validates event names are camelCase starting with lowercase, checks for reserved fields

Activation Conditions

-- In non-shipping builds: always enabled (for developers)
-- In shipping builds: requires all of:
--   1. No tech license
--   2. onlineFeatures == 'enable'
--   3. telemetry == 'enable'

Tracker Loading

Trackers are auto-discovered from telemetry/trackers/*.lua and loaded in priority order:

• session tracker: priority 1 (loaded first, unloaded last)
• All others: priority 500 (default)

How It Works

-- Add a simple event
extensions.telemetry_core.addEvent({
  name = "vehicleSpawned",
  model = "etk800",
  level = "west_coast_usa"
})

-- Track an activity with duration
extensions.telemetry_core.startActivity("freeroam", {level = "italy"})
-- ... player does stuff ...
extensions.telemetry_core.endActivity("freeroam", {duration = 300})

-- Events are auto-timestamped:
-- {"name":"vehicleSpawned","model":"etk800","level":"west_coast_usa","t":1234567.89}

Event Validation (Debug Mode)

-- These would log errors in debug mode:
addEvent({name = "BadName"})     -- starts with uppercase
addEvent({name = "bad name"})    -- contains space
addEvent({name = "bad-name"})    -- contains hyphen
addEvent({t = 123})              -- reserved field 't'

File Output Format

/telemetry/2024-01-15T10-30-00Z_abc123.jsonl

Each line is a JSON object:

{"name":"vehicleSpawned","model":"etk800","t":1705312200.123}
{"name":"freeroam","type":"start","level":"italy","t":1705312201.456}

Notes

• Manual unload mode - stays loaded to prevent errors
• Hooks into onTelemetryEventAdded for tracker extensions to observe events
• Uses os.clockhp() for high-precision timestamps
• Session ID includes randomized SHA256 hash for uniqueness

Additional Exports

• M.addEvent - (undocumented)
• M.endActivity - (undocumented)
• M.onExit - (undocumented)
• M.onExtensionLoaded - (undocumented)
• M.onExtensionUnloaded - (undocumented)
• M.onSettingsChanged - (undocumented)
• M.saveTelemetryData - (undocumented)
• M.startActivity - (undocumented)