Event Logging Setup

Introduction to Data Logging and Releases

This document outlines the steps necessary to integrate new game with the OpenGameData telemetry logging infrastructure.

The OGD pipeline is made up of the following steps:

  1. Game Client Logging

  2. Data Storage

  3. Data Transformations a. New Event Detection b. Feature Extraction c. (future work) Model Training

  4. Monthly Outputs

We provide various Open Game Data packages for use in each step of this process; you may freely use these, or substitute your own solution in for a given step. If you are only interested in event logging, the data transformations step may be ommitted from your project.

Game Client Logging

In this step of the pipeline, the game sends out telemetry events to be captured in a database. The steps needed to implement this part of the pipeline are:

  1. Identify and Design Game Events

  2. Implement Events

  3. Gameplay Testing

  4. Documentation

  5. Iteration

We’ll describe these steps in more detail below.

Identify and Design Game Events

  • Description: Choose the events to be logged, and design the structure of the data to be sent with each event.

  • Time Required: 1-4 hours, depending on the size/complexity of the game

In this very initial step, you will identify the events in your game, describe the data that belongs to each event, and document that description for later implementation. These events should be chosen to allow post-hoc reconstruction of gameplay. Please see Event Design for more information about choosing which events to log. If your game already implements some form of event logging, you may continue with your existing set of events, and simply port them to the Open Game Data system.

To maintain consistency of data across games, we use a standardized schema for events. If you use one of the logging packages provided by OpenGameData, this schema will be implicitly enforced; if you use a custom logging solution, we highly recommend following the standardized schema for maximum compatibility. Please see Open Game Data Event Schemas for more details.

Implement Events

  • Description: Implement logging for each event within the game code.

  • Time Required: 1-3 working days, depending on the size and complexity of the set of events to implement.

Once you have determined a set of events and the data to be logged with them, you will need to implement logging within your game. We recommend using one of the Open Game Data packages to ease this process. We currently have packages for Unity and JavaScript game projects. To get started, please see the readme guide for the package appropriate for your game:

  • For Unity: opengamedata-unity user’s guide

  • For JavaScript: opengamedata-js-log user’s guide

Note : If your implementation uses the Open Game Data logging servers, a table will need to be created for your game during this step. This will include a database table on the main production server and optionally the CI/testing server.

Gameplay Testing

  • Description: Test the logging implementation, recording any bugs that may have been created.

  • Time Required: Varies, likely 1-2 working days

After implementing new event logging in a game, the implementation should be tested for correctness and completeness. In particular, you should ensure the following:

  • The logging implementation does not lead to crashes in the game

  • The logging implementaiton does not create performance issues in the game, such as slow framerates.

  • Events are successfully sent to the logging server (see the event monitoring guide for more information).

  • Events have the correct content.

Documentation

  • Description: Produce documents formalizing and describing the event implementation.

  • Time Required: 1-2 working days, depending on the number of events implemented

Strictly speaking, progress on this step can be made at any time after step 1. Once the set of events has been agreed upon, formal documentation can begin. There are two pieces of documentation we recommend:

  1. Game project readme file

    This refers to a readme file included with the game source. The readme may contain other information, depending on the needs of the game project. In either case, this file should include semi-formal documentation of the events logged by the game. By “semi-formal,” we mean the documentation should at least include the names of all events and a listing of the specific data included with each event type, but details of format and any supporting text are left to the writer.

  2. GAME_ID.json file in opengamedata-core

    This refers to a specific json file for use within opengamedata-core. Among the uses of this file are automatic generation of a dataset readme file whenever data is exported via opengamedata-core. This is a formal documentation of events, in the sense there is a very specific format to use, with a prescribed set of elements to be listed for each type of event. Details are in the documentation of game schemas.

Both of these documents are important points of reference. In general, the readme file is useful for reviewing the state of logging and onboarding any new developers who may need to interact with the logging code, while the json file is useful as a specification of what should be implemented (where the documents differ, the json should be treated as the target, and the readme updated to reflect any fixes to the implementation).

Iteration

  • Description: Iterate on steps 1-4 (updating event definitions, implementing changes, testing) until satisfied with implementation.

  • Time Required: Per iteration, 30 minutes updating definitions, 2 hours implementing changes and updating documentation, 2 hours testing changes is typically a reasonable rate, number of iterations required varies widely.

