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

<!-- config/logging/log4j2.xml -->
<Configuration status="WARN">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
    </Console>
    <RollingFile name="DebugFile" fileName="logs/debug.log"
                 filePattern="logs/debug-%d{yyyy-MM-dd}-%i.log.gz">
      <PatternLayout pattern="%d{ISO8601} [%t] %-5level %logger{36} - %msg%n"/>
      <Policies>
        <SizeBasedTriggeringPolicy size="100 MB"/>
      </Policies>
    </RollingFile>
  </Appenders>

  <Loggers>
    <!-- Application logging -->
    <Logger name="gw.custom" level="DEBUG"/>
    <Logger name="gw.plugin" level="DEBUG"/>

    <!-- API logging -->
    <Logger name="gw.api.rest" level="DEBUG"/>
    <Logger name="gw.api.webservice" level="DEBUG"/>

    <!-- Database query logging -->
    <Logger name="gw.api.database" level="DEBUG"/>
    <Logger name="org.hibernate.SQL" level="DEBUG"/>

    <!-- Integration logging -->
    <Logger name="gw.integration" level="DEBUG"/>

    <Root level="INFO">
      <AppenderRef ref="Console"/>
      <AppenderRef ref="DebugFile"/>
    </Root>
  </Loggers>
</Configuration>

Step 2: Gosu Debugging in IDE

// Add debug breakpoints and logging
package gw.custom.debug

uses gw.api.util.Logger

class DebugHelper {
  private static final var LOG = Logger.forCategory("DebugHelper")

  // Debug method entry/exit
  static function trace<T>(methodName : String, block() : T) : T {
    LOG.debug(">>> Entering ${methodName}")
    var startTime = System.currentTimeMillis()
    try {
      var result = block()
      LOG.debug("<<< Exiting ${methodName} (${System.currentTimeMillis() - startTime}ms)")
      return result
    } catch (e : Exception) {
      LOG.error("!!! Exception in ${methodName}: ${e.Message}", e)
      throw e
    }
  }

  // Dump entity state
  static function dumpEntity(entity : KeyableBean) {
    LOG.debug("=== Entity Dump: ${entity.IntrinsicType.Name} ===")
    LOG.debug("  ID: ${entity.ID}")
    LOG.debug("  PublicID: ${entity.PublicID}")

    entity.IntrinsicType.TypeInfo.Properties
      .where(\p -> !p.Name.startsWith("_"))
      .each(\prop -> {
        try {
          var value = prop.Accessor.getValue(entity)
          LOG.debug("  ${prop.Name}: ${value}")
        } catch (e : Exception) {
          LOG.debug("  ${prop.Name}: <error reading>")
        }
      })
  }

  // Debug query execution
  static function debugQuery<T>(query : Query<T>) : List<T> {
    LOG.debug("Query: ${query.toString()}")
    var startTime = System.currentTimeMillis()
    var results = query.select().toList()
    var elapsed = System.currentTimeMillis() - startTime
    LOG.debug("Query returned ${results.Count} rows in ${elapsed}ms")
    return results
  }
}

Step 3: Remote Debugging Setup

# Start server with debug port
export JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
./gradlew runServer

# In IntelliJ: Run > Edit Configurations > Remote JVM Debug
# Host: localhost
# Port: 5005
# Module classpath: your-project

Step 4: API Request Tracing

// Add request/response logging
import axios, { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse } from 'axios';

function createDebugClient(): AxiosInstance {
  const client = axios.create({
    baseURL: process.env.POLICYCENTER_URL,
    timeout: 30000
  });

  // Request interceptor
  client.interceptors.request.use((config: InternalAxiosRequestConfig) => {
    const requestId = crypto.randomUUID();
    config.headers['X-Request-ID'] = requestId;

    console.log(`[${requestId}] >>> ${config.method?.toUpperCase()} ${config.url}`);
    if (config.data) {
      console.log(`[${requestId}] Request body:`, JSON.stringify(config.data, null, 2));
    }

    (config as any).metadata = { startTime: Date.now(), requestId };
    return config;
  });

  // Response interceptor
  client.interceptors.response.use(
    (response: AxiosResponse) => {
      const metadata = (response.config as any).metadata;
      const elapsed = Date.now() - metadata.startTime;
      const traceId = response.headers['x-gw-trace-id'];

      console.log(`[${metadata.requestId}] <<< ${response.status} (${elapsed}ms) trace=${traceId}`);
      console.log(`[${metadata.requestId}] Response:`, JSON.stringify(response.data, null, 2));

      return response;
    },
    (error) => {
      const metadata = (error.config as any)?.metadata;
      console.error(`[${metadata?.requestId}] !!! Error:`, error.response?.data || error.message);
      throw error;
    }
  );

  return client;
}

Step 5: Cloud Console Log Analysis

# View real-time logs in Guidewire Cloud Console
# Navigate to: Observability > Logs

# Common log queries (Lucene syntax)
# Find errors for a specific claim
claimNumber:"CLM-001234" AND level:ERROR

# Find slow API calls (>5 seconds)
message:"API call completed" AND duration:[5000 TO *]

# Find authentication failures
category:"Authentication" AND level:WARN

# Find integration errors
category:"gw.integration*" AND level:ERROR

# Download logs via API
curl -X GET "https://your-tenant.cloud.guidewire.com/api/v1/logs" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d "from=2024-01-15T00:00:00Z" \
  -d "to=2024-01-15T23:59:59Z" \
  -d "filter=level:ERROR" \
  -o error-logs.json

Step 6: Database Query Analysis

