FastStats-Compat

A self-contained FastStats (faststats.dev) telemetry bridge for platforms the official faststats-java SDK does not cover — or where its jar-in-jar Fabric / NeoForge modules don't fit.

It drives the SDK's platform-agnostic core + config modules directly and exposes a small builder API. Any plugin / mod / server can use it to report metrics to a FastStats project without depending on the platform-specific modules.

faststats.dev agreed to this usage;

the SDK docs: https://docs.faststats.dev/java.

---

How it works

• link.star_dust.faststats.compat.FastStatsCompat extends SimpleContext — the same technique the official platform modules use, minus the platform API deps.
• Reports server_type, platform_version, online_mode, player_count, plugin_version (with an optional +<platformTag> suffix) plus the SDK's own java_* / os_* / core_count data.
• Submits to https://metrics.faststats.dev/v1/collect (JDK java.net.http, gzip, Authorization: Bearer <token>); first submission after 30 s, then every 30 min.
• First run prints the opt-out notice and defers submission to the next restart (FastStats compliance — users must be able to opt out).

Artifacts

Task	Output	Contents
gradlew jar	build/libs/faststats-compat-<v>.jar	Library classes only (FastStats core/config are api deps)
gradlew shadowJar	build/libs/faststats-compat-<v>-all.jar	Self-contained: SDK + Gson relocated under link.star_dust.faststats.shaded.* — drop it into any server, no split-package issues

The -all jar is the easiest to use: no extra dependencies, no relocation worries (e.g. no JPMS Modules ... export package ... errors on Arclight / NeoForge).

Usage

1. Add the dependency

Self-contained (-all jar) — just drop faststats-compat-<v>-all.jar on the classpath (or use it as a file dependency):

dependencies {
    implementation files('libs/faststats-compat-1.0.0-all.jar')
}

Plain jar — the SDK core/config are api deps; if you use a Gradle dependency you also need the FastStats repo:

repositories {
    mavenCentral()
    maven { url = 'https://repo.faststats.dev/releases' }
	maven { url = 'https://jitpack.io' }
}
dependencies {
    implementation 'com.github.At87668:faststats-compat:1.0.0'
	implementation 'dev.faststats.metrics:core:0.29.4'
    implementation 'dev.faststats.metrics:config:0.29.4'
}

If you consume the plain jar through a build tool, remember to relocate dev.faststats, com.google.gson and com.google.errorprone in your final artifact (the -all jar already does this for you).

2. Create the bridge (startup)

import link.star_dust.faststats.compat.FastStatsCompat;

// Your platform's telemetry provider:
// You have to have your own way of getting this data.
FastStatsCompat.Data data = new FastStatsCompat.Data() {
    @Override public int playerAmount() { return /* online player count */; }
    @Override public int onlineMode() { return /* 1 / 0 / -1 */; }
    @Override public String serverSoftware() { return "NeoForge"; }
    @Override public String serverVersion() { return "1.21.1"; }
    @Override public String platformTag() { return "neoforge"; }
};

FastStatsCompat fastStats = FastStatsCompat.builder("YOUR_FASTSTATS_PROJECT_TOKEN")
    .platform("neoforge")          // e.g. "fabric" / "forge" / "neoforge"
    .projectName("your-plugin")    // the project_name reported to FastStats
    .pluginVersion("2.1.0.0")
    .dataFolder(dataFolder)        // Path (or File) that will hold faststats/config.properties
    .logger(new FastStatsCompat.Log() {
        @Override public void info(String message) { /* your logger.info */ }
        @Override public void warn(String message, Throwable error) { /* your logger.warn */ }
    })
    .data(data)
    .build();

fastStats.ready();  // starts submission

3. Shut down (on server stop)

fastStats.shutdown();

Wrap construction in try/catch — a failure is non-fatal and should never abort server startup.

Token

The token is a 32-character lowercase alphanumeric string (matches dev.faststats.Token.PATTERN). Create a project on faststats.dev and use its token. The bridge will be rejected with 401 if the token is invalid.

Config

<dataFolder>/faststats/config.properties is created / upgraded automatically by the SDK (serverId, enabled, submitMetrics, submitErrors, submitAdditionalMetrics, debug, configVersion). System properties that can help debugging: faststats.debug=true, faststats.initial-delay=0, faststats.metrics-server=....

Notes / gotchas

• SimpleContext, SimpleMetrics and SimpleConfig are marked @ApiStatus.Internal by FastStats — the official platform modules build on them the same way, so this is an accepted, version-pinned dependency (pinned to core/config 0.29.4 in build.gradle).
• The -all jar relocates dev.faststats → link.star_dust.faststats.shaded.sdk, com.google.gson → link.star_dust.faststats.shaded.gson and com.google.errorprone → link.star_dust.faststats.shaded.errorprone, so it never clashes with another bundled copy.
• Keep metric suppliers lightweight, thread-safe and side-effect free; return null/negative to skip a field for a submission.

License

MIT — © At87668 (Author87668). This bridge was originally extracted from MinerTrack and has been relicensed to MIT by the copyright holder.