PlugTrace

🔍 PlugTrace

Most server updates don't fail in a dramatic way. The server starts, the console reaches Done, and everything looks normal until someone notices a command is missing, a plugin never enabled, a dependency broke, or a config got reset.

PlugTrace is built for that exact situation. It keeps a history of deployments, watches the server after startup, compares the new state against a healthy one, and tells you whether the update actually held together.

Instead of treating "the process is still running" as success, it checks the parts of the server you actually care about.

A deployment can end up as HEALTHY, DEGRADED, FAILING, or UNKNOWN, with the evidence that led to that result.

⚡ spark is great for finding what is slow. PlugTrace is for finding what changed after an update.

---

🎬 Demo

HEALTHY → bad restart → FAILING → diff → share report.

---

🛡️ Baselines

PlugTrace is most useful when you install it while the server is still healthy.

Before a risky update, capture the state you want future deployments to be compared against:

/plugtrace selfcheck
/plugtrace checkpoint <name>
/plugtrace expected capture
/plugtrace mark healthy
/plugtrace status

expected capture records things such as plugins, commands, worlds, and registered services that should still be there after the next restart.

Once that's done, update your plugins, replace JARs, change configs, upgrade Paper, or do whatever maintenance you were going to do anyway.

After the restart:

/plugtrace status

That's the normal workflow:

capture a healthy state → make the change → restart → check what actually happened.

A PlugTrace checkpoint is a reference to a known-good deployment, not a backup.

Keep normal backups for worlds, databases, configs, and anything else you cannot afford to lose.

---

🕵️ Detection

PlugTrace is mainly interested in the failures that are easy to miss.

Depending on what changed, it can surface things such as:

• plugins disappearing, disabling, or failing to enable
• commands that existed before the update going missing
• missing worlds or registered services
• broken or missing dependencies
• plugin JARs being added, removed, or replaced
• a JAR changing while keeping the same version number
• config reset or deletion evidence
• new severe startup issues
• failures that appear during the post-start observation window

It also keeps the useful context around the deployment:

• failed checks
• important JAR differences
• changes from the healthy baseline
• detected issues
• incident history
• the strongest suspect supported by the evidence

That last part is intentionally conservative.

PlugTrace isn't supposed to invent a root cause just because something looks suspicious. If the available evidence isn't strong enough, it can return UNKNOWN instead.

---

⚡ Status

For day-to-day use, /plugtrace status is the main command.

/plugtrace status

If you need to dig further:

/plugtrace diff
/plugtrace issues
/plugtrace incidents
/plugtrace suspect
/plugtrace deployments

PlugTrace also keeps observing the deployment for a configurable period after the server becomes ready.

This matters because some problems don't happen during startup itself — they appear shortly afterward.

While that observation is still running, the deployment is OBSERVING.

Once it finishes, PlugTrace settles on one of these states:

State	Meaning
✅ HEALTHY	Critical checks passed
⚠️ DEGRADED	Something regressed, but no critical check failed
❌ FAILING	One or more critical checks failed
❓ UNKNOWN	There isn't enough reliable evidence to make a confident call

---

🔗 Sharing

When you need help from another admin, a plugin developer, or a host, dumping the entire console usually isn't ideal.

PlugTrace can build a report around the deployment instead, so the person looking at it gets the failed checks, relevant changes, incident evidence, and surrounding context in one place.

Preview it first:

/plugtrace report preview

If you decide to share it:

/plugtrace share

That creates a hosted PlugTrace report link you can send through Discord, GitHub, or a support ticket.

🔐 Privacy

Hosted reports are optional and nothing is uploaded automatically.

Checkpoints, verification, deployment history, local reports, and the local dashboard stay on your server.

A hosted report is uploaded only when an administrator explicitly runs:

/plugtrace share

Before upload, the report is redacted and encrypted.

The hosted service stores the encrypted report data, while the decryption key remains in the #k=... fragment of the full share URL.

Anyone with the complete URL can open the report, so treat it as private.

Hosted reports expire automatically; the default lifetime is 14 days.

PlugTrace can also send a redacted deployment digest to a Discord webhook if you configure one. No webhook is configured by default, and Discord notifications do not automatically create or upload a hosted report.

More details:

🔐 PlugTrace Privacy

---

🏠 Local-first

You don't need a PlugTrace account, and the hosted report service is not required for normal use.

Commands, verification, deployment history, local reports, and the optional web UI all work locally.

The dashboard binds to:

http://127.0.0.1:9465

by default and gives you a cleaner way to browse deployments, changes, checks, incidents, suspects, checkpoints, and recovery state.

If you choose to expose the dashboard outside localhost, secure it properly behind TLS and a reverse proxy.

---

↩️ Restore

When the required local evidence exists, PlugTrace can prepare a conservative restore plan:

/plugtrace restore preview
/plugtrace restore stage
/plugtrace restore finalize
/plugtrace restore verify
/plugtrace restore complete

The restore flow is deliberately review-first.

The goal is to recover the smallest relevant change supported by the evidence rather than blindly rolling the whole server backward.

You can abort an in-progress restore with:

/plugtrace restore abort

PlugTrace does not automatically restore worlds or databases, and it does not make hot reloads safe.

Use proper backups alongside it.

---

📦 Install

Drop PlugTrace into plugins/, perform a clean restart, then check that everything loaded correctly:

/plugtrace selfcheck

Once the server is in a healthy state, capture that baseline before the next risky update.

PlugTrace runs entirely server-side, so players do not need to install anything.

Compatibility

• Paper
• Purpur
• Folia
• Spigot
• No client mod required
• Server-side only
• Uses the Java version required by your server software

Check the compatibility information on the version you're downloading before installing.

---

💜 Free & open source

PlugTrace is free and open source under the Apache License 2.0.

There is no required account, paid edition, or required cloud service.

Hosted reports are there when you want to share an incident; the core deployment tracking and verification workflow does not depend on them.

🎬 Watch the demo
🌐 Website
📖 Documentation
💻 Source Code
🐛 Issue Tracker
💬 Discord
☕ Ko-fi

---

📊 Usage Stats

PlugTrace uses bStats for anonymous usage metrics.

---

🧪 PLUG Labs

PlugTrace is built under PLUG Labs, which is also where its support, ideas, testing, bug reports, development discussion, and release news live.

💬 Join the PLUG Labs Discord
🐛 Open an issue
📖 Read the docs
🎬 Watch PlugTrace in action