Agent Builder Troubleshooting Guide Chapter 1
Total Page:16
File Type:pdf, Size:1020Kb
IBM Agent Builder Version 6.3.1 Troubleshooting Guide IBM Agent Builder Version 6.3.1 Troubleshooting Guide ii Agent Builder Troubleshooting Guide Chapter 1. Gathering product information for IBM Software Support Gather certain product information before you contact IBM® Software Support. About this task Gather the product information that is detailed in: Table 1. Procedure Gather the following information before you contact IBM Software Support: Table 1. Information to gather before you contact IBM Software Support Information type Description Log files Collect trace log files from failing systems. Most logs are in a logs subdirectory on the host computer. See Chapter 2, “Agent Builder Trace logging,” on page 3 for lists of all trace log files and their locations. Operating system Operating system version number and patch level Messages Messages and other information that is displayed on the screen Version numbers for an IBM Tivoli® Monitoring environment Version number of the following members of the monitoring environment v Tivoli Monitoring. Also, provide the patch level, if available. v Tivoli Monitoring: Windows OS Agent v Tivoli Monitoring: UNIX OS Agent v Tivoli Monitoring: Linux OS Agent Version numbers for an IBM Performance Management Version number of the following members of the environment monitoring environment v Operating System agent installed on the monitored system. v Monitoring Infrastructure Node (if installed on your premises). Tip: If you are using IBM Performance Management (SaaS), you do not install the Monitoring Infrastructure Node on your premises. Instead, a version hosted in the cloud is used. In this case, you do not need to provide the version number for this component. Screen captures Screen captures of incorrect output, if any itm_agent_toolkit.xml file When an agent exhibits a problem, send a small non-confidential agent .xml file of a special case or sample test scenario that illustrates the problem. © Copyright IBM Corp. 2010, 2015 1 2 Agent Builder Troubleshooting Guide Chapter 2. Agent Builder Trace logging Trace logging is built into the software to assist IBM Software Support in gathering information to determine why a problem is occurring. Note: Trace logs contain detailed internal information and require an internal understanding. These logs are for use only by IBM Software Support. If you encounter an issue, IBM Software Support might request that you obtain the trace logs, to review the information. Here Trace logging is introduced with an explanation on how to locate the appropriate files. Trace logging captures information about the operating environment when the code fails to operate as intended. The IBM Agent Builder supports tracing through the Java™ Logging (JLog) Toolkit. The trace logger is configurable through the Eclipse plug-in preferences. For more information about configuration of the Trace logging, see (“Logging configuration” on page 5). Agent Builder Trace logging overview Trace logs capture information about the operating environment when component code fails to operate as intended. These logs are in the English language only. IBM Software Support uses the information that is captured by trace loggers to trace a problem to its source or to determine why an error occurred. Generally, this information is not enabled by default, but logging can be enabled without stopping the application. Trace log location Trace logging is kept in a configurable number of rotating log files. The log file names follow the format traceKQZ.log, traceKQZ1.log... where traceKQZ.log is the most recent log file. You can retrieve trace logs in the following location: workspace_directory/.metadata/tivoli/KQZ/logs Where: workspace_directory Identifies the workspace directory that you specified when you initially ran the Agent Builder. To save the log data, you must select the Enable Trace logging to files option on the Output page of the Tivoli Monitoring Agent Builder preferences. For information about the Output page, see (“Customize trace file settings” on page 6). Trace log format The trace log record format is as follows: [Date]-Level-Server-Thread-FileName.Method-LogText Exception(StackTrace) Where: © Copyright IBM Corp. 2010, 2015 3 Date Time the log was produced specified in milliseconds, since January 1st 1970, for example, 1015343592000. Server host name on which the program is running. Level The level of detail the trace represents, which can be one of the following options: ERROR error message. WARN Warning. INFO Informational message. MIN The minimum level of tracing provides some information about the program state with only a minimal affect on the performance of the program. MID The medium level of tracing follows the paths of some high-level APIs and their parameters. MAX The maximum level of tracing follows the paths of most of the code and provide a detailed program flow. This level includes minimum and medium levels of tracing as well. For more information about setting these levels, see (“Configuration by using the IBM Java Logging Toolkit” on page 5). FileName Name of the file or class to which the trace refers. Method The method in the class to which the trace refers. Thread Thread to which the trace refers. Thread element that refers to the operating system-specific notion of a thread. LogText A description of the error Exception Exception element depends upon the specific language or platform. For Java, it is a stack trace. Trace log example The following text shows an example of a trace that is recorded in the trace log: [2007-08-17T17:50:17.527-04:00] - MIN - myhost - main - AgentXMLDocument.parseAgent - begin parsing document Where: 2007-08-17 Specifies the date that the log entry was produced. 17:50:17.527 Specifies the time that the log entry was produced. 4 Agent Builder Troubleshooting Guide -04:00 Specifies the Coordinated Universal Time offset. MIN Specifies the level of detail the trace entry represents, in this case, minimum debug level. myhost Specifies the host name of the system that produced the trace entry. main Specifies name of the thread to which the trace entry refers. AgentXMLDocument Specifies name of the file or class to which the trace refers. parseAgent Specifies the method in the class to which the trace refers. begin parsing document Specifies the description of the condition or error. Logging configuration You can configure logging on components of the Tivoli Monitoring Agent Builder. About this task IBM Agent Builder logging options can be configured after installation. If you are experiencing problems, IBM Software Support might request that you configure logging and tracing information. The following steps explain how to configure the product to provide logging data. Configuration by using the IBM Java Logging Toolkit You can configure trace logs by using the IBM Java Logging Toolkit to set the trace level for the appropriate component of the Tivoli Monitoring Agent Builder. About this task You can do all logging configuration in the IBM Java Logging Toolkit. Access the Eclipse preference window by using the following steps: Procedure 1. Select Window > Preferences to display the Window toolbar menu. 2. Click IBM Java Logging Toolkit to display the IBM Java Logging Toolkit window. The Logger Configuration table displays the trace configuration for the following components: JLog IBM Tivoli Monitoring Logger Trace Logger KQZGeneratorTrace IBM Tivoli Monitoring Generator Trace Logger KQZTrace IBM Tivoli Monitoring Agent Builder Trace Logger The trace level for each component can be set independently to one of the following values. Selecting a trace level causes trace entries of that level and all higher levels to be included in the log file. v Error - error messages. v Warning - Warnings. v Information - Informational messages. Chapter 2. Agent Builder Trace logging 5 v Minimum - The Minimum level of tracing provides some information about the program state with only a minimal affect on the performance of the program. v Medium - The Medium level of tracing follows the paths of some high-level APIs and their parameters. v Maximum - The Maximum level of tracing follows the paths of most of the code and provide a detailed program flow. Logging for each component can also be enabled or disabled by selecting On or Off for Logging. 3. By expanding the IBM Java Logging Toolkit, you can set the following Trace Attributes for each component: v Log file Directory v Maximum number of revolving trace files v Maximum size of each trace file (in KB) v Enable trace logging to files v Enable trace logging to console v Restore Defaults Customize trace file settings Use the appropriate output windows to customize the trace file settings. About this task Access the Eclipse output page by doing the following steps: Procedure 1. Click Window to display the Window toolbar menu. 2. Click Preferences to display the Preferences window. 3. Click the plus sign next to the IBM Java Logging Toolkit to display the output windows. 4. Click the appropriate output window to display the output settings for that component. The window displays the following information: Log file directory Specifies the location of the log file directory. Maximum number of revolving trace files Specifies the number of trace files that are used and reused to store the trace data. Maximum size of each trace file (in Kilobytes) Specifies the maximum size in KB for each of the revolving trace files. Enable trace logging to files Check this box to store the trace log data. Enable logging to console Check this box to send logging information to a development console. Note: If you enable this option, you must restart the IBM Agent Builder as described in the following procedure: a. Close the IBM Agent Builder. b. Modify the install_dir/agentbuilder.ini file. v On Windows systems, change install_dir/_jre/jre/bin/javaw.exe to install_dir/_jre/jre/bin/java.exe. v On Linux or AIX® systems, change install_dir/_jre/jre/bin/javaw to install_dir/_jre/jre/bin/java.