Telemetry #

The Telemetry service accepts events from game clients, game services, Pragma Engine plugins, and custom services.

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.

Anatomy of an Event #

Event Sources #

The sourceId represents the source of an event, such as a player game client, or game server.

• Player events: Set by the platform from the player session.
• Trusted source events: Supplied by the caller (Partner, Operator, or Service gateways).
• Batch events: Caller specifies a sourceID for each event, enabling a game server to send events on behalf of all players in a game in a single batch.

Request Types #

Player event request

For events requested by a player.

{
  "event": {
    "name" : "player-open-menu",
    "json" : "{\n  \"menuClicked\": \"shopkeeper\",\n  \"durationMenuOpenSeconds\": 43,\n  \"interactionsInMenu\": 7\n, \"transactions\": 2\n}"
  }
}

Partner event request from a game server

For events from a game server.

{
  "sourceId": "game-server-1",
  "event": {
    "name": "boss-defeated",
    "json": "{\n  \"boss_id\": \"miniboss_1\",\n  \"damage_dealt\": 2200,\n  \"encounter_duration_sec\": 17\n}"
  }
}

Stored event

For recorded events.

{
  "name": "player-open-menu",
  "timestamp_millis" : 1646097667207,
  "id_hash": 3241420594091297482,
  "event_json": "{\n  \"menuClicked\": \"shopkeeper\",\n  \"durationMenuOpenSeconds\": 43,\n  \"interactionsInMenu\": 7\n, \"transactions\": 2\n}"
}

Understanding the Telemetry Plugin #

The Telemetry plugin allows users to persist events to a datastore of choice, either by configuring the implementations provided by the engine or by building a custom plugin implementation.

interface TelemetryPlugin {

    suspend fun recordEvent(event: Event)

    suspend fun recordEvents(events: List<Event>)

    suspend fun getEvents(): List<Event>
}

Topics in This Section #