Your first data

What happens between starting your server and seeing it in the dashboard, how to make it fast on a test server, and what to check when nothing arrives.

From server to dashboard

The server starts. The SDK starts collecting in memory right away.
The first report is sent 3 to 6 minutes later (a random delay, so servers that restart together don't all report at once), then every hour, plus a last one when your plugin is disabled (unless the previous one was under 10 minutes ago), so a test server stopped early still reports.
Reports are merged before they're written. An aggregator combines the reports of every server and writes them to the database every 5 minutes. So a report can take up to about 5 minutes to appear.
The dashboard switches by itself. Until a first server is seen, your plugin's Overview shows a setup screen that checks again every 15 seconds and turns into your data the moment it arrives.

See it faster: firstDelay

On a test server, send the first report after a few seconds with a JVM flag (the value is in seconds):

java -Dpluginanalytics.firstDelay=10 -jar paper.jar

It applies to every plugin with the SDK on that server and only changes the first report; the next ones are still hourly. Don't use it on production servers.

See exactly what is sent: log-sent-data

The SDK creates plugins/PluginAnalytics/config.yml on first start. Set log-sent-data: true and restart, and every report is printed in the console:

[ArenaPlus] PluginAnalytics sent: {"v":1,"key":"pa_…","server":"6f1c…","players":3,
  "env":{"platform":"paper","mc":"1.21.8","software":"Paper","java":"21","os":"Linux","cores":8,
  "plugin":"1.4.0","sdk":"1.2.0","online_mode":true,"players_max":100},
  "props":{"config.auto-queue":"false","config.storage":"sqlite","dep.vault":"installed"},
  "events":[{"n":"command:arena.join","k":"p","c":4,"u":2},{"n":"game_started","k":"p","c":2,"u":2,"p":{"mode":"solo"}}],
  "firsts":[{"n":"$join","a":"p:3fa1…","t":1760000000}], …}

Failures are printed too: PluginAnalytics got HTTP 404 or PluginAnalytics could not send data: ….

No data? Check these, in order

A warning at startup. Search the console for PluginAnalytics is disabled:
- relocate com.gamepathics.pluginanalytics into your plugin's package: the SDK wasn't relocated, or you're running the plain jar instead of the shaded one. See relocation.
- invalid project key: the key is empty or doesn't start with pa_.
The key belongs to another project. A key that starts with pa_ but doesn't exist is refused by the server (HTTP 404 with log-sent-data) and the report is dropped. Copy the key again from the dashboard's setup screen or Settings → Install.
Analytics is turned off on that server. Check enabled in plugins/PluginAnalytics/config.yml; analytics.isEnabled() returns false in that case.
You didn't wait long enough. First report after 3 to 6 minutes (or your firstDelay), plus up to about 5 minutes until it's written.
You restarted the server several times within 10 minutes. Each server can report once every 10 minutes; reports in between are refused and that data waits for the next hourly report.
You restarted within 10 minutes. Each server may report at most once every 10 minutes. An earlier report is refused (HTTP 429) and its data is kept for the next attempt, an hour later. Wait 10 minutes between test runs that use firstDelay.
The server can't reach us. Reports are an HTTPS POST to pluginanalytics.dev on port 443, with a 5-second connect and 10-second read timeout. A firewall, an outbound proxy or a hosting provider that blocks outgoing connections stops them; log-sent-data then shows could not send data.
A leftover endpoint. If you ever started the server with -Dpluginanalytics.endpoint=…, reports go there instead.

The SDK never throws and never blocks, whatever goes wrong: your plugin keeps working, the data simply doesn't arrive.

Sections that stay empty

Some pages only fill when there's something to show: Events needs a command or a track call, Funnels needs players joining, Errors needs an exception, Listing needs your pages connected. Until then they explain what they show and the code they need.

NextAll features →