BKCommonLib/Metrics - Revision history

RyanDo at 09:47, 12 October 2025

2025-10-12T09:47:40Z

← Older revision		Revision as of 09:47, 12 October 2025
Line 1:		Line 1:
	~~[[BKCommonLib\|« Go back]]~~
	{{Update\|BKCommonLib\|10 June 2021\|reason=BKCommonLib now uses bStats metrics.\|date=16 June 2023}}		{{Update\|BKCommonLib\|10 June 2021\|reason=BKCommonLib now uses bStats metrics.\|date=16 June 2023}}

	==Introduction==		==Introduction==
	[https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f 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.		[https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f 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.

Bbayu: Mark page as outdated

2023-09-26T00:43:11Z

Mark page as outdated

← Older revision		Revision as of 00:43, 26 September 2023
Line 1:		Line 1:
	[[BKCommonLib\|« Go back]]		[[BKCommonLib\|« Go back]]
			{{Update\|BKCommonLib\|10 June 2021\|reason=BKCommonLib now uses bStats metrics.\|date=16 June 2023}}

	==Introduction==		==Introduction==

RyanDo at 18:51, 9 June 2021

2021-06-09T18:51:27Z

← Older revision		Revision as of 18:51, 9 June 2021
Line 15:		Line 15:


	=PluginBase=		===PluginBase===
	If you use [[BKCommonLib/PluginBase\|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.		If you use [[BKCommonLib/PluginBase\|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=		===Manually===
	To manually create a new Metrics instance, use the following code:		To manually create a new Metrics instance, use the following code:

RyanDo at 18:50, 9 June 2021

2021-06-09T18:50:40Z

← Older revision		Revision as of 18:50, 9 June 2021
Line 1:		Line 1:
			[[BKCommonLib\|« Go back]]

	==Introduction==		==Introduction==
	[https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f 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.		[https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f 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.

RyanDo: Created page with "==Introduction== [https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f Metrics] is a service provided by '''Hidendra''' to keep track of plugin statis..."

2021-06-09T18:50:20Z

Created page with "==Introduction== [https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f Metrics] is a service provided by '''Hidendra''' to keep track of plugin statis..."

New page

==Introduction==
[https://dev.bukkit.org/linkout?remoteUrl=https%253a%252f%252fmcstats.org%252f 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:

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

==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 [https://github.com/bergerkiller/BKCommonLib/blob/master/src/main/java/com/bergerkiller/bukkit/common/metrics/Metrics.java Metrics] class instance to use it in your plugin.

=PluginBase=
If you use [[BKCommonLib/PluginBase|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:

<pre>Metrics metrics = Metrics.initialize(this);
if (metrics != null) {
// Add your graphs here
}</pre>
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 [https://mcstats.org 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):
<pre>// 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);
}
});</pre>
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:
* [https://github.com/bergerkiller/BKCommonLib/blob/master/src/main/java/com/bergerkiller/bukkit/common/metrics/MyDependingPluginsGraph.java MyDependingPluginsGraph] - shows the plugins depending on your plugin
* [https://github.com/bergerkiller/BKCommonLib/blob/master/src/main/java/com/bergerkiller/bukkit/common/metrics/SoftDependenciesGraph.java 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