fastStats

Configuration

Advanced configuration options for FastStats Java SDK

Configuration

Configure FastStats to suit your needs with advanced options for self-hosted deployments, custom intervals, and more.

Basic Configuration

The minimal configuration requires only a token:

private final Metrics metrics = BukkitMetrics.factory()
    .token("YOUR_TOKEN")
    .create(this);

Self-Hosted Instance

If you're running your own FastStats instance, specify the custom URL:

import java.net.URI;

private final Metrics metrics = BukkitMetrics.factory()
    .url(URI.create("https://faststats.myserver.com/v1/collect"))
    .token("YOUR_TOKEN")
    .create(this);

Complete Configuration Example

Here's a fully configured metrics instance with all available options:

import dev.faststats.bukkit.BukkitMetrics;
import dev.faststats.core.Chart;
import dev.faststats.core.Metrics;

import java.net.URI;

public final class MyBukkitPlugin extends JavaPlugin {
    public static final ErrorTracker ERROR_TRACKER = ErrorTracker.contextAware();

    private final Metrics metrics = BukkitMetrics.factory()
        // Required: Your API token
        .token("YOUR_TOKEN")

        // Optional: Custom data collector URL (for self-hosted)
        .url(URI.create("https://faststats.myserver.com/v1/collect"))

        // Optional: Add custom charts
        .addChart(Chart.number("worlds", () -> getServer().getWorlds().size()))
        .addChart(Chart.number("plugins", () -> getServer().getPluginManager().getPlugins().size()))
        .addChart(Chart.string("test_string", () -> "some test value"))
        .addChart(Chart.number("answer_to_life", () -> 42))
        .addChart(Chart.stringArray("animals", () -> new String[]{"dogs", "cats"}))

        // Optional: Attach an error tracker
        // This must be enabled in the project settings
        .errorTracker(ERROR_TRACKER)

        // Optional: Project specific debug logging, useful during development
        .debug(true)

        // Create the metrics instance
        .create(this);
}

Error Tracking

FastStats can automatically track errors in your project.

Error tracking must be enabled in the project settings. Otherwise, all reported errors will be ignored.

The error tracker does not replace proper error handling. It should only be used as a way to report errors for monitoring purposes.

Context-Aware Error Tracker

The context-aware error tracker automatically tracks errors in the same class loader:

import dev.faststats.core.ErrorTracker;

public final class MyBukkitPlugin extends JavaPlugin {
    // Context-aware error tracker, automatically tracks errors in the same class loader
    public static final ErrorTracker ERROR_TRACKER = ErrorTracker.contextAware();

    private final Metrics metrics = BukkitMetrics.factory()
        .errorTracker(ERROR_TRACKER)
        .token("YOUR_TOKEN")
        .create(this);

    public void doSomethingWrong() {
        new Thread(() -> {
            // This exception will automatically be tracked
            throw new RuntimeException("Something went wrong!");
        }).start();
    }
}

The automatic tracking only covers errors that would otherwise be swallowed by the JVM, manual tracking should be used in addition to passive tracking.

Context-Unaware Error Tracker

The context-unaware error tracker does not automatically track any errors:

import dev.faststats.core.ErrorTracker;

public final class MyBukkitPlugin extends JavaPlugin {
    // Context-unaware error tracker, does not automatically track errors
    public static final ErrorTracker CONTEXT_UNAWARE_ERROR_TRACKER = ErrorTracker.contextUnaware();

    private final Metrics metrics = BukkitMetrics.factory()
        .errorTracker(CONTEXT_UNAWARE_ERROR_TRACKER)
        .token("YOUR_TOKEN")
        .create(this);

    public void doSomethingWrong() {
        try {
            // Do something that might throw an error
            throw new RuntimeException("Something went wrong!");
        } catch (Exception e) {
            CONTEXT_UNAWARE_ERROR_TRACKER.trackError(e);
        }
    }
}

Manual Error Tracking

Both context-aware and context-unaware error trackers support manual error tracking using trackError(String) or trackError(Throwable).
This allows you to report errors in specific places where more insights might be useful.

public void doSomethingRisky() {
    try {
        // Do something that might throw an error
        riskyOperation();
    } catch (Exception e) {
        // Proper error handling first
        getLogger().severe("Operation failed: " + e.getMessage());

        // Then track the error for monitoring
        ERROR_TRACKER.trackError(e);
    }
}

public void validateConfiguration() {
    if (!isConfigValid()) {
        // Track custom error messages
        ERROR_TRACKER.trackError("Invalid configuration detected");
    }
}

Platform-Specific Configuration

All platforms follow the same API design. Below is a reference table for each platform:

PlatformMetrics ClassExample
Bukkit/Spigot/Paperdev.faststats.bukkit.BukkitMetricsExamplePlugin.java
BungeeCorddev.faststats.bungee.BungeeMetricsExamplePlugin.java
Fabricdev.faststats.fabric.FabricMetricsExampleMod.java
Hytaledev.faststats.hytale.HytaleMetricsExamplePlugin.java
Minestomdev.faststats.minestom.MinestomMetrics
Nukkitdev.faststats.nukkit.NukkitMetrics
Spongedev.faststats.sponge.SpongeMetricsExamplePlugin.java
Velocitydev.faststats.velocity.VelocityMetricsExamplePlugin.java

Best Practices

  • Keep chart suppliers lightweight
  • Cache expensive calculations and values that never change
  • Chart suppliers must be thread-safe and pure
  • Don't rely on the error tracker as your only error handling solution

On this page