GraniteLog — Lightweight, Fast & Modern Block Logger for Paper/Spigot

GraniteLog is a high-performance block logging and rollback plugin built for Paper/Spigot servers.
It prioritizes speed, clarity, and admin usability, while keeping the database schema simple, efficient, and migration-friendly.

✅ Actively tested on latest Paper builds
✅ Compact storage with zero-NBT by default (optional JSON compression)
✅ Multiple storage options: SQLite, MySQL/MariaDB, PostgreSQL

---

Key Features

Block & Action Tracking

• Tracks all major block-related events:

  • Block place/break, fluid flow, crop growth, explosions
  • Interactions: doors, levers, buttons, beds, armor stands, sign edits, books
  • Container edits (add/remove items) with meta-aware diffs
  • Hopper/pipe IO moves tracked separately

Investigation Tools

• /inspect — Click blocks to view full history

  • Sneak → paginate results
  • Sprint → view container diffs + recent sign edits

• /lookup — Quickly list changes at the targeted block

Rollback, Restore & Undo

• Rollback/restore any set of changes with filters:

  • Radius, time, user, block ID, action, entity

• Preview → Confirm workflow prevents mistakes

• Each operation generates a batch ID, allowing precise undo with /rbundo

Discord Webhooks

• Send formatted change logs straight to Discord

• Features:

  • Multiple endpoints with per-webhook action filters
  • Async dispatch queue (won’t block gameplay)
  • TNT explosions show affected block counts

Storage & Maintenance

• Databases supported: SQLite (default), MySQL/MariaDB, PostgreSQL
• Automatic schema migrations on startup
• Retention policy to purge old data automatically
• Optional JSON meta compression to save space

Performance-Oriented

• Async ingest queue with backpressure + drop counter
• Batched database writes & optimized indices
• Configurable safety caps for heavy rollbacks

---

Commands Overview

Inspection & Lookup

• /inspect [on|off] → Click a block for history
• /lookup [limit=N] → List recent changes instantly

Rollback & Restore

• /rollback preview <filters>
• /rollback confirm <filters>
• /restore preview <filters>
• /restore confirm <filters>
• Filters: radius|r, time=30m/12h/3d, user=<name>, block=<ns:id>, action=place,break,explode, entity=<ns:id>, chunklock, page=<n>

Undo

• /rbundo <batchId> — Undo an exact rollback/restore

Admin

• /glog status → Event & queue stats
• /glog reload → Reload config
• /glog purge olderThan:<time> → Purge old rows (e.g. 90d, 12h)
• /glog migrate to:mysql → Migrate data from SQLite → MySQL

---

Permissions

GraniteLog uses fine-grained permission nodes so you can control who can investigate, rollback, and manage data.

permissions:
  glog.inspect:
    description: Use inspect mode
    default: op

  glog.lookup:
    description: Lookup history
    default: op

  glog.rollback:
    description: Execute rollbacks
    default: op

  glog.restore:
    description: Execute restores
    default: op

  glog.rbundo:
    description: Undo a rollback batch
    default: op

  glog.admin:
    description: Use GraniteLog admin commands
    default: op
    children:
      glog.admin.status: true
      glog.admin.purge: true
      glog.admin.reload: true

  glog.admin.status:
    description: View GraniteLog status
    default: op

  glog.admin.purge:
    description: Purge old GraniteLog records
    default: op

  glog.admin.reload:
    description: Reload GraniteLog config/locales
    default: op

Permission Overview

• glog.inspect → Toggle inspect mode and click blocks for history

• glog.lookup → Use /lookup to list recent changes

• glog.rollback → Run rollbacks with /rollback

• glog.restore → Run restores with /restore

• glog.rbundo → Undo rollbacks/restores with /rbundo

• glog.admin → Master node for all admin commands

  • glog.admin.status → View plugin statistics
  • glog.admin.purge → Purge old data
  • glog.admin.reload → Reload config and locales

---

⚙ Config Highlights (config.yml)

• Choose storage: sqlite | mysql | postgres

• Configure limits:

  • Inspect max entries
  • Rollback preview/confirm thresholds

• Enable/disable action logging (block, container, interactions, fluids, growth, explosions, containerIO)

• JSON compression with configurable threshold

• Webhook settings: endpoints, filters, timeouts

---

Data Migration (SQLite → MySQL)

Migrate seamlessly without losing data:

1. Configure MySQL in config.yml (keep storage.type: sqlite)
2. Run: /glog migrate to:mysql
3. Switch storage type to mysql and restart

Migration is safe: SQLite remains intact as a backup.

---

Inspect & Lookup in Action

• Inspect → View detailed history with timestamps & actors

• Sprint while inspecting to show:

  • Container changes (-3x cobblestone | +2x sand)
  • Sign edits (preview old → new)

• Lookup → One-shot block history without interaction

---

Rollback/Restore Workflow

1. Preview to review changes
2. Confirm to apply rollback/restore
3. GraniteLog reports: Rollback applied. Batch <id>, changed <n> blocks.
4. Undo at any time with /rbundo <id>

---

Performance & Storage

• Automatic schema migrations
• Retention policies to purge old logs
• Optimized indices for fast lookups
• Async queue ensures no TPS drops during heavy logging

---

FAQ

Q: Does it support PostgreSQL?
A: Yes — set storage.type: postgres.

Q: How do I find a batch ID for /rbundo?
A: After a rollback/restore, GraniteLog prints Batch <id> in chat.

Q: Can I filter Discord notifications?
A: Yes — set per-webhook action filters.

Q: How do I reduce database size?
A: Enable JSON meta compression + configure retention.

---

Roadmap

• Smarter webhook rate limiting/backoff
• Optional Discord embed formatting
• More granular filters & summaries in /inspect

---

Support

• Open an issue with your server version + config
• For performance help, include: timings, row counts, database type