Analytics Commands

Commands for viewing permission usage analytics, identifying unused permissions, and auditing permission changes on your server.

Command Summary

Command	Description
`/hp analytics`	Show analytics help
`/hp analytics help`	Show analytics help
`/hp analytics summary`	View permission usage overview
`/hp analytics hotspots [limit]`	Most frequently checked permissions
`/hp analytics unused [days]`	Permissions not checked recently
`/hp analytics audit [holder]`	View permission change history
`/hp analytics export [format]`	Export analytics data

Permissions

Permission	Description	Default
`hyperperms.command.analytics`	Access to all analytics commands	op
`hyperperms.command.analytics.summary`	View analytics summary	op
`hyperperms.command.analytics.hotspots`	View permission hotspots	op
`hyperperms.command.analytics.unused`	View unused permissions	op
`hyperperms.command.analytics.audit`	View audit log	op
`hyperperms.command.analytics.export`	Export analytics data	op

SQLite Requirement

Analytics commands require the SQLite JDBC driver to store and query analytics data. The driver is not bundled with HyperPerms to keep the JAR file small.

If the SQLite driver is not installed, analytics commands will show setup instructions instead of data. You must install the driver and enable analytics in your config before these commands will work.

Installing the SQLite Driver

Download the SQLite JDBC driver from the official repository
Place the JAR file in the mods/com.hyperperms_HyperPerms/lib/ directory
Enable analytics in your configuration (see below)
Restart the server

text

# Directory structure after installing the driver:
mods/
└── com.hyperperms_HyperPerms/
    ├── config.json
    ├── data/
    └── lib/
        └── sqlite-jdbc-3.x.x.jar

Enabling Analytics

Set analytics.enabled to true in your config.json:

json

{
  "analytics": {
    "enabled": true
  }
}

Analytics data collection begins after the driver is installed, analytics is enabled, and the server is restarted. Historical data from before enabling is not available.

Viewing the Summary

/hp analytics summary

Show an overview of permission check activity on your server, including total checks, grant and deny counts, grant rate, and unique permissions checked.

text

Usage: /hp analytics summary

Output:
[HyperPerms] Permission Analytics Summary
[HyperPerms] ─────────────────────────────
[HyperPerms] Total checks:        14,328
[HyperPerms] Grants:              12,105
[HyperPerms] Denies:               2,223
[HyperPerms] Grant rate:           84.5%
[HyperPerms] Unique permissions:      67

Finding Hotspots

/hp analytics hotspots

Show the most frequently checked permissions on your server. Useful for identifying which permissions are checked most often and may benefit from optimization.

text

Usage: /hp analytics hotspots [limit]

Arguments:
  [limit]  - Number of results to show (default: 10)

Examples:
/hp analytics hotspots
/hp analytics hotspots 5

Output:
[HyperPerms] Permission Hotspots (Top 10):
[HyperPerms] ─────────────────────────────
[HyperPerms]  1. server.chat           3,412 checks (23.8%)
[HyperPerms]  2. server.build          2,891 checks (20.2%)
[HyperPerms]  3. server.interact       1,756 checks (12.3%)
[HyperPerms]  4. server.command.help   1,203 checks (8.4%)
[HyperPerms]  5. server.teleport         892 checks (6.2%)
[HyperPerms]  6. mod.kick                445 checks (3.1%)
[HyperPerms]  7. mod.ban                 312 checks (2.2%)
[HyperPerms]  8. server.fly              298 checks (2.1%)
[HyperPerms]  9. admin.manage            187 checks (1.3%)
[HyperPerms] 10. server.kit.daily        156 checks (1.1%)

Finding Unused Permissions

/hp analytics unused

List permissions that have not been checked in the specified number of days. Useful for cleaning up stale or unnecessary permission nodes.

text

Usage: /hp analytics unused [days]

Arguments:
  [days]  - Number of days since last check (default: 30)

Examples:
/hp analytics unused
/hp analytics unused 7
/hp analytics unused 90

Output:
[HyperPerms] Unused Permissions (not checked in 30 days):
[HyperPerms] ─────────────────────────────────────────────
[HyperPerms]  - mod.legacy.warn         (last: 45 days ago)
[HyperPerms]  - server.oldfeature       (last: 62 days ago)
[HyperPerms]  - admin.debug.verbose     (never checked)
[HyperPerms]  - server.kit.seasonal     (last: 38 days ago)
[HyperPerms]
[HyperPerms] 4 permissions found.

