Analytics and the audit trail

Every trade event recorded, queryable in chat, a menu, or a CSV export.

Every trade outcome is written to the database. Nothing is sampled and nothing expires on its own.

The event types

Event	When
`TRADE_STARTED`	Requirements taken, slot filled
`TRADE_COMPLETED`	Finished and rewarded
`TRADE_BURNED`	Failed its success roll
`TRADE_FAILED`	Could not complete — a missing hook, an invalid reward
`TRADE_CANCELLED`	The player cancelled it
`ADMIN_CANCELLED`	Staff cancelled it
`ADMIN_FORCE_COMPLETED`	Staff completed it
`INSTANT_COMPLETED`	An `instantCraft` trade succeeded
`INSTANT_BURNED`	An `instantCraft` trade burned
`INSTANT_FAILED`	An `instantCraft` trade could not complete
`REFUND_PENDING`	A refund was owed but not delivered
`REFUND_DELIVERED`	The refund reached the player
`REFUND_FAILED`	The refund could not be delivered

Each row records the event type, the player, the trade id, the slot, the acting staff member if any, the refund mode, whether a full refund was even possible, and a timestamp.

Daily rollups

Alongside the raw events, counts are aggregated per day per trade in trade_daily_stats: started, completed, burned, cancelled and failed. That is what the summary commands read, so a total query does not scan the event log.

Dates are UTC, so "today" rolls over at 00:00 UTC regardless of where the server is.

In chat

/blacksmith admin analytics <today|week|month|total>

Prints the five counts for the period, then the top trades by volume with their own breakdown. Use it to answer the two questions that actually matter: which recipes people use, and which ones burn so often that nobody starts them twice.

/blacksmith admin analytics gui [period]

Defaults to today. The same figures with the period switchable in-place.

One player's history

/blacksmith admin history <player> [limit]

Newest first. limit defaults to 10 and is capped at 50. Each line is the event type, the trade, the slot, who did it, and the time — which is the answer to "my legendary sword disappeared".

Export

/blacksmith admin export <csv|json> [today]

Writes today's events to a file in the plugin folder and prints the absolute path. CSV for a spreadsheet, JSON for anything else.

The export runs off the main thread and reports back when it lands, so it does not stall the server on a busy day.

The pending queue

/blacksmith admin queue list [player]
/blacksmith admin queue gui
/blacksmith admin queue cancel <player> <slot> [refund|no-refund]
/blacksmith admin queue complete <player> <slot>

The live view of what is running, and the tools to intervene. cancel refunds by default; pass no-refund to take the materials.

A refund the player cannot receive — offline, full inventory — becomes a row in pending_refunds and is delivered on their next login. REFUND_PENDING then REFUND_DELIVERED in the event log is the normal, healthy sequence, not an error.

A command reward is not refundable

refundComplete on an event records whether everything could be returned. A trade whose reward ran commands, or whose requirement was consumed by a hook that has since been disabled, cannot be made whole. Check that flag before telling a player they got everything back.

Placeholders

%uxmblacksmith_analytics_today_started%
%uxmblacksmith_analytics_today_completed%
%uxmblacksmith_analytics_today_burned%
%uxmblacksmith_analytics_today_cancelled%
%uxmblacksmith_analytics_today_failed%

Server-wide, cached, safe on a scoreboard.

Retention

Nothing prunes trade_events or progression_events. On a busy server they grow steadily. They are indexed by player, trade and timestamp, so queries stay fast, but the file does not shrink — plan a periodic archive if you run for years.

Was this page helpful?