Installing zAuctionHouseStats

This guide covers installing the zAuctionHouseStats addon, choosing its storage, and checking that statistics are being collected.

RequirementsCopy Anchor Link

Server RequirementsCopy Anchor Link

Required PluginsCopy Anchor Link

These plugins are declared in the depend list of plugin.yml: the addon will not load without them.

Optional PluginsCopy Anchor Link

LibrariesCopy Anchor Link

The JDBC drivers are declared in the libraries section of plugin.yml, so the server downloads them on the first start. You do not need to install anything else.

Installation StepsCopy Anchor Link

1. Install the JarCopy Anchor Link

Place zAuctionHouseStats.jar in your server's plugins/ folder, next to zAuctionHouse.jar and zMenu.jar.

2. Start Your ServerCopy Anchor Link

Start the server once to generate the default files. With the default settings (SQLite), the addon works immediately.

3. Configure Storage and TimezoneCopy Anchor Link

Edit plugins/zAuctionHouseStats/config.yml:

• choose the storage type (SQLite for a single server, MySQL/MariaDB for a network);
• set the timezone before any statistics are recorded or imported.

4. Restart Your ServerCopy Anchor Link

Some settings are only read at startup: storage-type and database-configuration, collection.*, statistics.timezone, statistics.save-itemstacks, retention.sales-days and language.yml. /zahstats reload does not apply them (it prints a "restart required" warning in the console). Restart the server after changing them.

File StructureCopy Anchor Link

After the first start, zAuctionHouseStats creates the following structure:

plugins/zAuctionHouseStats/
├── language.yml            # Language of the generated files (auto, en, fr, es, it)
├── config.yml              # Main configuration
├── messages.yml            # All addon messages
├── inventories/
│   ├── stats.yml           # Statistics hub (/ah stats)
│   ├── leaderboard.yml     # Leaderboards
│   ├── player-stats.yml    # Player statistics
│   ├── item-prices.yml     # Item price explorer (/zahstats items)
│   └── admin.yml           # Admin status menu
├── patterns/
│   ├── zahstats-back.yml
│   └── zahstats-pagination.yml
└── database.db             # SQLite database (if using SQLite)

LanguageCopy Anchor Link

language.yml is read before any other file is generated. It selects the language of messages.yml, inventories/ and patterns/.

Any other value prints a warning and falls back to English. config.yml is always generated in its default version, whatever the language.

StorageCopy Anchor Link

zAuctionHouseStats uses its own database connection. It never writes into the zAuctionHouse tables: all its tables use their own prefix.

# SQLITE | MYSQL | MARIADB
storage-type: SQLITE

database-configuration:
  table-prefix: "zahstats_"
  host: 192.168.10.10
  port: 3306
  user: homestead
  password: secret
  database: zauctionhouse
  max-pool-size: 4
  min-idle: 2
  debug: false

SQLiteCopy Anchor Link

With storage-type: SQLITE, the data is stored in plugins/zAuctionHouseStats/database.db. No other setting is needed. SQLite is meant for a single server.

MySQL / MariaDBCopy Anchor Link

Set storage-type to MYSQL or MARIADB and fill in the connection details. You can use the same database as zAuctionHouse: the addon tables are kept apart by their prefix (zahstats_ by default).

With MySQL/MariaDB, the addon always uses a HikariCP connection pool sized by max-pool-size and min-idle.

If the connection or the migrations fail (or do not complete within 60 seconds), the addon disables itself and prints the reason in the console. It never runs in a degraded mode without storage.

Shared database-configuration.ymlCopy Anchor Link

If a database-configuration.yml file exists at the root of the server (the same file used by zAuctionHouse V4 and other GroupeZ plugins), it takes priority over config.yml key by key: each key it defines replaces the one in config.yml, missing keys fall back to config.yml.

The following keys are read from this file, under the database-configuration section:

When the file is detected, the console shows:

Using the server-wide database-configuration.yml for database credentials (table-prefix is still read from config.yml).

If the file exists but cannot be read, a warning is printed and the values of config.yml are used instead.

Tables CreatedCopy Anchor Link

On startup, the addon runs its migrations and creates the following tables (shown with the default zahstats_ prefix):

The migration registry follows the prefix (<prefix>migrations; with an empty prefix it is zahstats_migrations). It is never the generic migrations table nor the zAuctionHouse one, so the addon can safely share a database with zAuctionHouse. After the migrations, the addon checks that all tables exist; if one is missing while the registry marks it as created, the addon stops and tells you to drop that registry table (or restore the missing tables) and restart.

TimezoneCopy Anchor Link

Statistics for the DAY, WEEK and MONTH periods are grouped by day. The timezone used to cut those days is set in config.yml:

statistics:
  # Empty = server timezone. Example: "Europe/Paris".
  timezone: ""

The same timezone is used to display dates in the date placeholders (placeholders.date-format).

Multi-ServerCopy Anchor Link

When several servers share one auction house (see the zAuctionHouse Redis addon):

• use MYSQL or MARIADB and point every server to the same database with the same table-prefix. Counters are written as atomic increments, so several servers can write at the same time;
• do not use SQLite: each server would only see its own statistics. If the zAuctionHouseRedis addon is installed while the addon uses SQLite, a warning is printed at startup;
• each sale keeps the server name configured in zAuctionHouse;
• use the same statistics.timezone on every server;
• if you have to use the degraded logs polling mode (collection.mode: LOGS_POLLING), enable collection.polling.enabled on one server only. Servers with LOGS_POLLING and polling disabled collect nothing and print a warning.

Verify InstallationCopy Anchor Link

ConsoleCopy Anchor Link

A successful start prints lines similar to:

Storage ready (SQLITE, prefix 'zahstats_').
Statistics collection: zAuctionHouse stats events.
zMenu inventories loaded (language: en).
PlaceholderAPI expansion 'zahstats' registered.
zAuctionHouseStats 2.0.0 enabled.

The PlaceholderAPI line only appears when PlaceholderAPI is installed.

In GameCopy Anchor Link

All permissions default to operators. The admin menu (admin.yml, opened from the hub with zauctionhouse.stats.admin) shows the storage type, the collection mode and the state of the write queue and caches.

Statistics are written to the database every few seconds (flush.interval-seconds, 2 by default, or earlier once flush.max-pending events are waiting). On the server where the sale happens, player statistics already in cache and the global statistics are updated immediately. Leaderboards are recalculated when their cache expires (caches.leaderboard-ttl-seconds, 60 by default) and item prices every hour (caches.material-price-ttl-seconds, 3600), so a new sale can take that long to appear there. Use /zahstats clearcache to force an immediate refresh of the caches.

See Commands & Permissions for the full reference.

Upgrading from V1Copy Anchor Link

zAuctionHouseStats V2 only works with zAuctionHouse V4. Your V1 history (zah_* tables) and the zAuctionHouse V4 logs can be imported into the new tables with /zahstats import v1 and /zahstats import v4logs: without confirm the command only shows a preview (estimated rows and duration), /zahstats import <v1|v4logs> confirm starts the import. V1 placeholders keep working through compatibility aliases (placeholders.enable-v1-aliases).

Set the timezone before importing, then follow the Migration guide.

Next StepsCopy Anchor Link

• Commands & Permissions - Full command reference
• Placeholders - Display statistics anywhere
• Configuration - All config.yml options
• Inventories - Customize the menus