Regularly check for unused permissions and remove them from your groups. This keeps your permission setup clean and easier to manage.

Viewing the Audit Log

/hp analytics audit

View the history of permission changes. Optionally filter by a specific holder (group or user). Each entry shows the timestamp, action, permission, holder, who made the change, and the source.

text

Usage: /hp analytics audit [holder]

Arguments:
  [holder]  - Optional filter. Format: group:<name> or user:<uuid>

Examples:
/hp analytics audit
/hp analytics audit group:mod
/hp analytics audit user:069a79f4-44e9-4726-a5be-fca90e38aaf5

Output:
[HyperPerms] Audit Log:
[HyperPerms] ──────────
[HyperPerms] 2026-02-22 14:30:52 | ADD    | mod.timeout      | group:mod   | Steve    | command
[HyperPerms] 2026-02-22 14:28:11 | REMOVE | mod.legacy       | group:mod   | Steve    | command
[HyperPerms] 2026-02-22 13:15:04 | ADD    | server.fly       | user:069a.. | Console  | console
[HyperPerms] 2026-02-21 19:42:30 | CREATE | -                | group:vip   | Steve    | command
[HyperPerms] 2026-02-21 18:30:00 | SET    | weight:50        | group:mod   | Console  | web-editor

Audit Entry Fields

Timestamp - When the change occurred
Action - Type of change (ADD, REMOVE, CREATE, SET, DELETE)
Permission - The permission node affected (or other data like weight)
Holder - The group or user that was changed
Executor - Who made the change (player name or Console)
Source - How the change was made (command, console, web-editor, api)

Exporting Data

/hp analytics export

Export analytics data to a file for external analysis or record-keeping.

text

Usage: /hp analytics export [format]

Arguments:
  [format]  - Export format: json (default) or csv

Examples:
/hp analytics export
/hp analytics export json
/hp analytics export csv

Output:
[HyperPerms] Exporting analytics data...
[HyperPerms] Export complete!
[HyperPerms] File: exports/analytics_20260222_143052.json
[HyperPerms] Size: 245 KB

Exports are saved to the exports/ directory inside your HyperPerms data folder with a timestamped filename:

text

exports/
├── analytics_20260222_143052.json
└── analytics_20260215_091200.csv

JSON exports include all analytics data including raw check counts, audit entries, and metadata. CSV exports are formatted for spreadsheet applications with one row per permission node.

Configuration

Analytics behavior can be configured in config.json:

json

{
  "analytics": {
    "enabled": true
  }
}

analytics.enabled - Enable or disable analytics data collection (default: false)

Disabling analytics stops data collection but does not delete existing data. Re-enabling analytics will resume collection and existing data will still be available.

Complete Examples

Initial Analytics Setup

text

# 1. Install SQLite driver
# Place sqlite-jdbc-3.x.x.jar in mods/com.hyperperms_HyperPerms/lib/

# 2. Enable analytics in config.json
# Set analytics.enabled to true

# 3. Restart the server

# 4. Wait for data to accumulate, then check the summary
/hp analytics summary

# 5. View hotspots to see what's being checked most
/hp analytics hotspots

Permission Cleanup Workflow

text

# Find permissions not used in the last 60 days
/hp analytics unused 60

# Review which groups have these permissions
/hp group info mod

# Remove stale permissions
/hp group removeperm mod mod.legacy.warn

# Verify the audit log shows the change
/hp analytics audit group:mod

Exporting for Analysis

text

# Export as JSON for programmatic analysis
/hp analytics export json

# Export as CSV for spreadsheet review
/hp analytics export csv

# Files are saved to exports/ directory

Investigating Permission Issues

text

# Check if a permission is being checked at all
/hp analytics hotspots 50

# Check what changes were made to a group recently
/hp analytics audit group:mod

# Check changes made to a specific user
/hp analytics audit user:069a79f4-44e9-4726-a5be-fca90e38aaf5

Analytics Commands

Command Summary

Permissions

SQLite Requirement

Installing the SQLite Driver

Enabling Analytics

Viewing the Summary

/hp analytics summary

Finding Hotspots

/hp analytics hotspots

Finding Unused Permissions

/hp analytics unused

Viewing the Audit Log

/hp analytics audit

Audit Entry Fields

Exporting Data

/hp analytics export

Configuration

Complete Examples

Initial Analytics Setup

Permission Cleanup Workflow

Exporting for Analysis

Investigating Permission Issues

See Also