📊 Maykesh’s Server Observability Framework (Freemium • Beta)

A formal observability and telemetry framework built exclusively for Fabric 1.21 servers.
This freemium module instruments the full Minecraft server runtime and exposes structured telemetry for developers building optimisation tools, diagnostics, debugging utilities, or rate‑limiting systems. It provides unified resource attribution, modular collectors, and a central telemetry bus for deep server introspection — all without altering gameplay.

---

⚠️ Current Build Status (Freemium‑Beta)

This build is Freemium‑Beta, providing:

• basic metrics,
• core collectors,
• telemetry bus,
• commands,
• config systems,
• NO GUI yet.

The Freemium‑Release build (ETA: ~3 days) will introduce a basic, minimal, functional GUI designed for simple collector toggling and basic metric viewing.

Premium and Ultra‑Premium editions will feature a more advanced, more organised, and significantly more capable UI designed for deep analysis and production‑grade observability.

---

🔗 External Links

Available for download on CurseForge:
https://www.curseforge.com/minecraft/mc-mods/maykeshs-server-observability-framework-mod

CurseForge Comments / Feedback:
https://www.curseforge.com/minecraft/mc-mods/maykeshs-server-observability-framework-mod/comments

---

⚠️ Licensing & Redistribution

This project is licensed under CC BY‑NC‑SA 4.0.

If this mod is edited, modified, extended, or redistributed, the resulting work:

• must be provided for free,
• must be published on Github,
• must remain open‑source,
• must credit both Maykesh and PhaseZero Labs,
• must include a link back to the original Modrinth project page,
• must NOT be used commercially,
• must follow all other terms of the license.

Any derivative version must clearly state that it is a fork and must link directly to this original Modrinth page.

---

⚠️ Recommendation Notice

This freemium version is ideal for development, testing, diagnostics, and lightweight observability.

It is not recommended for advanced server owners
and not recommended for advanced players who require full‑scale analysis, production‑grade exporters, or deep runtime tooling.

A Premium Edition — featuring a powerful UI, extended exporters, and deeper analysis tools — is scheduled for release within 1–4 weeks.
Advanced users should wait for the premium version for the best experience.

---

🚀 Why Use This Framework?

• 📡 Full Runtime Instrumentation — Observe tick loops, entity updates, chunk activity, packet flow, async tasks, scheduler queues, worldgen events, and more.
• 🧩 Modular Collector System — 16 collectors, each independently toggleable through config or commands.
• 📁 Structured Telemetry Output — Export unified metrics via JSON files or in‑memory buffers.
• 🔌 Telemetry Bus API — Other mods can subscribe to real‑time events for custom tooling and integrations.
• 🧭 Command-Based Management — Enable, disable, reload, test, and inspect collectors directly in-game.
• 🛡️ Zero Gameplay Changes — Purely diagnostic; no mechanics, no balance changes, no player-facing impact.
• 🎯 Fabric 1.21 Only — Designed specifically for the 1.21 runtime and its updated APIs.
• 💠 Freemium Tier — Core collectors, telemetry, commands, and config systems included.
  Premium features (advanced UI, extended exporters, deeper analysis tooling) are not included in this version.

---

✨ Features

📈 Core Observability

• Tick Loop Instrumentation — Monitor tick duration and subsystem cost.
• Entity Updates — Track update load and behaviour metrics.
• Chunk Loading — Observe load/unload operations and memory pressure.
• Packet Send/Receive — Inspect inbound/outbound packet frequencies.
• Block & Redstone Updates — Identify update-heavy areas.
• World Generation Events — Track worldgen queue activity.
• Event Bus Activity — Detect mod/plugin event spam.
• Thread Pools & Async Tasks — Monitor background workloads.
• Scheduler Queues — Inspect delayed and scheduled tasks.
• Pathfinding & Inventory Ops — Attribute cost to high-impact systems.
• Command Execution — Profile command processing.
• Anomaly Detection — Detect spikes, floods, and runaway loops.

🛠️ Configuration & Control

• Hot Reloading — Apply config changes without restarting the server.
• Permission System — Fully configurable OP level requirements.
• Config Files
  • config/runtime-profiler.json
  • config/runtime-profiler-permissions.json

🧭 Command Interface

• /profiler help — Show all commands and collectors
• /profiler list — View collector status
• /profiler enable <collector> — Enable a collector
• /profiler disable <collector> — Disable a collector
• /profiler toggle <collector> — Toggle a collector
• /profiler reload — Reload configuration
• /profiler metrics — Display unified resource metrics
• /profiler test collectors — Run diagnostic tests

---

📌 Recommended For

• Developers building optimisation tools
• Diagnostics and debugging environments
• Rate‑limiting and anti‑spam systems
• Monitoring dashboards and analytics pipelines
• Early-stage development and testing

Not recommended for advanced server owners or advanced players.
Premium Edition recommended (1–4 weeks).

---

📜 Requirements

• Minecraft 1.21
• Fabric Loader 0.15.11+
• Fabric API 0.100.8+1.21
• Java 21
• Fabric Only — No Quilt, No Forge, No NeoForge

---

🧪 About PhaseZero Labs

Developed by Maykesh under PhaseZero Labs (pz.labs),
an organisation combining human expertise with AI‑assisted tooling to accelerate development, testing, and optimisation workflows for complex Minecraft mods.