Once all steps have an initial implementation, the process should be repeated iteratively to fix issues with the initial implementation. Further iterations are also recommended if and when the game changes significantly. “Significantly” is intentionally vague as there are no hard-and-fast rules for all games to determine when updates to logging are needed. A general guideline is that changes to game content typically do not require changes to logging, but changes to game structure do. For example, the addition or removal of game levels may not require changes to logging, but the introduction of a new mechanic or removal of a UI button almost always require updates to logging.

Note : It is strongly recommended to increase the log_version logged by the game whenever a new release includes changes to event logging.

Data Storage

Once you have implemented logging in your game, you’ll need a database to receive and store the logged events. In principle, any table-based database system may be used to record Open Game Data events; in practice, we have ready support for MySQL as a short-term container for new events, and for BigQuery for long-term archival of older events. Logging to another database system may require some additional development effort.

If you wish to utilize our existing logging infrastructure to capture your game events, please contact us to discuss integration with our instance of the OGD logging system.

If you prefer to create your own instance of logging infrastructure, there are two major steps to complete. These are:

  1. Set up logging to MySQL short-term database

  2. Set up automatic archival to BigQuery.

The details of this process are discussed in the next chapter

Data Transformations

Event Detectors

Feature Extractors

Monthly Outputs

OpenGameData Logger and Logging Clients

OpenGameData provides packages for logging events from game clients, and a PHP logger script to receive these events and place them into a database.

Client-Logger Communications

The logging clients communicate with the logger script via HTTP POST requests. These use request parameters for data that is constant within a gameplay session, such as versioning and identifier variables, and a base-64-encoded body for data that varies per-event. This allows the system to support packaging multiple events into a single request for games that either log events frequently or experience poor internet connections.

In particular, the following parameters are included in the header of each request:

  1. app_id: identifier for given app, should match the game’s name in the database

  2. app_version: the current version of the app

  3. app_branch: (optional) the branch of the app

  4. log_version: the current version of the app’s logging code/schema

  5. session_id: a unique ID for the current game session

  6. user_id: (optional) the player’s personal ID

  7. user_data: (optional) gives further data associated with player ID

Then the POST URL for a given request will have the following form:

https://hostname.com/path/to/log.php?app_id={1}&app_version={2}&app_branch{3}&log_version{4}&session_id={5}&user_id={6}&user_data={7}

The body of the request, as mentioned above, is base-64 encoded. The encoded data is an array, containing one or more JSON-style dictionaries, each containing data for a single event. The elements of these dictionaries are as follows:

  • client_time: client’s timestamp resolved to the second

  • client_offset: offset of client’s local time from UTC

  • event_name: the type of event logged

  • event_data: a JSON string containing all the logged information

  • game_state: a JSON string containing information about the state of the game when the event occurred

  • event_sequence_index: integer that increments with each log, showing the true order of the logs

These are decoded by the logger script, and recombined with the parameter items to form full events for storage into the configured database.

opengamedata-unity

The OGD client for the Unity game engine is developed and maintained at GitHub. Documentation on its use is included in the repository README. You can access it at the following URL: https://github.com/opengamedata/opengamedata-unity

If you wish to use the opengamedata-unity package, you can install it in your project from OpenUPM. The package page can be accessed at https://openupm.com/packages/com.fieldday.opengamedata-unity

opengamedata-js-log

The OGD client for general JavaScript projects is also maintained at GitHub, along with README documentation. You can access it at the following URL: https://github.com/opengamedata/opengamedata-js-log

To use the opengamedata-js-log package, you can install it in your project from NPM. The package can be accessed at https://www.npmjs.com/package/opengamedata-js-log

opengamedata-logger

Install Logging

STUB: This section is on the to-do list.

Install Python

As a first step, you should ensure Python is installed on your system. The quickest way to check is to open up a command prompt (often called a terminal) on your system, and typing:

  > python --version

This will output something like the following:

  Python 3.12.4

Currently, OpenGameData is meant to run on Python 3.8 and higher. If you have an older version of Python, but it is at least Python 3, you should think about updating to a newer Python version to avoid incompatibilities. If your Python is still on version 2, you should try running:

  > python3 --version

This should tell you if there is a separate installation of Python 3 on your system. If there is, then you should be good to go. You just need to be aware that you will need to use python3 instead of python if you want to run data exports with the provided main.py (as documented in the “Getting Started” page).

If there is no Python 3 installation, or no Python install at all (i.e. if the command(s) above resulted in an error message), you’ll need to perform a brand new installation of Python. Official Python downloads are available at the Python downloads page: https://www.python.org/downloads/