Tools for troubleshooting and diagnostics

1. IBM Support Assistant
2. Data collection and symptom analysis
3. Manual creation of aspect-enabled JAR files
4. Portal version and history information
5. Logging and tracing
6. WCM tracing
7. Troubleshooting IBM Lotus Web Content Management Syndication

IBM Support Assistant

IBM Support Assistant (ISA) provides quick access to product, education, and support resources that can help you answer questions and resolve problems with IBM software products on our own, without needing to contact IBM Support. Different product-specific plug-ins let you customize IBM Support Assistant for the particular products you have installed. IBM Support Assistant can also collect system data, log files, and other information to help IBM Support determine the cause of a particular problem.

IBM Support Assistant is a utility to be installed on an administrator's workstation, not directly onto the portal or WCM server system itself. The memory and resource requirements for the Assistant could negatively impact the server's performance. The included portable diagnostic components are designed for minimal impact to the normal operation of a server.

We can use IBM Support Assistant to help in the following ways:

• To search through IBM and non-IBM knowledge and information sources across multiple IBM products to answer a question or solve a problem

• To find additional information through product-specific Web resources; including product and support home pages, customer news groups and forums, skills and training resources and information about troubleshooting and commonly asked questions

• To extend the ability to diagnose product-specific problems with targeted diagnostic tools available via the Support Assistant

• To simplify collection of diagnostic data to help and IBM resolve your problems (collecting either general or product/symptom-specific data)

• To help in reporting of problem incidents to IBM Support through a customized online interface, including the ability to attach the previous diagnostic data or any other information to new or existing incidents

Finally, we can use the built-in Updater facility to obtain support for additional software products and capabilities as they become available.

More information, the download package, installation instructions and the latest version of the IBM Support Assistant are available from the IBM Support Assistant Web page at www.ibm.com/software/support/isa/.

Related:

Download the IBM Support Assistant Lite for Websphere Portal
IBM Support Assistant Lite for WebSphere Portal tool User's Guide

Data collection and symptom analysis

There are two methods for collecting data and analyzing symptoms for problem determination scenarios.

• IBM Support Assistant Lite for WebSphere Portal
• Run a task to collect data, and optionally send to IBM Support

IBM Support Assistant Lite sets trace levels automatically, and performs symptom analysis.

IBM Support Assistant Lite can also create and deploy aspect-enabled JAR files to enable additional troubleshooting. After reproducing the problem, we can use IBM Support Assistant Lite to remove the aspect-enabled JAR files, replace them with the original version, and collect the LOG file. For detailed instructions, see the User Guide that comes with IBM Support Assistant Lite.

If you do not want to install IBM Support Assistant Lite, we can implement an aspect-enabled jar file manually.

IBM Support Assistant Lite

1. Download IBM Support Assistant Lite for WebSphere Portal.

2. Extract the .zip file anywhere on the portal server.

3. Go to the ISALite directory that was created when you completed the previous step.

4. To collect data...

   GUI	./runISALite.sh
   Command line	./runISALiteConsole.sh

5. Select the Problem Type.

   For example, for a portal logon problem, select...

   WebSphere Portal | Security and Administration | Portal Login Problem

6. Specify the collection file.

   The file name must include the path and .zip extension.

7. Click Collect Data and answer the remaining prompts.

   To have the tool automatically FTP the logs to IBM, choose the required FTP option when prompted.

   To manually FTP the results, follow the instructions in "Exchanging information with IBM Technical Support for problem determination".

For detailed instructions, see the IBM Support Assistant Lite for WebSphere Portal tool User's Guide.

wpcollector tool

1. If the support team has requested tracing, enable it now as instructed and then re-create the problem. If no tracing is requested, skip to the next step.

2. Collect data:
   cd WP_PROFILE/PortalServer/bin/
   ./wpcollector.sh

   Run wpcollector from WP_PROFILE/PortalServer/bin/. If run from a different directory, the task fails.

   The wpcollector script can automatically FTP the logs to IBM so that you dont need to manually transfer them. To begin the collection and FTP the results to IBM correctly, identify the collection with the PMR (Problem Management Record) number...

   -Dpmr=pmr_number

   Format the number using either periods or commas.

   wpcollector.sh -Dpmr=12345.xxx.000

   To collect files for the dmgr profile, use the parameter...

   -Ddmgr.root=dmgr_root

   ...either alone or in conjunction with...

   -Dpmr=pmr_number

