BKCommonLib/Metrics

This page is outdated

It was written for an older version of BKCommonLib and may not apply to the most recent version. BKCommonLib now uses bStats metrics. (16 June 2023)

Last update: 10 June 2021

Introduction

Metrics is a service provided by Hidendra to keep track of plugin statistics. It allows plugin developers to see who uses their plugin the most, and to keep track of certain features. This makes it easier to decide on new features and to see what parts of the plugin really matter to most people. The data is sent anonymously, that is, no server IP/player names/personal information is sent to the database.

You do not want to participate in this as a server? Aw...oh well, you can opt-out on Metrics globally in the metrics configuration file:

plugins\PluginMetrics\config.yml < change opt-out: to true.

Metrics in BKCommonLib

A Metrics implementation, almost entirely similar as the one provided by mcstats, is included in BKCommonLib. It provides an easy API layer to set up the data you wish to send to the server. Instead of scheduling a task to update it every other time, or having synchronization issues, the Metrics implementation in BKCommonLib works slightly differently.

Creating Metrics for your plugin

How to obtain a Metrics class instance to use it in your plugin.

PluginBase

If you use PluginBase for your plugin, all you have to do is add 'metrics: true' to the plugin.yml of the plugin. After that you can obtain the Metrics instance using the provided getMetrics() method. Before using it, check that metrics is available (and enabled) using the hasMetrics() method, otherwise errors will occur.

Manually

To manually create a new Metrics instance, use the following code:

Metrics metrics = Metrics.initialize(this);
if (metrics != null) {
    // Add your graphs here
}

You can also create a new Metrics instance using the provided constructor, and handle the errors yourself. In that case, make sure you also call start() once all graphs are added. The initialize method does that for you.

Adding graphs

Graphs in this implementation work slightly different than the ones found elsewhere. In BKCommonLib, Metrics graphs contain an onUpdate method in which the values can be set. It also does not contain a 'Plotter' class, instead it uses a map of values. it is up to the plugin to fill or update the data in the graph. The onUpdate method is called on the main thread (synchronized), so it is thread-safe to access Bukkit or plugin resources.

To add a graph, use Metrics.addGraph.

Changing plotter values in graphs

A plotter value is basically a single value for part of a graph displayed on mcstats.org. For example, if you have a Commands graph, you can add plotter values for all commands the plugin provides, mapped to the amount of times it was performed.

Plotter values have to be numeric (int, double, float, etc.), non-numeric text is not possible simply because it can't be displayed in a graph.

There are several methods to change 'plotter' values:

clearPlotters - removes all set plotters
togglePlotter - Adds a plotter with value '1' if enabled, or removes the plotter if disabled
addPlotter - Adds a plotter mapping the value to a key

Example graph implementation (found in enable() of a PluginBase):

// Total server memory
getMetrics().addGraph(new Graph("Total server memory") {
    @Override
    public void onUpdate(Plugin plugin) {
        clearPlotters();
        // Get server total memory in MB (>> 20 = / (1024 * 1024))
        final long mem = Runtime.getRuntime().totalMemory() >> 20;
        final String key;
        if (mem <= 512) {
            key = "0-512 MB";
        } else if (mem <= 1024) {
            key = "512-1024 MB";
        } else if (mem <= 2048) {
            key = "1024-2048 MB";
        } else if (mem <= 4096) {
            key = "2048-4096 MB";
        } else if (mem <= 8192) {
            key = "4096-8192 MB";
        } else if (mem <= 16384) {
            key = "8-16 GB";
        } else {
            key = "16+ GB";
        }
        togglePlotter(key, true);
    }
});

This produces a graph as follows (pie chart): Total server memory - Pie chart

Default graph implementations

BKCommonLib also includes some 'common' Graph implementations. These are:

MyDependingPluginsGraph - shows the plugins depending on your plugin
SoftDependenciesGraph - shows the plugins enabled that your plugin has a soft dependency on

Important notes

onUpdate is not called if the server opted out, also if the server opted out after your metrics instance was started.
getMetrics() throws an exception if no metrics is available - use hasMetrics() before using it
To use metrics in PluginBase, add the metrics: true to the plugin.yml. By default metrics is disabled.
Only use numeric plotter values