// Analyze slow queries
uses gw.api.database.Query
uses gw.api.database.QueryPlanExplainer

class QueryDebugger {

  static function explainQuery<T>(query : Query<T>) : String {
    var explainer = new QueryPlanExplainer(query)
    var plan = explainer.explain()

    LOG.debug("=== Query Execution Plan ===")
    LOG.debug("SQL: ${plan.SQL}")
    LOG.debug("Estimated Rows: ${plan.EstimatedRows}")
    LOG.debug("Index Used: ${plan.IndexUsed}")
    LOG.debug("Scan Type: ${plan.ScanType}")

    if (plan.ScanType == "FULL_TABLE_SCAN" && plan.EstimatedRows > 10000) {
      LOG.warn("WARNING: Full table scan on large table!")
    }

    return plan.toString()
  }

  // Profile query execution
  static function profileQuery<T>(name : String, query : Query<T>) : List<T> {
    var startTime = System.nanoTime()
    var results = query.select().toList()
    var elapsed = (System.nanoTime() - startTime) / 1_000_000.0

    LOG.info("Query '${name}': ${results.Count} rows in ${elapsed}ms")

    if (elapsed > 1000) {
      LOG.warn("Slow query detected: ${name}")
      explainQuery(query)
    }

    return results
  }
}

Step 7: Memory and Thread Analysis

// Monitor memory usage
class MemoryDebugger {
  static function logMemoryUsage() {
    var runtime = Runtime.getRuntime()
    var totalMB = runtime.totalMemory() / 1024 / 1024
    var freeMB = runtime.freeMemory() / 1024 / 1024
    var usedMB = totalMB - freeMB
    var maxMB = runtime.maxMemory() / 1024 / 1024

    LOG.info("Memory: used=${usedMB}MB, free=${freeMB}MB, total=${totalMB}MB, max=${maxMB}MB")

    if (usedMB > maxMB * 0.9) {
      LOG.warn("HIGH MEMORY USAGE: ${(usedMB * 100.0 / maxMB) as int}%")
    }
  }

  // Dump thread state
  static function dumpThreads() {
    LOG.info("=== Thread Dump ===")
    Thread.getAllStackTraces().each(\thread, stack -> {
      LOG.info("Thread: ${thread.Name} [${thread.State}]")
      stack.each(\frame -> {
        LOG.info("  at ${frame}")
      })
    })
  }
}

Debug Support Bundle

// Collect diagnostic information
interface DebugBundle {
  timestamp: string;
  environment: string;
  version: string;
  systemInfo: any;
  recentErrors: any[];
  configSnapshot: any;
  performanceMetrics: any;
}

async function collectDebugBundle(): Promise<DebugBundle> {
  const bundle: DebugBundle = {
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV || 'unknown',
    version: process.env.APP_VERSION || 'unknown',
    systemInfo: await getSystemInfo(),
    recentErrors: await getRecentErrors(100),
    configSnapshot: getConfigSnapshot(),
    performanceMetrics: await getPerformanceMetrics()
  };

  // Save to file
  const filename = `debug-bundle-${Date.now()}.json`;
  await fs.writeFile(filename, JSON.stringify(bundle, null, 2));
  console.log(`Debug bundle saved to ${filename}`);

  return bundle;
}

async function getSystemInfo() {
  return {
    nodeVersion: process.version,
    platform: process.platform,
    memoryUsage: process.memoryUsage(),
    uptime: process.uptime(),
    apiEndpoint: process.env.POLICYCENTER_URL
  };
}

async function getRecentErrors(limit: number) {
  // Fetch from logging service or local storage
  return [];
}

Common Debug Scenarios

Debugging Workflow Failures

// Add workflow debug hooks
class WorkflowDebugger {
  static function debugWorkflowStep(workflow : Workflow, step : WorkflowStep) {
    LOG.debug("=== Workflow Step Debug ===")
    LOG.debug("Workflow: ${workflow.Name}")
    LOG.debug("Step: ${step.Name}")
    LOG.debug("Status: ${step.Status}")

    // Check preconditions
    step.Preconditions.each(\precond -> {
      var result = precond.evaluate(workflow.Context)
      LOG.debug("Precondition '${precond.Name}': ${result}")
    })

    // Check available actions
    step.AvailableActions.each(\action -> {
      LOG.debug("Available action: ${action.Name}")
    })
  }
}

Debugging Integration Failures

// Integration debug helper
class IntegrationDebugger {
  static function debugRequest(request : RestRequest) {
    LOG.debug("=== Outbound Request ===")
    LOG.debug("URL: ${request.URL}")
    LOG.debug("Method: ${request.Method}")
    LOG.debug("Headers:")
    request.Headers.each(\name, value -> {
      // Mask sensitive headers
      var displayValue = name.toLowerCase().contains("auth") ? "***" : value
      LOG.debug("  ${name}: ${displayValue}")
    })
    LOG.debug("Body: ${request.Body}")
  }

  static function debugResponse(response : RestResponse) {
    LOG.debug("=== Inbound Response ===")
    LOG.debug("Status: ${response.StatusCode}")
    LOG.debug("Headers:")
    response.Headers.each(\name, value -> {
      LOG.debug("  ${name}: ${value}")
    })
    LOG.debug("Body: ${response.Body}")
  }
}

Output

• Debug logs with trace information
• Query execution plans
• Memory and thread dumps
• Complete debug bundle for support

Resources

• Guidewire Cloud Console
• IntelliJ Debugging Guide
• Log4j2 Configuration

Next Steps

For rate limiting information, see guidewire-rate-limits.