Telemetry for MovingBlocks

GSoC 2017 project: a telemetric-gathering system in a sandbox game Terasology

In this blog, I'll update the progress of the 2017 GSoC project Telemetry for MovingBlocks. If you are interested MovingBlocks/Terasology, you can learn more in forum or GitHub

You can get more information about this project by reading:

Project Overview

Bonding Period

I started Bonding Period by dockerizing the telemetry system.

At first I found a snowplow-mini docker in dockerHub, I linked the snowplow-mini docker with the logstash docker: telemetry-coupled. After talking with my mentor @qwc, we thought that that docker is not service oriented and could only be used for test.

So then I started a more un-couped telemetry system: telemetry. Since I'm not familar with docker and snowplow stacks, the setup took more time than I expected.

Phrase 1

Week 1 (30/May ~ 5/June)

GSoC started! There are some issues left in the telemetry system, so I fixed telemetry#5, telemetry#7, telemetry#8, telemetry#9 in the week.

Later in the week, I worked on documentation of the telemetry system: wiki.

Then I worked on the Terasology codebase. I imported the snowplow tracker lib to track the metrics. The snowplow lib had a version conflict with 'jackson-core' in CrashReport. Problems resolved by excluding the 'jackson-core' package in CrashReporter: CR#39. Then I created a first telemetry event which tracked some basic infos like os, video card, java version, etc. The PR corresponded is Terasology#2968. I tested it locally with telemetry system and mentors @skaldarnar @rzats helped me test. Here is what it looked like in server:

Week 2 (6/June ~ 12/June)

In week 2, following the work of week 1, I implemented the user's authorization.

The user's authorization is implemented by adding two config types in `Config.class` instance in game context: `TelemetryConfig` (Enable telemetry or not) and `LaunchPopupConfig` (whether the user wants to see the popup when launching the game).

Together with the user authorization, I implemented a `LaunchPopup` which will pop up during game launching, tell user what telemetry does and ask for user's permission. With the help of @Cervate and @skaldarnar, we added a buttom which will link to the `Metrics Menu` (will be implemented in furture). Here is update in PR: update week 2 is the update in PR. The popup looked as follow:

Week 3 (13/June ~ 19/June)

In week 3, I fixed two bugs in the docker server: telemetry#10 and telemetry#11

Quite a few work is done in the Terasology code:

A `TelemetrySubSystem` engine system initializes all the telemetry stuffs, and then injects the `emitter` and the `metrics` to game context so that the other classes can use them for telemetry.

Similar to the `Config.class`, the `Metrics.class` stores all the metric instance in the environment. It'll be used to show to the users what we tracker. In the future, it'll be used if we want to store some user's statistics in files. E.g. If we want to count the total number of boxes distroyed and we might need to store the number of boxes every time game shuts down.

The abstract `Metric.class` is a class to extend for every new `Metric` class. A new `Metric` class should also be annotitated by `@TelemetryCategory`. Every field being tracked should be marked as `@TelemetryField`.

The `TelemetryScreen` shows to users the field names and field values that we track. Users can enable and disable the telemetry via the check boxes in the menu. It finds these telemetry metrics automatically by the annotation `@TelemetryCategory`. So if a new metric extends the abstract `metric.class` and all the telemetry fields marked as `@TelemetryField`, their names and values will be showed automatically. Thanks @onitas for reviewing the PR.

Here is the update in PR: update week 3, and the `Metrics Menu` looked like this:

Week 4 (20/June ~ 26/June)

In the week 4, I worked on the error reporting. The error reporting system will enrich the error logs and send them to the server.

A new configuration in the logstash server to descode the json logs: telemetry#13

I used logstash-logback-encoder library. I implemented a `TelemetryLogstashAppender` based on the `LogstashTcpSocketAppender`. It has a `gameContext` field and it could be enabled or disabled via its methods.

Two json providers `SystemContextJsonProvider` and `ModulesJsonprovider` enriches the error logs with system information and module information. Also I added a new metric `ModulesMetric` to track the module information in game.

To turn on/off the error reporting, the user can go to the Metrics Menu and clicks the check box to enable/disable it. It's implemented via a listener on the check box and the filters in the logback appender. Thanks @Cervator for reviewing the code.

Here is the update in the PR: update week4. The error logs received during launching a game looked like this:
The informations of a log received:

Phrase 2

Phrase 3

Project Review