AstralAnalytics Overview

AstralAnalytics is the event-collection pipeline for AstralRealms. Each game server and the proxy emit small typed events (player_join, command_execute, luckperms-promote, …) to a central master service that stores them in PostgreSQL. Metabase reads from the same database to power dashboards.

What it does

Collects events from Paper servers, the Velocity proxy, MageHic services, and any other plugin that calls the shared AnalyticsService interface.
Routes them over a single RabbitMQ exchange (analytics.events) using a compact binary packet.
Enriches events with geo data — payloads carrying an ip field get a country ISO code appended via ip-api.com.
Stores every event as a row in the events table with a JSONB payload.
Visualises through Metabase. A docker-compose.yml boots Postgres + Metabase with one command.

Modules

AstralAnalytics is a multi-module Maven project:

Module	Runs on	Purpose
`common`	every host	Shared packet (`LogEventPacket`), exchange name, `AnalyticsServiceImpl` that fires packets onto RabbitMQ.
`paper`	every Paper server	Bukkit plugin: registers the messaging service, the AnalyticsService, listeners for join/quit/commands, the `track-event` action, and the LuckPerms hook.
`velocity`	the Velocity proxy	Velocity plugin: collects richer first-touch data (client brand, mod info, settings, IP).
`master`	a dedicated MageHic node	Consumes the `analytics.events` exchange, runs GeoIP enrichment, writes to Postgres. Also exposes a local `MHAnalyticsService` for MageHic-side events that skip the RabbitMQ hop.

Architecture at a glance

Paper   ──► AnalyticsServiceImpl ──► LogEventPacket ──┐
Velocity ─► AnalyticsServiceImpl ──► LogEventPacket ──┤
MageHic  ─► MHAnalyticsService    ──► (direct)        │
                                                       ▼
                                              RabbitMQ "analytics.events"
                                                       │
                                                       ▼
                                              master ─ EventService
                                                       ├── parse payload
                                                       ├── if payload has "ip": GeoIP lookup → country
                                                       └── EventRepository.insert → Postgres
                                                                                       │
                                                                                       ▼
                                                                                   Metabase

Requirements

Dependency	Required	Notes
Paper 1.21+ / Velocity 3.4+	Per module	—
AstralCore	Yes	Messaging, plugin lifecycle, `AnalyticsService` interface live here.
RabbitMQ	Yes	Single exchange `analytics.events`, opcode `0x00`.
PostgreSQL 15+	Master only	`events` table with `JSONB payload`, indexed by created-at, type, player UUID, and a GIN index on the payload.
Metabase	Optional	Visualisation; bundled `docker-compose.yml` provisions it.
LuckPerms	Optional	When present on a Paper server, promote/demote events are auto-tracked.

What you'd typically use it for

Login funnel and player retention curves.
Cross-server playtime aggregation.
Country / locale / client-brand distribution.
Command usage telemetry.
Custom feature instrumentation through the track-event action or the AnalyticsService API in your own plugin.

Last modified: 25 July 2026