Telemetry #

The Telemetry service accepts events from game clients, game services, Pragma Engine plugins, and custom services and forwards them to a big data store.

While telemetry applies to many different kinds of data collection, Pragma Engine uses it to describe high-volume, less structured, big data information. Pragma Engine provides a real-time telemetry event collector that terminates data into a data store of choice. Telemetry is useful for collecting high resolution data around specific questions or features, and requires post-processing to produce actionable insights.

The service accepts events in realtime and delegates to a configured storage provider. Studios can use standard, existing toolchains for data analytics and processing.

Data can be passed individually or in a batch, and messages are sent as JSON. Several standard fields are provided outside of the JSON payload to help with grouping, filtering, and aggregating events.

Operationalize #

While it’s possible to build reports and dashboards against raw telemetry data, it’s not recommended. The result will be dashboards that are slow to load due to the volume of data being processed. The reports will also be fragile, breaking when changes are made to the raw telemetry events. Instead, create ETLs that aggregate data into an operable format and build reports against these.

For example, exploratory queries and ad-hoc reports can be built against raw telemetry, but it is advisable to transform raw events into well-formed schemas that are tailored to their purpose. This improves performance, reliability, and reduces the cost and complexity of producing actionable insights.

Below is a sample workflow for building a game health report.

sequenceDiagram participant gs as Service | Client | Server participant t as Telemetry participant db as Storage (S3 or DB) participant s as ScheduledJob participant d as Dashboard participant o as Operator gs->>t:events t->>db:store(events) s->>db:runEtl(gameHealth) db->>db:storeGameHealthData() d->>db:retrieveGameHealthReport() o->>d:viewGameHealthDashboard()

Configuration #

The Telemetry service is configured through TelemetryServiceConfig:

OptionDefaultDescription
xxHash64Seed0The seed used in the xxhash64 hash of the event sourceId and eventName.
playerEventSourceIdPLAYER_IDThe session ID used as the event sourceId for player events recorded on the game backend. PLAYER_ID uses the session’s playerId; SOCIAL_ID uses the session’s socialId. Applies only to playerEventV1 and playerEventsV1.
globalWeight1000The global client telemetry sampling weight, 0–1000. 0 sends no events; 1000 sends all events.
perEventWeightemptyPer-event-name sampling weight overrides, 0–1000. Event names missing from this map use globalWeight.
alwaysEnabledIdsemptyIDs (playerId or socialId strings) whose sessions send client telemetry regardless of sampling weights. Only the key matters; the value is ignored.

Client event sampling #

globalWeight, perEventWeight, and alwaysEnabledIds control how much client-originated telemetry is sent. SDKs fetch the sampling config on the first telemetry send attempt of a connection, and config changes are broadcast to connected sessions in real time. alwaysEnabledIds is resolved per session on the platform—the list itself is never sent to clients.

game: # or social/telemetry
  serviceConfigs:
    TelemetryServiceConfig:
      globalWeight: 800
      perEventWeight:
        "event-a": 800
        "event-b": 50
      alwaysEnabledIds:
        "00000000-0000-0000-0000-000000000001": ""
        "00000000-0000-0000-0000-000000000002": ""

Dedicated Backend #

Telemetry can run on a dedicated backend, isolated from your game and social backends, so high-volume event traffic doesn’t compete with latency-sensitive gameplay RPCs. See Dedicated Telemetry Backend for details.

TopicDescription
PluginsUse a provided plugin or implement your own.
EventsSend events to Telemetry Service.
Schema of EventsIngest data for reporting.
Pragma AnalyticsEvents automatically sent by Pragma
Dedicated Telemetry BackendRun telemetry on its own backend, isolated from game and social.

Concepts
Plugins