用途
Guidewire Debug Bundle 用于调试 Guidewire InsuranceSuite 相关问题，包括 Gosu 代码、Cloud API 集成以及系统性能问题。它适合在排查错误、分析慢查询、定位认证失败或集成错误等场景中使用。
主要能力
该技能包提供以下调试环节：
-
启用调试日志：配置 Log4j2，将 gw.custom、gw.plugin、gw.api.rest、gw.api.database、gw.integration 等类别设为 DEBUG 级别，并使用滚动文件追加器，单文件大小上限 100 MB。
-
Gosu 调试：在 IDE 中使用 DebugHelper 类进行方法追踪、实体状态转储和查询性能分析，在 IntelliJ 中设置断点并附加到调试端口（5005）。
-
远程调试：通过 JAVA_OPTS 配置 JDWP 远程调试，命令为：
export JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" # 5005 = configured value ./gradlew runServer
在 IntelliJ 中通过 Run > Edit Configurations > Remote JVM Debug（localhost:5005）连接。
-
API 请求追踪：添加 axios 拦截器，记录请求/响应详情，并附带唯一请求 ID 和 Guidewire 追踪 ID（x-gw-trace-id）。
-
Cloud Console 日志分析：在 Guidewire Cloud Console 的 Observability > Logs 中使用 Lucene 查询，按索赔编号、慢 API 调用、认证失败或集成错误进行检索。
-
数据库查询分析：使用 QueryPlanExplainer 分析查询，检测全表扫描和超过 1 秒的慢查询。
-
内存与线程分析：监控 JVM 内存使用情况，在排查性能问题或死锁时转储线程状态。
如需详细代码实现（Log4j2 配置、Gosu 辅助类、TypeScript 追踪、查询分析），可加载参考指南： Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)
使用方式
按照技能包中的步骤依次操作：先启用调试日志，再进行 Gosu 调试或远程调试，随后进行 API 请求追踪、Cloud Console 日志分析、数据库查询分析，最后进行内存与线程分析。
输出
- 带追踪信息的调试日志
- 查询执行计划
- 内存与线程转储
- 用于提交支持的完整调试包
错误处理
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 无调试日志 | 日志级别错误 | 将类别设为 DEBUG |
| 调试器无法附加 | 端口或防火墙错误 | 验证 JAVA_OPTS 和端口 |
| 未检测到慢查询 | 未进行性能分析 | 用 profileQuery 包装查询 |
| 缺少追踪 ID | 未记录请求头 | 添加响应拦截器 |
适用场景
适用于需要排查 Guidewire InsuranceSuite 中 Gosu 代码问题、Cloud API 集成问题以及系统性能问题的开发与运维场景。
限制与前提
使用前需要：
- 具备 Guidewire Cloud Console 访问权限
- 安装带 Gosu 插件的 IntelliJ IDEA
- 具备 Java 调试基础知识
- 具备应用日志访问权限
关于速率限制信息，可参见 guidewire-rate-limits。
示例
- 基础用法：在采用默认配置选项的标准项目设置中应用 guidewire debug bundle。
- 高级场景：针对生产环境，结合多重约束和团队特定需求定制 guidewire debug bundle。