Access Screeps Console, Performance, and Statistics Data via Kibana and ElasticSearch
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
js
provisioning
screeps_etl
.gitignore
.screeps_settings.dist.yaml
Dockerfile
LICENSE
README.md
Vagrantfile
docker-compose.yml
makefile
requirements.txt

README.md

Screeps Stats

Screeps Stats Collection is a service that ingests statistics and console data from the Screeps game and saves them in ElasticSearch. This service can be setup on an existing server or can be provisioned using the supplied vagrant file.

Features

  • Full console output is saved in a quickly searchable database.
  • Performance data- such as CPU and Memory usage- is saved and charted over time.
  • Personal market history is pulled from the API without any game code changes.
  • Provided "screepsstats.js" module can be added to game code in order to collect more statistics.
  • Custom statistics can be easily added using screepsstats module.
  • Statistics are buffered, reducing needed API calls and ensuring data isn't lost for minor issues (server restarts, internet issues).
  • Utilizes segments to store data, preventing it from being continually parsed when Memory is loaded.
  • Falls back to Memory when segments are unavailable.

Quick Start with Vagrant

You can run this immediately on your own computer using vagrant.

  1. Install vagrant.
  2. Open terminal to this project.
  3. Copy the configuration file (cp .screeps_settings.dist.yaml .screeps_settings.yaml) and fill it out.
  4. Run vagrant up and wait.
  5. Open your browser to http://172.16.0.2/.

Self Hosting (Ubuntu)

Install

Running the Screps Stats Collector service on a linux server is a little more complicated but far more robust. This is the recommended setup for long term installations.

ElasticSearch can be installed however you wish, but a provisioning script for ElasticSearch and Kibana is provided.

  1. Download - wget $(curl -L -s https://api.github.com/repos/screepers/screeps-stats/releases/latest | grep tarball_url | head -n 1 | cut -d '"' -f 4) -O screepsstats.tgz
  2. Unpack - mkdir screepsstats; tar zxvf screepsstats.tgz -C ./screepsstats --strip 1.
  3. Move - sudo mv screepsstats /opt/screepsstats.
  4. Change Directory - cd /opt/screepsstats
  5. OPTIONAL: Provision ElasticSearch and Kibana sudo ./provisioning/provision.sh.
  6. Configure - cp .screeps_settings.dist.yaml ~screepsstats/.screeps_settings.yaml and then edit.
  7. Build - make
  8. Install - sudo make install

Manage Service

If you are using an operating system with SystemD this service will be installed when you run make install. From there it can be managed with the systemctl tool (systemctl start screepsstats.service).

For servers without systemd the screepsstatsctl service manager has been provided. It takes the commands start, stop, and reset. For security reasons this should be run as root (it will downgrade itself to it's own user).

Enhanced Screeps Stats Collection

By default this service will ingest the console and performance data (cpu and memory size).

With the addition of a client side (in game, javascript) module additional statistics, including custom stats, can be added.

var ScreepsStats = require('screepsstats')
global.Stats = new ScreepsStats()

module.exports.loop = function () {

  // Do code stuff!

  // Run Stats Last.
  Stats.runBuiltinStats()

  // Optional: Move stats from this tick out of memory
  // and into one of the passed segments.
  Stats.manageSegments([50,51,52,53,54])
}

When the stats collection service picks stats up from the server it will erase them, so as long as the service is running only a few ticks worth of data will be stored. If the stats service fails. Stats will be collected for up to 20 ticks, at which point the oldest data will be removed.

It's important for the ScreepsStats class to get assigned to global.Stats, as the stats collection server will use this class to delete ticks that it has finished processing.

Enhanced Console Attributes

This module uses the console attribute system defined in the Screeps Console project. By adding additional tags like severity, group, and tick, developers can sort and filter their console data to drill down into issue.

You can start with the ExampleLogger in that project as a replacement for console.log to immediately take advantage of this.