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>
}

S3 event storage #

You can write files to an S3 bucket based on the following naming scheme: <shard>/'yyyy/MM/dd/kk/<service-instance-id>/yyyyMMdd-kkmmss_SSS'.jsonl.

To configure this plugin, use the class name pragma.telemetry.s3.S3TelemetryPlugin in your config. Once the values below have been set, events can be sent directly to the Telemetry service.

Config values:

valuedescription
eventBatchSizenumber of events that will be accumulated before being sent to S3
timeWindowPerBatchMillisamount of time between forced sends of events, mainly for low traffic environments
s3BucketNamename of the bucket for storage
shardNamename of the shard to differentiate between different environments
Example: Telemetry config

Example

game:
  pluginConfigs:
    TelemetryService.telemetryPlugin:
      class: "pragma.telemetry.s3.S3TelemetryPlugin"
      config:
        eventBatchSize: 10000
        timeWindowPerBatchMillis: 60000
        s3BucketName: "your-best-bucket"
        shardName: "your-best-shard-name"

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 #

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 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}"
  }
}

Store 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}"
}