ShowTable of Contents
Introduction
IBM® Level 2 (L2) Support Teams are able to perform more effective and accurate triage and problem determination if detailed problem descriptions and a complete set of diagnostic data are provided when a PMR is opened. You can do this by following the best practices of using the IBM Electronic Service Request (SR), providing detailed problem descriptions, and using Automated Data Collection (ADC), to provide a complete set of diagnostic data.
Prerequisites
It is assumed that you have the following installed and available:
- IBM WebSphere® Portal Server 7.0
- IBM Support Assistant 5.0
You also need the the files below, which are provided in the .zip file attached to this article:
- “Start SR Viewlet” shortcut
- “ConfigTrace.log”
Objectives
In this article you will:
- Watch a viewlet that walks through the steps of opening a PMR with SR.
- Learn about the automated data collection options and perform an ADC.
- Use the IBM Portal Log Analyzer tool via IBM Support Assistant (ISA) to analyze a ConfigTrace.log file.
You will understand how to access SR from a Web browser to create a PMR and perform an automated data collection. In addition, you will learn how to use ISA to launch tools such as the IBM Portal Log Analyzer and perform troubleshooting analysis.
Procedure
Step 1: Watch the SR viewlet
For this section we review a 3-minute viewlet that describes the steps on how to open a PMR with SR. To start the viewlet, extract the attached .zip file and find the “Start SR Viewlet” shortcut file. Then double-click the “Start SR Viewlet” shortcut file to launch the viewlet.
The SR Tool itself can be directly accessed via the
IBM Service Request sign in page.
After watching the viewlet you have completed Step 1. Now continue to Step 2.
Step 2: Perform an automated data collection
Next we perform an automated data collection. Refer to the IBM
Support Technote #1444911, “
Collecting Data: Read First for WebSphere Portal 7.0,” for information on the ADC options available for WebSphere Portal.
Currently WebSphere Portal has two ADC options available:
- ISALite. A download tool that provides robust automated data collection capabilities, including setting required traces from within the tool.
- Wpcollector. Less features than ISALite, but it's included in the product and immediately available after product install.
It is recommended to become familiar with both collection procedures; either one may be requested based on the particular situation.
Running ISALite: Access the
ISALite viewlet and follow along on your WebSphere Portal environment to perform an automated data collection using the ISALite tool.
Running wpcollector: Using the instructions in Support Technote #1445430, “
Wpcollector tool, new in WebSphere Portal 7.0 provides automated data collection capability,” perform an automated data collection using the wpcollector tool.
This completes Step 2. Now continue to Step 3.
Step 3: Use ISA to access tools such as the IBM Portal Log Analyzer
If you do not have ISA already installed, first you need to download and install ISA. To do this, go to Techdoc #7023689, “
IBM Support Assistant 5.0 Tech Preview,” and click the Download Now button.
After downloading the ISA .zip file, getting started is as simple as extracting the file, running the start_isa.bat or start_isa.sh file, and opening a browser to http://<hostname>:8080/isa5. Refer to he ReleaseNotes.txt file in the .zip file for more details.
We now use ISA to launch tools that can help troubleshoot problems. In this case, we show how to use the IBM Portal Log Analyzer tool to help resolve problems with WebSphere Portal Configuration task failures.
1. Once ISA is available in the browser, begin by clicking the Tools tab within the ISA interface (see figure 1).
Figure 1. Tools tab
2. The list of available tools displays. If you click “IBM Portal Log Analyzer,” you will see the description of the tool display in the main workspace (see figure 2). Here you can find out more about the tool, its intended purpose, and how to use it.
Figure 2. IBM Portal Log Analyzer description
3. Create a new case by clicking the Cases button. For the purposes of this document we created a case called “Lotusphere Serviceability Lab”. Once the case is created, ensure it is selected in the drop-down list, as shown in figure 3.
Figure 3. Lotusphere Serviceability Lab case
4. Next, add the ConfigTrace.log file provided in the .zip file by clicking the Add Files button, or by simply dragging and dropping the file onto the dotted square.
5. After loading the case with the file, select the Files tab, and click the support_files folder under the Navigator window; you should see the ConfigTrace.log file display in the main workspace (see figure 4).
Figure 4. ConfigTrace.log file
6. Right-click on the ConfigTrace.log to bring up the Actions menu, expand “Problem Analysis,” and then select “IBM Portal Log Analyzer” (see figure 5).
Figure 5. IBM Portal Log Analyzer selected
7. This action should bring up a new Problem Analysis window in which you should see the path to the file to be analyzed; click Submit (see figure 6).
Figure 6. Problem Analysis window
8. After clicking Submit, you are presented with another pop-up window that shows the location of the output directory for the analysis; click OK (see figure 7).
Figure 7. Location of output directory
Now we actually access the viewer that was created by the execution of the tool to review the analysis:
- Expand the support_files directory to find the newly created sub-directory called “ConfigTrace.log-portalloganalyzer_ISA_PD”.
- Click on the “ConfigTrace.log-portalloganalyzer_ISA_PD” directory; you should see files appear in the main workspace.
- Double-click the ConfigTrace_portalloganalyzer.html file to launch the viewer (see figure 8).
Figure 8. ConfigTrace_portalloganalyzer.html file
The viewer opens in another browser tab and look like that shown in figure 9.
Figure 9. Viewer open in another browser
Once in the viewer you can begin to use it to perform analysis on the ConfigTrace.log, to understand more about your WebSphere Portal configuration history and configuration task failures.
This completes Step 3. Leave the IBM Portal Log Analyzer open and continue to Step 4.
Step 4: Using IBM Portal Log Analyzer to troubleshoot Configuration task issues
The IBM Portal Log Analyzer tool makes it easier to review and navigate through a Portal ConfigTrace.log. The ConfigTrace.log contains the entire history of all Configuration tasks that have been run on a Portal environment.
Running Configuration tasks is commonplace in all Portal environments; therefore it is also common to have problems in this area of Portal administration. When problems occur you need to review the ConfigTrace.log file to understand the nature of the problem and begin to correct it.
Parsing through a very large text file like the ConfigTrace.log to find the problem can often be time consuming and challenging---this is where the Portal Log Analyzer can help.
The Portal Log Analyzer is designed to make it much easier to review a ConfigTrace.log by automatically parsing through the file and presenting the contents of the file in a more structured and easier-to-consume way. Let's take a closer look at the Portal Log Analyzer.
In Step 3 you launched the IBM Portal Log Analyzer and probably noticed that the UI was divided into three panels. Each of the three panels in the viewer serves a different purpose. Let's begin by describing the purpose of each panel.
Left-hand panel. The left-hand panel contains a historical list of all configuration tasks performed on this Portal environment that are contained in the ConfigTrace.log. You can expand each parent task to see the sub-tasks that comprise it. The green check marks indicate a task that completed successfully, while the red X indicates a task that failed (see figure 10).
Figure 10. Left-hand Log Analyzer UI expanded
Middle panel. The middle panel displays the contents of the Configuration task that were selected in the left-hand panel and highlights error conditions in red, to make them easier to spot (see figure 11).
Figure 11. Middle panel
Right-hand panel. The right-hand panel displays the configuration properties and the values of those properties that were used for the execution of the Configuration task selected in the left-hand panel.
Many times a configuration task failure is caused by an incorrect property value. You can search for the value of a particular property used by the Configuration task by using the type-ahead-enabled Filter text box (see figure 12).
Figure 12. Right-hand panel
A typical use case would be as follows (see figure 13):
- Identify a problem task in the left-hand panel as indicated by the red X.
- Click on the parent task to reveal the task details in the middle panel. Notice that the middle panel takes you to the end of the logging for that task where you can easily see the “Build Failed” message and the errors that occurred to cause the build to fail.
- Once you have narrowed down the problem you can use the Filter feature in the right-hand panel to determine what property values were used for properties that may be suspect.
Figure 13. Typical use case
Feel free to return to the IBM Portal Log Analyzer and play around with the UI as described above. Once you are done, you have completed Step 4. Continue to Step 5.
Step 5: Putting it all together
When problems occur with our software, IBM wants to provide its customers with the best support experience possible. Achieving this desired support experience requires a working partnership between the customer and IBM.
IBM's goal is to provide software that is easy to use and with few problems. However, problems will eventually occur and, when they do, both IBM and customers benefit from the ability to solve those problems quickly and efficiently.
So when problems occur and a PMR is needed, customers should partner with us so we can help you solve the problem in the most efficient manner possible. This partnership begins with the areas we have covered in this article:
- Install and familiarize yourself with IBM Support Assistant. The tools made available to customers in ISA are the very same tools IBM Support Engineers use internally to help triage and solve customer problems.
- Use the Electronic Service Request tool to open PMRs. SR allows customers to enter a detailed problem description and even copy/paste error messages found in logs or other interesting information that may have been discovered from using tools available in ISA.
Providing detailed problem description and analysis up front is very important and is much easier to do electronically than relying on verbal dictation over the phone.
- Understand the product's Automated Data Collection mechanism and use it to provide a complete ADC at the time the PMR is opened. ADC is a vital Serviceability element to any product. ADCs make it easier for customers to provide IBM a complete set of diagnostic data and, in turn, ensures that IBM has a clear understanding of the problem from the beginning.
Take the time before a PMR is required to familiarize yourself with the product's ADC mechanism so it can be easily invoked when a PMR is needed. If you are unsure of the ADC mechanism for a particular product, ask an IBM representative like an Accelerated Value Leader or L2 Support Specialist for instruction.
Conclusion
In this article you have successfully walked through the steps to create a PMR using the SR tool. You learned about the ADC options available for WebSphere Portal and performed an automated data collection and learned how to access the same tools through ISA that the IBM internal Support teams use to troubleshoot problems.
Using this knowledge, you can effectively partner with IBM Support teams when opening a PMR so that your problems can be worked and resolved in the most efficient manner possible.
Resources
Electronic Service Request (SR):
http://www.ibm.com/support/servicerequest
IBM Support Assistant (ISA):
http://www.ibm.com/software/support/isa/
About the author
Jerry Dancy has more than 12 years of experience working with customers in a support or services capacity. He currently serves as a WebSphere Portal Server Level 2 Support Specialist and is considered a leader in the transformation and innovation of IBM's remote support and serviceability business model. Jerry has co-authored several IBM publications on the topics of operational and deployment best practices. You can reach him at
dancy@us.ibm.com.