While default server metrics (TPS, player count, connections) provide a solid baseline for server operations, they don’t capture the unique gameplay features that make your Minecraft server stand out. If you have custom economy plugins, unique questlines, faction territory captures, or custom mini-games, you need specialized telemetry.

Fortunately, ShardAnalytics allows you to send Custom Events directly from your Java plugins and server code. In this guide, we will cover how custom event ingestion works, show you examples of what events you should track, and explain how the system infers and indexes your custom data so it is queryable in dashboards and funnels.

1. Beyond Default Analytics: Why Custom Events Matter

Default analytics are great for general monitoring, but they are blind to your custom business logic. For example:

You can see that player count drops at 8:00 PM, but you can’t see if that drop was caused by players getting frustrated by a specific custom boss fight.
You know your shop is bringing in virtual currency, but you don’t know which specific shop category or item is the most popular.

By sending custom events to ShardAnalytics, you bridge the gap between technical server health and game design analytics. This enables you to build custom dashboards, map player progression funnels, and make decisions based on empirical gameplay data.

2. What Is a Custom Event?

A custom event is a data packet sent to ShardAnalytics when a specific action occurs in-game. Each event consists of:

Event Name: A unique identifier (e.g. quest_completed, crate_opened).
Telemetry Context: Automatically attached fields like player_uuid, server_id, world, and timestamp.
Event Payload: A flat JSON object containing custom properties (e.g., the quest ID, item rarity, or purchase cost).

To ensure high-performance querying, event payloads should be kept flat. Avoid nested JSON structures or complex arrays when sending custom events.

3. High-Value Custom Events to Track

Depending on your server’s game mode, here are the most valuable events you should instrument in your plugins:

Onboarding & Progression

tutorial_step_completed: Track fields like step_id and time_taken to find where new players get stuck or log off during onboarding.
quest_completed: Track quest_id, reward_type, and difficulty to map player progression speed.

Server Economy & Monetization

crate_opened: Track crate_type, key_source (store purchase vs. in-game reward), and reward_id to audit your server’s drop rates.
shop_purchase: Track item_id, category, price, and currency_type to see what virtual goods drive your economy.

Gameplay & Competition

boss_killed: Track boss_type, party_size, and time_to_kill to verify combat balance.
region_capture: On Factions or Towny servers, track region_id, capturing_faction, and duration to monitor active gameplay.
island_upgrade: On Skyblock servers, track island_level, upgrade_type, and cost.
minigame_round_finished: Track game_mode, map_name, and winner_uuid.

4. The Data Catalog: Automatic Event Discovery

When your custom plugin sends a new event type to the ShardAnalytics ingestion endpoint, you do not need to pre-register the schema.

[ Custom Plugin Event ] ──> [ Ingestion Endpoint ] ──> [ Data Catalog Auto-Discovery ]
                                                                   │
                                                                   ▼
                                                       [ Schema Preview & Inference ]
                                                                   │
                                                                   ▼
                                                       [ Queryable Dimensions ]

ShardAnalytics automatically discovers the new event name and starts indexing the incoming stream. It records the first time each event was seen and samples incoming payloads, so new metrics become available without a schema change on your side.

5. Schema Preview, Inference, and Curation

Once a new event type is discovered, ShardAnalytics parses sample payloads and infers:

Data Types: The system automatically identifies properties as strings, numbers, booleans, or arrays.
Cardinality: It evaluates how many unique values a property has. For example, a rarity field (common, rare, legendary) has low cardinality, while a quest_id might have medium cardinality, and a coordinate has high cardinality.

Fields are then curated before they are exposed for charting: human-readable names, units of measurement, and sensitive-field markings.

6. From Raw Fields to Queryable Data

Curation does not just make your schema look neat; it turns your custom properties into fields you can chart.

Dimensions: Categorical fields (like item_id, world_name, or rarity) are used to group, filter, and segment your data.
Measures: Numeric fields (like purchase_price or seconds_to_complete) are used to calculate aggregates like sums, averages, minimums, maximums, and percentiles.

Once available, these fields can be used in the custom dashboard widget builder and as funnel steps. You can drag a new quest_id dimension onto a chart to see quest popularity, or sum purchase_price to track economic velocity.

7. Common Instrumenting Mistakes to Avoid

When setting up custom event tracking, avoid these pitfalls:

Tracking Raw Coordinates in Event Names: Do not name your events dynamically (e.g. block_break_102_64_205). Keep event names static (e.g. block_broken) and put coordinate context inside the payload.
Inconsistent Field Naming: Ensure all plugins use the same casing for properties (e.g., don’t use questId in one plugin and quest_id in another). Consistent names make cross-event analysis simple.
Missing Context: Always include key metadata like the world, server instance, or player state. A crate_opened event is much more valuable if it includes whether the player was in the Lobby or a Survival world.

8. Start Instrumenting Your Server Today

Take control of your server’s gameplay data. ShardAnalytics provides a simple Java SDK to send custom telemetry events and build custom dashboards in minutes.

Automatic Schema Inference: Send payloads and watch ShardAnalytics parse and index data types.
Queryable Fields: Turn raw JSON fields into dimensions and measures you can chart instantly.
Developer-First SDK: Native support for Paper servers.

Start Tracking Custom Events with ShardAnalytics.

How to Track Custom Minecraft Plugin Events with Analytics