> ## Documentation Index
> Fetch the complete documentation index at: https://catalyst.leifiyo.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Use the bundled CatalystAnalytics plugin and the Catalyst analytics dashboard.

CatalystAnalytics is a Paper and Purpur plugin bundled with Catalyst. When enabled during server creation, Catalyst copies the plugin JAR into `plugins/`. The plugin writes a local analytics JSON file that Catalyst reads from the desktop app.

<Note>
  CatalystAnalytics is file-based in the current app integration. It does not require you to expose an HTTP API for Catalyst to read analytics.
</Note>

## Enable analytics

<Steps>
  <Step title="Create a Paper or Purpur server">
    Analytics installation is offered only for platforms that can run Bukkit-style plugins.
  </Step>

  <Step title="Turn on CatalystAnalytics">
    Leave the analytics toggle enabled during creation.
  </Step>

  <Step title="Start the server">
    The plugin creates `plugins/CatalystAnalytics/config.yml` and writes data under `plugins/CatalystAnalytics/data/`.
  </Step>

  <Step title="Open Analytics">
    Use the server detail analytics tab or the global Analytics page. Catalyst polls analytics while the app is open.
  </Step>
</Steps>

## Dashboard sections

<Tabs>
  <Tab title="Overview">
    Online players, peak online, unique players, average playtime, uptime, joins, new players, deaths, and a player-count timeline.
  </Tab>

  <Tab title="Performance">
    Current TPS, memory, MSPT, and history charts for TPS, memory usage, and milliseconds per tick.
  </Tab>

  <Tab title="Players">
    Client brand share, top players by playtime, client versions, and player identity data where available.
  </Tab>

  <Tab title="Activity">
    Most active hours, kills, chat messages, commands, returning players, and join distribution.
  </Tab>
</Tabs>

## Tracking settings

The analytics tab displays the plugin tracking configuration in read-only form. Edit the plugin config file when you need to change collection behavior:

```yaml theme={null}
plugins/CatalystAnalytics/config.yml
```

Common settings include player joins, playtime, client versions, client brands, operating system, TPS, RAM, FPS, and optional geolocation.

<Warning>
  Geolocation is disabled by default. If enabled, the plugin can call the configured geolocation provider for player IP metadata. Review your privacy obligations before turning it on.
</Warning>

## Commands

The plugin registers:

```text theme={null}
/analytics status
/analytics reload
```

The command permission is `catalystanalytics.admin` and defaults to server operators.