Trade Logging - Shopkeepers/Shopkeepers-Wiki GitHub Wiki
The Shopkeepers plugin can create a historical record of all trades that took place.
Depending on the configured storage format, you can also view the trading history in-game using the /shopkeeper history command (see Commands).
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. Supports the in-game trading history.CSV: Logs all trades to daily CSV files inside the plugin folder. Does NOT support the in-game trading history.
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 use cases and keeps the complexity of this feature low.
If you have a use case 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. Implementing additional storage formats as third-party add-on plugins, instead of adding them to the Shopkeepers plugin directly, helps to keep the maintenance effort of the core plugin low.
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.
If you want item attributes, such as display names, to show up in the in-game trading history, you must enable this setting.
This item metadata is represented in a compact Yaml representation based on Bukkit's item serialization. See Item Serialization for details.
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.
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 collect the trades over a duration of 10 seconds before we write them in a single batch to the trade log. This buffering duration cannot be configured.
This buffering duration provides some reduction of IO operations on servers with lots of trades, while still being short enough to not delay the logging of trades, which would affect the user experience of other features such as the in-game or third-party trading histories: Depending on the configuration of trade merging (see above), it can take 10-25 seconds for trades to be written to the log and then show up in the in-game trading history.