3. To manually FTP the results, follow the instructions in "Exchanging information with IBM Technical Support for problem determination", and ftp either...
   wp.mustgather.zip file
   pmr-wp.mustgather-timestamp.zip

   ...in...

   WP_PROFILE/filesForAutoPD/

If you try to extract the wp.mustgather.zip file, some collections might not expand properly if the path name exceeds the 256 character limitation.

Manual creation of aspect-enabled JAR files

IBM Support Assistant Lite is the preferred way to create and deploy aspect-enabled JAR files for troubleshooting because the tool automates the process for you. If you do not want to install IBM Support Assistant Lite, or we are running on a platforthat does not support IBM Support Assistant Lite, we can manually create our own aspect-enabled JAR files using either the aspect source file that ship with IBM WebSphere Portal, or aspect source files provided by IBM Support.

1. Set up AspectJ as follows:

   1. Download the latest version of AspectJ from the Eclipse Web site.

   2. To install AspectJ:
      java -jar aspect_enabled_jar_filename

2. Make the following changes:

   1. Set the CLASSPATH environment variable to include Aspect-Home\aspectjrt.jar where Aspect-Home is the directory where you installed AspectJ.

   2. Set the PATH environment variable to include Aspect-Home\bin.

   3. Modify the AspectJ compiler batch file Aspect-Home\bin\ajc.bat to use -Xmx1500M instead of -XmX64M.

3. To create an aspect-enabled JAR file on a single line:

   ajc -inpath full path to jar file  \
       -sourceroots /path/to/aspect_source_file_dir  \
       -extdirs /path/to/target/dir \
       -outjar aspect_enabled_jar_file \
   

   Contact IBM Support for the values that specify for -inpath, -sourceroots, -extdirs, and -outjar.

4. To implement an aspect-enabled JAR file:

   1. Go to the directory containing the JAR file to replace.

   2. Copy the JAR file to a backup location.

   3. Replace the specified JAR file with the aspect-enabled version.

5. Restart the server.

6. Set any necessary trace levels.

7. Reproduce the problem to troubleshoot.

8. Collect the LOG files.

9. Replace the aspect-enabled JAR file with the backup copy of the original JAR file.

10. Reset the trace levels.

11. Restart the server.

Related
Data collection and symptom analysis for z/OS
Download the IBM Support Assistant Lite for Websphere Portal
Self-Help Central for WebSphere Portal
Eclipse AspectJ downloads site

Portal version and history information

We can use the IBM WebSphere Portal version and history information tools to gather information about the portal installation. This information can be useful when you need a snapshot of the portal installation specifics, for example when you contact customer support. This information is automatically included in the automated data collection that is available when we use the IBM Support Assistant Lite for WebSphere Portal.

Version information

The portal version information tool is located in the following directory:

WP_PROFILE/PortalServer/bin

Invoke the tool...

./WPVersionInfo.sh

We can also generate a report in html format by executing the genVersionReport tool

./genVersionReport.sh

History information

The History information tool can be used to gather installation history for the WebSphere Portal product. The History information tool is located in the following directory:

WP_PROFILE/PortalServer/bin

The History information tool can be invoked using the following:

./WPHistoryInfo.sh

We can also generate a report in HTML format by executing the genHistoryReport tool:

./genHistoryReport.sh

Logging and tracing

If portal is experiencing issues, enable tracing and then re-create the problem to create verbose log output.

Refer to the MustGather data collection lists used in troubleshooting various problems in WebSphere Portal and IBM WCM.

We can use the IBM Support Assistant Lite for WebSphere Portal to automate the collection of the diagnostic data.

1. How do I turn on WebSphere Portal trace logging?
2. WebSphere Portal run-time logs
3. Change the log file name and location
4. Installation and migration logs
5. WebSphere Portal run-time logs
6. Verbose garbage collection in JVM logs
7. WAS tracing and log files
8. Logging and tracing in Portal Search
9. Configuration wizard log files
10. Use Virtual Member Manager tracing files
11. System event logging
12. Web Content Manager tracing files
13. Logging and tracing client side rendering

Parent: Troubleshooting
Related:
Data collection and symptom analysis for z/OS
Contact support
Collecting Data (MustGather): Read first for IBM WebSphere Portal
Self-Help Central for WebSphere Portal
Exchanging information with IBM Technical Support for problem determination