Andreas Troelsen
26cb8474db
Introduces the bStats metrics library to the plugin. This first commit contains just a single custom chart, the `store_type`, which will help figure out which stores to focus on for performance optimization and such.
204 lines
8.2 KiB
Markdown
204 lines
8.2 KiB
Markdown
# MobArenaStats [](https://github.com/garbagemule/MobArenaStats/actions/workflows/build.yml)
|
|
|
|
MobArenaStats is a _plugin extension_ for [MobArena](https://github.com/garbagemule/MobArena).
|
|
The extension collects stats from MobArena sessions into persistent storage such as MySQL, MariaDB, and SQLite databases.
|
|
It hooks into MobArena's command handler to provide commands for querying and managing the stats.
|
|
|
|
|
|
## Getting Started
|
|
|
|
Download a copy of the latest MobArenaStats build and place it in your server's `plugins` folder.
|
|
You can grab a build from the _Artifacts_ section of the latest run of the [build workflow](https://github.com/garbagemule/MobArenaStats/actions/workflows/build.yml) in GitHub Actions, or you can join the MobArena Discord server and grab one from the `#test-builds` channel.
|
|
|
|
Start your server and let the plugin load.
|
|
It will generate a default `config.yml` file and set up a default SQLite data store.
|
|
If this is the store you want to use, then there is nothing left to do - fire up a MobArena session and start collecting stats!
|
|
|
|
If you wish to set up a different data store, please refer to the [Configuration](#configuration) section below.
|
|
|
|
|
|
## Configuration
|
|
|
|
When the plugin first loads, it will generate a `config.yml` file in the plugin folder.
|
|
This file consists of a single section, the `store` section, which is used to set up the data store.
|
|
|
|
MobArenaStats _natively_ supports a couple of different data stores:
|
|
|
|
- SQLite
|
|
- MySQL
|
|
- MariaDB
|
|
- CSV files
|
|
|
|
The following sections describe the store-specific config properties.
|
|
|
|
|
|
### SQLite
|
|
|
|
[SQLite](https://www.sqlite.org/) is a database engine embedded in a library.
|
|
It uses a single file on disk to store all of its data.
|
|
|
|
By default, MobArenaStats uses the filename `stats.db` inside its own plugin folder, but this can be altered with the `filename` property, which is the _relative path_ from the plugin folder.
|
|
|
|
#### Example
|
|
An example SQLite database configuration that stores its data in a file called `mobarena_stats.db` in the server root folder (`../..` is the server root relative to the plugin folder).
|
|
|
|
```yml
|
|
store:
|
|
type: sqlite
|
|
filename: ../../mobarena_stats.db
|
|
```
|
|
|
|
|
|
### MySQL
|
|
|
|
[MySQL](https://www.mysql.com/) is one of the most well-known relational databases and a common sight in database offerings from various providers.
|
|
|
|
MobArenaStats requires a `host`, a `port`, a `database` name, and credentials in the form of a `username` and a `password` to connect to a MySQL database.
|
|
By default, the plugin tries to connect to `localhost` on port 3306 with a database called `mobarena_stats`, but these can all be altered.
|
|
There are no defaults for the `username` and `password`.
|
|
|
|
**Note:** The `database` must be created manually!
|
|
|
|
MobArenaStats is tested with MySQL 5.7.
|
|
|
|
#### Example
|
|
An example MySQL database configuration that connects to a database called `mastats` on localhost port 1337 with username `bob` and password `saget`.
|
|
|
|
```yml
|
|
store:
|
|
type: mysql
|
|
host: localhost
|
|
port: 1337
|
|
database: mastats
|
|
username: bob
|
|
password: saget
|
|
```
|
|
|
|
|
|
### MariaDB
|
|
|
|
[MariaDB](https://mariadb.org/) is a fork of MySQL by the original MySQL authors that aims to be free and open-source forever.
|
|
|
|
MobArenaStats supports MariaDB via the [drop-in replacement](https://en.wikipedia.org/wiki/Drop-in_replacement) compatibility with MySQL.
|
|
This means that the configuration of MariaDB databases is _exactly_ the same as for [MySQL](#mysql) databases (including setting `type: mysql`).
|
|
|
|
MobArenaStats is tested with MariaDB 10.4.
|
|
|
|
|
|
### CSV files
|
|
|
|
MobArenaStats can persist session stats on the file system in the CSV format.
|
|
It stores two files, `sessions.csv` and `players.csv`, with overall and player-specific session data, respectively.
|
|
By default, the plugin stores the data files in a local `data` subfolder in the plugin folder, and it uses semicolons (`;`) to separate values.
|
|
|
|
**Note:** CSV stores _do not_ support data queries!
|
|
|
|
#### Example
|
|
An example of a CSV configuration that stores the data files in a `mobarena_stats` folder in the server root (`../..` is the server root relative to the plugin folder) and uses commas (`,`) to separate values.
|
|
|
|
```yml
|
|
store:
|
|
type: csv
|
|
folder: ../../mobarena_stats
|
|
separator: ,
|
|
```
|
|
|
|
|
|
## Commands
|
|
|
|
MobArenaStats introduces new subcommands to the `/ma` base command in MobArena.
|
|
These include player commands for querying the data store, and server admin commands for exporting from and importing into data stores.
|
|
|
|
The following sections describe each command (and the permission required to run it) and its arguments, if any.
|
|
|
|
|
|
### Queries
|
|
|
|
Query commands dip into the data store to fetch global stats, arena-specific stats, or player-specific stats.
|
|
|
|
#### Global stats
|
|
|
|
- `/ma global-stats`
|
|
- `mobarenastats.command.global-stats`
|
|
|
|
Get a summary of session stats across all arenas and all players:
|
|
|
|
- Total sessions: total number of unique arena sessions
|
|
- Total duration: sum of all session durations
|
|
- Total kills: sum of all kills made in arena sessions
|
|
- Total waves: total number of waves spawned in arena sessions
|
|
|
|
#### Arena stats
|
|
|
|
- `/ma arena-stats <arena-slug>`
|
|
- `mobarenastats.command.arena-stats`
|
|
|
|
Get a summary of stats across all sessions in the arena denoted by the given `<arena-slug>`:
|
|
|
|
- Highest wave: the highest wave number spawned in the arena
|
|
- Longest duration: the duration of the longest session in the arena
|
|
- Most kills: the highest number of total kills in a session in the arena
|
|
- Total sessions: total number of unique sessions in the arena
|
|
- Total duration: sum of durations for all sessions in the arena
|
|
- Total kills: sum of all kills made in the arena
|
|
- Total waves: total number of waves spawned in the arena
|
|
|
|
#### Player stats
|
|
|
|
- `/ma player-stats <player-name>`
|
|
- `mobarenastats.command.player-stats`
|
|
|
|
Get a summary of session stats for the player with the given `<player-name>`:
|
|
|
|
- Total sessions: total number of unique arena sessions for the player
|
|
- Total duration: sum of all session durations for the player
|
|
- Total kills: sum of all kills made in arena sessions by the player
|
|
- Total waves: total number of waves spawned in arena sessions with the player
|
|
|
|
|
|
### Import & Export
|
|
|
|
All data stores can export their stats, and all data stores can import stats exported from other data stores.
|
|
The plugin always exports data as SQLite database files, and it can only import files that follow the same format and naming convention.
|
|
|
|
#### Export
|
|
|
|
- `/ma export-stats`
|
|
- `mobarenastats.command.export-stats`
|
|
|
|
Export the stats in the current data store to an SQLite database file.
|
|
All data exports follow the naming convention `stats.export-<timestamp>.db`, where `<timestamp>` is a UNIX timestamp of the time that the export was started.
|
|
|
|
**Note:** Exporting stats is a slow operation and will take time proportional to the amount of data in the current store.
|
|
The operation runs _off_ the main thread, so it should not impact performance.
|
|
|
|
#### Import
|
|
|
|
- `/ma import-stats <filename>`
|
|
- `mobarenastats.command.import-stats`
|
|
|
|
Import the stats from the data export denoted by the given `<filename>`.
|
|
The file must be an SQLite database created with the [export command](#export).
|
|
|
|
**Note:** It is not recommended to import stats into a non-empty data store.
|
|
Always import into an empty store unless you know what you are doing.
|
|
|
|
**Note:** Importing stats is a very slow operation and will take time proportional to the amount of data in the export file.
|
|
The operation runs _off_ the main thread, so it should not impact performance.
|
|
|
|
|
|
## Getting Help
|
|
|
|
If you run into problems or need help with something, feel free to hop on the MobArena Discord server: [Instant Invite](https://discord.gg/5tnwQvC)
|
|
|
|
|
|
## Metrics
|
|
|
|
MobArenaStats collects anonymous server metrics through [bStats](https://bstats.org/).
|
|
The metrics include generic information like Minecraft version, as well as plugin-specific information like plugin version and store type.
|
|
All collected metrics are publicly available [here](https://bstats.org/plugin/bukkit/MobArenaStats/11932).
|
|
|
|
Please note that the stats collected by the plugin itself never leave the server, and they are thus _not_ a part of the metrics collection.
|
|
|
|
To opt out of metrics collection, edit the `plugins/bStats/config.yml` file.
|