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)

importlink.star_dust.faststats.compat.FastStatsCompat;
// Your platform's telemetry provider:// You have to have your own way of getting this data.FastStatsCompat.Datadata = newFastStatsCompat.Data() {
@OverridepublicintplayerAmount() { return/* online player count */; }
@OverridepublicintonlineMode() { return/* 1 / 0 / -1 */; }
@OverridepublicStringserverSoftware() { return"NeoForge"; }
@OverridepublicStringserverVersion() { return"1.21.1"; }
@OverridepublicStringplatformTag() { return"neoforge"; }
};
FastStatsCompatfastStats = 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(newFastStatsCompat.Log() {
@Overridepublicvoidinfo(Stringmessage) { /* your logger.info */ }
@Overridepublicvoidwarn(Stringmessage, Throwableerror) { /* 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/config0.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.