Collecting troubleshooting data with diagnostic plans

Use diagnostic plans to help diagnose intermittent or long-lasting problems in WebSphere® Application Server. With a properly configured diagnostic plan, an application server can respond automatically to an anticipated problem and produce the wanted traces and Java dumps.

About this task

Administrators of the product must capture diagnostic data when a problem occurs. Diagnostic data can be logs, trace files, Java dumps, or other data, depending on the problem. IBM support often requires you to collect diagnostic data to assist in problem resolution. If the problem you are diagnosing occurs infrequently and unpredictably, it can be difficult to collect diagnostic data at the correct time. If data is not collected soon after the problem occurs, the log or trace files can roll over, resulting in loss of the needed diagnostic data.

Rather than wait for the problem to occur and capture the debugging data manually, diagnostic plans enable you to configure the application server to automatically respond to an anticipated problem and capture the needed diagnostic data.

Diagnostic plans are useful for diagnosing the intermittent issue or issues that take a long time to reproduce because they don't require manual monitoring of the server status. Diagnostic plans also can reduce the possibility of missing the time window to collect diagnostic data when the anticipated problem eventually occurs.

To use diagnostic plans, identify one or more log entries, trace entries, or FFDC incidents that are emitted when the problem you are diagnosing occurs. Then, set the diagnostic plan in the problematic application server to automatically monitor for those entries or incidents and automatically collect the needed diagnostic data when the problem occurs. Use AdminControl wsadmin scripts to configure diagnostic plans and view plan status. To set or clear a diagnostic plan, use the DiagPlanManager MBean. Refer to the MBean interface documentation for details on the MBean and supported functions.

1. Ensure that the application server that is experiencing the problem is started.
2. Set and start a diagnostic plan. Run AdminControl wsadmin scripts that configure and start a diagnostic plan with the DiagPlanManager MBean.
   1. Open a command line at the app_server_root/bin directory and start the wsadmin scripting tool with Jython.

      wsadmin -lang jython

      See Starting the wsadmin scripting client using wsadmin scripting.

   2. Set the diagnostic plan for the server.

      By default, no diagnostic plan is set on a server. Each application server can run only one diagnostic plan at a time. The following examples set simple diagnostic plans for a running server.

      • Example to collect data for the WSVR0605W message

        Commands in the following example instruct the server to wait for the WSVR0605W message to be logged, then generate a Java core, wait for 6 seconds, generate a heap dump, wait for another 6 seconds, and generate another Java core.

        # Query to find the DiagnosticPlan MBean and create the objectName
        diagPlanMBean = AdminControl.queryNames('WebSphere:type=DiagPlanManager,process=server1,*')
        objName = AdminControl.makeObjectName(diagPlanMBean)
        
        # Pass the diagnostic plan string as a parameter
        parms =["MATCH=TRACE:WSVR0605W*,JAVACORE,DELAY=6,HEAPDUMP,DELAY=6,JAVACORE"]
        
        # Run the setDiagPlan method in the MBean with the diagnostic plan string
        AdminControl.invoke_jmx(objName, 'setDiagPlan', parms, ["java.lang.String"])
        

      • Example to collect data for the SRVE024I message

        Commands in the following example set the trace to use the memory buffer, set the trace specification, wait for the SRVE024I: [*]: Initialization successful message or the [connection] * successful message to be logged, then dump the trace memory buffer to a file, generate a Java core, and finally restore the trace specification to the previous state before running this diagnostic plan.

        # Query to find the TraceService MBean
        RASTraceMBean = AdminControl.queryNames('WebSphere:type=TraceService,process=server1,*')
        
        # Set the runtime trace output to Memory Buffer
        print "\nSetting the Runtime Trace Output to Memory Buffer"
        AdminControl.invoke(RASTraceMBean, "setTraceOutputToRingBuffer", [8, "Basic"])
        
        # Query to find the DiagnosticPlan MBean and create the objectName
        diagPlanMBean = AdminControl.queryNames('WebSphere:type=DiagPlanManager,process=server1,*')
        objName = AdminControl.makeObjectName(diagPlanMBean)
        
        # Pass the diagnostic plan string as a parameter
        parms =["SET_TRACESPEC=*=info:com.ibm.ws.webcontainer*=all:com.ibm.ws.jsp=all:WAS.j2c=all:Transaction=all:WAS.database=all:EJBContainer=all,
        MATCH=TRACE:SRVE0242I: [*]: Initialization successful.;TRACE:[connection] * successful,DUMPBUFFER,JAVACORE,RESTORE_TRACESPEC"]
        
        # Run the setDiagPlan method in the MBean with the diagnostic plan string.
        AdminControl.invoke_jmx(objName, 'setDiagPlan', parms, ["java.lang.String"])
        

      For information about the syntax of diagnostic plan actions, see Diagnostic plan action scripts.

3. View the status of an existing diagnostic plan. Run wsadmin scripts that use the AdminControl object to view diagnostic plan status.

   The following example runs the getDiagPlan method in the MBean to get the status of an existing diagnostic plan and then prints the results to the console.

   # Query to find the DiagnosticPlan MBean and create the objectName
   diagPlanMBean = AdminControl.queryNames('WebSphere:type=DiagPlanManager,process=server1,*')
   diagPlanObjName = AdminControl.makeObjectName(diagPlanMBean)
   
   # Run the getDiagPlan method in the Mbean
   ret = AdminControl.invoke_jmx(diagPlanObjName, 'getDiagPlan',[],[])
   
   # Display the results on the console
   print ret
   

   The resulting console output provides the status information.

   The following is the configured diagnostic plan:
   The asterisk (*) in front of the action indicates the currently running action.
   *MATCH: [
     TRACE: WSVR0605W*
   ]
   JAVACORE
   DELAY: 60
   JAVACORE
   DELAY: 60
   HEAPDUMP
   

   Tip: If the diagnostic plan does not use the default trace specification, use the memory buffer to capture trace. Writing more detailed trace information to the file can significantly reduce the performance of the server.