Trade Logging - Shopkeepers/Shopkeepers-Wiki GitHub Wiki

The Shopkeepers plugin can create a historical record of all trades that took place.

Viewing the trading history in-game is not yet supported.

Supported Storage Formats

The trade logging can be enabled inside the config by setting trade-log-storage to one of the supported storage formats:

• DISABLED (default): Disables the logging of trades.
• SQLITE (recommended): Logs all trades to an SQLite database inside the plugin folder.
• CSV: Logs all trades to daily CSV files inside the plugin folder.

Only one storage format can be enabled at a time.

We currently only support local file-based storage formats since this is sufficient for the plugin's own anticipated usecases and keeps the complexity of this feature low.

If you have a usecase that would benefit of writing the trade log to a remote database or other storage format, consider implementing the trade logging yourself by writing an add-on plugin that reacts to the ShopkeeperTradeCompletedEvent, or contribute an implementation via a pull request (try to stick close to the implementation of the existing trade loggers).

The data format of each of these supported storage formats may change in future updates. If you write any tools that automatically process the trade log, be aware that you may have to update your tool whenever the data format changes.

SQLite

When enabled, the plugin logs trades to a SQLite database file named trades.db inside the folder trade-logs inside the plugin folder.

CSV

When enabled, the plugin logs trades in a CSV format to files inside the folder trade-logs inside the plugin folder.

Trades are grouped by date: Each CSV log file collects the trades that took place in a single day. Currently, all date and time information uses the server's local timezone.

Item Metadata

By default, to keep the log files smaller, we only log the types of the items involved in the trades. The setting log-item-metadata (default: false) enables the additional logging of item metadata, such as for example item display names, lore, etc.

This item metadata is represented in a compact Yaml representation based on Bukkit's item serialization. See Item Serialization for details.

Buffered Logging

In order to not block the server's main thread with IO operations, the trade log is written asynchronously by another thread. Additionally, to further limit IO operations, we log the trades in batches: When a trade takes place, we wait 30-45 seconds (depends on the additional trade merging duration, see below) before we log the trade and any other trades that may have taken place during this timespan.

Trade Merging

In order to represent the logged trades more compactly, we merge equivalent trades that are triggered in quick succession over a certain period of time into a single record.

By default, we merge successive equal trades for up to 15 seconds, but only if there is no gap longer than 5 seconds between the individual trades. The settings trade-log-merge-duration-ticks and trade-log-next-merge-timeout-ticks control these parameters. They also allow the trade merging to be disabled. See Configuration for details.