🔍 Cracking the Code: Enabling Detailed Persistence Debugging in Joget

Overview

When troubleshooting Joget workflows, standard error logs sometimes lack the specific details needed to pinpoint which activity or tool is failing. By enabling Persistence Debugging, you can track exactly which process IDs and activity definitions are being handled by the engine in real-time. This is essential for identifying the "where" and "why" behind workflow bottlenecks or silent failures.

How It Works

Joget uses Log4j2 for its logging framework. By adding a specific logger for Persistence at the DEBUG level in the system configuration, the server begins outputting granular details about activity persistence events. This reveals the internal IDs that link a running process to its specific configuration in the Workflow Builder.

Where to Use in Joget

• ✅ System Backend: Accessing the Joget installation directory.

• ✅ Workflow Builder: Identifying the definitionId and activityId shown in the logs.

Full Code

⚙️ Log4j2 Configuration Update
Locate and edit the file at /apache-tomcat-x.x.x/webapps/jw/WEB-INF/classes/log4j2.xml. Add the following block within the <Loggers> section:

<ThresholdFilter level="debug" />
<Logger name="Persistence" level="debug" additivity="true">
</Logger>

Note: Restart your Joget server for these changes to take effect.

---

Example Use Cases

• 💡 Stuck Processes: Finding the exact activityId that failed to persist during a transition.

• 💡 Tool Failures: Identifying which "BeanShell Tool" or "Email Tool" was active immediately before a database error.

• 💡 Audit Trail: Verifying that a process actually reached the database state-change phase.

Customization Tips

• ⚙️ Log to File: You can redirect these specific persistence logs to a separate file by defining a new AppenderRef within the Logger tag.

• ⚙️ Specific Classes: If "Persistence" is too broad, you can target specific Joget libraries like org.joget.workflow.model.

Key Benefits

• ✅ Precision: See the exact definitionId (e.g., tool5) causing issues.

• ✅ Real-time Tracking: Watch process movements as they happen.

• ✅ Faster Root Cause Analysis: Reduces guesswork when analyzing catalina.out.

🛡️ Security & Performance Note

Do not enable debug logs in a production environment, as excessive logging may impact application performance. Always revert the level to INFO once troubleshooting is complete. Additionally, ensure you perform regular backups of your .jwa files and database.

Final Thoughts

Enabling persistence logs turns the workflow engine into a transparent map. Once you have the activityId and processId from the debug logs, you can easily find the offending element in the Workflow Builder and fix it.

Comments

[Rasmus Ros]

Detailed persistence debugging can add overhead in workflows. How do you handle performance impacts with this?

[Explorer]

That’s a great point about the overhead! To keep things running smoothly, it's best to use targeted logging by focusing only on specific Joget libraries, like org.joget.workflow.model, instead of logging everything. Since this can impact performance and disk space, recommend using it only for temporary troubleshooting and never in a production environment. Once you've caught the bug, just remember to revert the logs back to the INFO level.

[Rasmus Ros]

right, and the awkward bit is that debug logging can change timing enough to hide racey workflow bugs, so scoping it tightly and reproducing on staging with production-like load is usually the only sane way to trust what you see.