guidewire-debug-bundle
Guidewire Debug Bundle
Overview
Comprehensive debugging techniques for Guidewire InsuranceSuite including Gosu debugging, Cloud API tracing, log analysis, and performance profiling.
Prerequisites
- Access to Guidewire Cloud Console
- IntelliJ IDEA with Gosu plugin
- Basic understanding of Java debugging
- Access to application logs
Instructions
Step 1: Enable Debug Logging
Configure Log4j2 with DEBUG level for gw.custom, gw.plugin, gw.api.rest, gw.api.database, and gw.integration categories. Use rolling file appender with 100 MB size limit.
Step 2: Gosu Debugging in IDE
Use the DebugHelper class for method tracing, entity state dumps, and query profiling. Set breakpoints in IntelliJ and attach to the debug port (5005).
Step 3: Remote Debugging Setup
export JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" # 5005 = configured value
./gradlew runServer
In IntelliJ: Run > Edit Configurations > Remote JVM Debug (localhost:5005).
Step 4: API Request Tracing
Add axios interceptors to log request/response details with unique request IDs and Guidewire trace IDs (x-gw-trace-id).
Step 5: Cloud Console Log Analysis
Use Lucene queries in Guidewire Cloud Console Observability > Logs to search for errors by claim number, slow API calls, auth failures, or integration errors.
Step 6: Database Query Analysis
Profile queries with QueryPlanExplainer to detect full table scans and slow queries exceeding 1 second.
Step 7: Memory and Thread Analysis
Monitor JVM memory usage and dump thread state when investigating performance issues or deadlocks.
For detailed code implementations (Log4j2 config, Gosu helpers, TypeScript tracing, query analysis), load the reference guide:
Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)
Output
- Debug logs with trace information
- Query execution plans
- Memory and thread dumps
- Complete debug bundle for support
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| No debug logs | Wrong log level | Set categories to DEBUG |
| Debugger won't attach | Wrong port or firewall | Verify JAVA_OPTS and port |
| Slow query undetected | No profiling | Wrap queries with profileQuery |
| Missing trace IDs | Headers not logged | Add response interceptor |
Resources
Next Steps
For rate limiting information, see guidewire-rate-limits.
Examples
Basic usage: Apply guidewire debug bundle to a standard project setup with default configuration options.
Advanced scenario: Customize guidewire debug bundle for production environments with multiple constraints and team-specific requirements.