WebSphere Application Server, often referred to simply as WAS, is a JEE-compliant application server platform. JEE stands for Java Enterprise Edition and was previously referred to as J2EE. JEE application servers provide functionality to deploy fault-tolerant, distributed, and multi-tier Java software.

In this article by Steve Robinson, author of IBM WebSphere Application Server 8.0 Administration Guide, we will be covering a few of the command-line tools shipped with WAS to help you with problem diagnosis when WebSphere or applications are not running as they should. We will also introduce the IBM Support Assistant, a very powerful WebSphere Application Server (WAS) support tool, and walk through how to analyze a WAS log file using one of the many ISA add-ons.

Specifically we will cover the following topics:

• Dumping namespaces
• EAR expander
• IBM Support Assistant (ISA)

 

(For more resources on IBM, see here.)

Dumping namespaces

To diagnose a problem, you might need to collect WAS JNDI information. WebSphere Application Server provides a utility that dumps the JNDI namespace.

The dumpNamespace.sh script dumps information about the WAS namespace and is very useful when debugging applications when JNDI errors are seen in WAS logs. You can use this utility to dump the namespace to see the JNDI tree that the WAS name server (WAS JNDI lookup service provider) is providing for applications.

This tool is very useful in JNDI problem determination, for example, when debugging incorrect JNDI resource mappings in the case where an application resource is not mapped correctly to a WAS-configured resource or the application is using direct JNDI lookups when really it should be using indirect lookups.

For this tool to work, WAS must be running when this utility is run.

To run the utility, use the following syntax:

./dumpNameSpace.sh -<command_option>

There are many options for this tool and the following table lists the command-line options available by typing the command <was_root>/dumpsnameSpace.sh -help:

Command option	Description
-host <host>	Bootstrap host, that is, the WebSphere host whose namespace you want to dump. Defaults to localhost.
-port <port>	Bootstrap port. Defaults to 2809.
-user <name>	Username for authentication if security is enabled on the server. Acts the same way as the -username keyword.
-username <name>	Username for authentication if security is enabled on the server. Acts the same way as the -user keyword.
-password <password>	Password for authentication, if security is enabled in the server.
-factory <factory>	The initial context factory to be used to get the JNDI initial context. Defaults to com.ibm.websphere.naming. WsnInitialContextFactory and normally does not need to be changed.
-root [ cell | server | node | host | legacy | tree | default ]	Scope of the namespace to dump.
For WS 5.0 or later:
cell:	DumpNameSpace default. Dump the tree starting at the cell root context.
server:	Dump the tree starting at the server root context.
node:	Dump the tree starting at the node root context. (Synonymous with host)
For WS 4.0 or later:
legacy:	DumpNameSpace default. Dump the tree starting at the legacy root context.
host:	Dump the tree starting at the bootstrap host root context. (Synonymous with node)
tree:	Dump the tree starting at the tree root context.
For all WebSphere and other name servers:
default:	Dump the tree starting at the initial context, which JNDI returns by default for that server type. This is the only -root choice that is compatible with WebSphere servers prior to 4.0 and with non-WebSphere name servers. The WebSphere initial JNDI context factory (default) obtains the desired root by specifying a key specific to the server type when requesting an initial CosNaming NamingContext reference. The default roots and the corresponding keys used for the various server types are listed as follows:

WebSphere 5.0: Server root context. This is the initial reference registered under the key of NameServiceServerRoot on the server.

• WebSphere 4.0: Legacy root context. This context is bound under the name domain/legacyRoot, in the initial context registered on the server, under the key NameService.
• WebSphere 3.5: Initial reference registered under the key of NameService, on the server.
• Non-WebSphere: Initial reference registered under the key of NameService, on the server.

-url <url> The value for the java.naming.provider.url property used to get the initial JNDI context. This option can be used in place of the -host, -port, and -root options. If the -url option is specified, the -host,-port, and -root options are ignored. -startAt <some/subcontext/ in/the/tree> The path from the requested root context to the top-level context, where the dump should begin. Recursively dumps (displays a tree-like structure) the sub-contexts of each namespace context. Defaults to empty string, that is, root context requested with the -root option. -format [ jndi | ins ] jndi: Display name components as atomic strings.
ins: Display name components parsed per INS rules (id.kind)
The default format is jndi. -report [ short | long ] short: Dumps the binding name and bound object type, which is essentially what JNDI Context. list() provides.
long: Dumps the binding name, bound object type, local object type, and string representation of the local object, that is, Interoperable Object References (IORs) string values, and so on, are printed).
The default report option is short. -traceString <some.package. to.trace.*=all> Trace string of the same format used with servers, with output going to the DumpNameSpaceTrace.out file.

Example name space dump

To see the result of using the namespace tool, navigate to the <was_root>/bin directory on your Linux server and type the following command:

• For Linux:
  

  ./dumpNameSpace.sh -root cell -report short -username wasadmin
  -password wasadmin >> /tmp/jnditree.txt

• For Windows:
  

  ./dumpNameSpace.bat -root cell -report short -username wasadmin
  -password wasadmin > c:\temp\jnditree.txt

The following screenshot shows a few segments of the contents of an example jnditree.txt file which would contain the output of the previous command.

EAR expander

Sometimes during application debugging or automated application deployment, you may need to enquire about the contents of an Enterprise Archive (EAR) file. An EAR file is made up of one or more WAR files (web applications), one or more Enterprise JavaBeans (EJBs), and there can be shared JAR files as well. Also, within each WAR file, there may be JAR files as well. The EARExpander.sh utility allows all artifacts to be fully decompressed much as expanding a TAR file.

Usage syntax:

EARExpander -ear (name of the input EAR file for the expand
operation or name of the output EAR file for the collapse operation)
-operationDir (directory to which the EAR file is expanded or
directory from which the EAR file is collapsed) -operation (expand |
collapse) [-expansionFlags (all | war)] [-verbose]

To demonstrate the utility, we will expand the HRListerEAR.ear file. Ensure that you have uploaded the HRListerEAR.ear file to a new folder called /tmp/EARExpander on your Linux server or an appropriate alternative location and run the following command:

• For Linux:
  

  <was_root>/bin/EARExpander.sh -ear /tmp/HRListerEAR.ear
  -operationDir /tmp/expanded -operation expand -expansionFlags all
  -verbose

• For Windows:
  

  <was_root>\bin\EARExpander.bat -ear c:\temp\HRListerEAR.ear
  -operationDir c:\temp\expanded -operation expand -expansionFlags
  all -verbose

The result will be an expanded on-disk structure of the contents of the entire EAR file, as shown in the following screenshot:

An example of everyday use could be that EARExpander.sh is used as part of a deployment script where an EAR file is expanded and hardcoded properties files are searched and replaced. The EAR is then re-packaged using the EARExpander -operation collapse option to recreate the EAR file once the find-and-replace routine has completed. An example of how to collapse an expanded EAR file is as follows:

• For Linux:
  

  <was_root>/bin/EARExpander.sh -ear /tmp/collapsed/HRListerEAR.ear
  -operationDir /tmp/expanded -operation collapse -expansionFlags
  all -verbose

• For Windows:
  

  <was_root>\bin\EARExpander.bat -ear c:\temp\collapsed\HRListerEAR.
  ear -operationDir c:\temp\expanded -operation collapse
  -expansionFlags all -verbose

In the previous command line examples, the folder called EARExpander contains an expanded HRListerEAR.ear file, which was created when we used the -expand command example previously.

To collapse the files back into an EAR file, use the -collapse option, as shown previously in the command line example. Collapsing the EAR folders results in a file called HRListerEAR.ear, which is created by collapsing the expanded folder contents back into a single EAR file.

IBM Support Assistant

IBM Support Assistant can help you locate technical documents and fixes, and discover the latest and most useful support resources available. IBM Support Assistant can be customized for over 350 products and over 20 tools, not just WebSphere Application Server.

The following is a list of the current features in IBM Support Assistant:

• Search Information
  • Search and filter results from a number of different websites and IBM Information Centers with just one click.
• Product Information
  • Provides you with a page full of related resources specific to the IBM software you are looking to support. It also lists the latest support news and information, such as the latest fixes, APARs, Technotes, and other support data for your IBM product.
• Find product education and training materials
  • Using this feature, you can search for online educational materials on how to use your IBM product.
• Media Viewer
  • The media viewer allows you search and find free education and training materials available on the IBM Education Assistant sites.
  • You can also watch Flash-based videos, read documentation, view slide presentations, or download for offline access.
• Automate data collection and analysis
  • Support Assistant can help you gather the relevant diagnostic information automatically so you do not have to manually locate the resources that can explain the cause of the issue.
  • With its automated data collection capabilities, ISA allows you to specify the troublesome symptom and have the relevant information automatically gathered in an archive. You can then look through this data, analyze it with the IBM Support Assistant tool, and even forward data to IBM support.
  • Generate IBM Support Assistant Lite packages for any product addon that has data collection scripts. You can then export a lightweight Java application that can easily be transferred to remote systems for remote data connection.
• Analysis and troubleshooting tools for IBM products
  • ISA contains tools that enable you to troubleshoot system problems. These include: analyzing JVM core dumps and garbage collector data, analyzing system ports, and also getting remote assistance from IBM support.
• Guided Troubleshooter
  • This feature provides a step-by-step troubleshooting wizard that can be used to help you look for logs, suggest tools, or recommend steps on fixing the problems you are experiencing.
• Remote Agent technology
  • Remote agent capabilities through the feature pack provide the ability to perform data collection and file transfer through the workbench from remote systems. Note that the Remote agents must be installed and configured with appropriate 'root-level' access.

ISA is a very detailed tool and we cannot cover every feature in this article. However, for a demonstration, we will install ISA and then update ISA with an add-on called the Log Analyzer. We will use the Log Analyzer to analyze a WAS SystemOut.log file.

Downloading the ISA workbench

To download ISA you will require your IBM user ID. The download can be found at the following URL:

http://www-01.ibm.com/software/support/isa/download.html

It is possible to download both Windows and Linux versions.

 

(For more resources on IBM, see here.)

Installing the ISA workbench

To start the ISA workbench installation run the following commands:

• For Linux:
  

  rpm -ivh support-assistant-4.1.2.00-20101123_1610.i386.rpm

• For Windows:
  

  setupwin32.exe

  In the following example, we are using a Windows installation; however, the process is almost identical for Linux, except that the installation location filepaths will be different. For Linux, the RPM installer will install ISA in the following location: /opt/ibm/ IBMSupportAssistant_4.

Follow these steps for the installation wizard:

1. Once the ISA workbench installation wizard has loaded, Click on Next and then read and accept the License Agreement on the following page. Click on Next again.
2. On the Destination folder screen, choose the location where you wish to install the ISA binaries. Click on Next to continue.
3. On the next screen, you will be given an option to choose the location of where your user data will be stored. Choose an appropriate option to suit your requirement and click on Next to continue. In our example, we have chosen to use the default location.
4. On the last screen, review your settings and click on Install to begin the installation.
5. Once the installation wizard has completed click on Finish.

Launching ISA

One you have installed ISA, you can launch the ISA workbench application using the following commands:

• For Linux:
  

  /opt/ibm/IBMSupportAssistant_41/rcp/rcplauncher

• For Windows:
  

  C:\Program Files (x86)\ibm\IBM Support Assistant v41\rcp\
  rcplauncher

When ISA loads it will present the welcome page:

The first time the ISA workbench is loaded, it will prompt to inform you that it needs to update the list of available add-ons. The update process runs as a background task to keep ISA up-to-date with available add-ons.

(Move the mouse over the image to enlarge it.)

By default, ISA is set to start the update process as a background task every time ISA is launched; however, you may wish to disable automatic updates or simply schedule updates to occur at certain times of the day. Using the File | Preferences | Updater Preferences menu, you can enable/disable updates via the Automatically find new updates and notify me checkbox option:

Adding add-on tools

ISA organizes the downloads of add-on tools, such as the Log Analyzer, Symptom Editor, Memory Analyzer, Garbage Collection and Memory Visualizer, and Dump Analyzer, to name a few, which are all very useful tools for WAS administration. There are many other tools and add-ons constantly being made available.

The following steps explain how to install the Log Analyzer:

1. Ensure you have an Internet connection as ISA will be communicating with IBM remote repositories.
2. From the workbench menu, select Update | Find New | Tools Add-ons:
   

   

3. A background task will be initiated and ISA will return with a list of the latest available add-ons from IBM.
4. When the Tool add-ons to install window appears, expand the JVM-based tools option:
   

   

5. Select Log Analyzer 4.5.0.3 (or the latest version) from the list of available tools:
   

   

   It is possible to install several tools at the same time.

6. On the License of Add-ons to install screen, read and accept the license agreement and click on Next to continue.
7. You will now be presented with a summary of the add-ons that will be installed. Click on Install.
8. After the installation has completed, you will be prompted with a screen summarizing the results of the installation operations:
   

   (Move the mouse over the image to enlarge it.)

   

9. Click on Finish to complete and you will be prompted to restart ISA. Once ISA has been restarted, you can use the Log Analyzer add-on.

Analyzing log files

Now that we have installed the Log Analyzer, we can import a WAS SystemOut.log and analyze it. In our example, we will use a local copy of SystemOut.log, which has been copied from a WAS server and is located in C:\temp.

1. To analyze a log file, click on the Analyze Problem link on the workbench welcome page:
   

   

2. From the Tools Catalog list, locate Log Analyzer and click on Launch:
   

   

3. Once the Log Analyzer has loaded, select File | Import Log from the main menu:
   

   

4. On the Import Log screen, select the Import from the local system option and click on Next:
   

   

5. On the Import from the local system screen, browse for the log file, then click on the Add button to add the log to the Logs to be imported into Log Analyzer list and click on Finish. The log will be parsed by the Log Analyzer and imported. The result will be to display the log data as a list of rows in the right-hand panel. In the following screenshot, we see example entries which you might find in a SystemOut.log file:
   

   

6. Now you have imported a log file, you can navigate through the log data as a set of rows. Note that there is a toolbar located above the main log panel, as shown in the following screenshot:
   

   

7. This toolbar allows you to change the colors of specific error severities and select columns of field data as required. It also allows you to sort columns to make it easier to navigate through the log data in a structured manner.

Loading symptom catalogs

Just viewing logs is not a useful problem analysis activity until the log is compared against a database of known symptoms and recommended solutions.

A symptom catalog contains three key types of information:

• Symptoms: Common problems or error messages
• Solutions: Reasons why the error may have occurred
• Directives or resolutions: Possible resolutions for the error

Within the example imported log as shown in the previous section, we can see that there is a CPU Starvation detected. We can import a symptom catalogue to get recommended solutions from the IBM support knowledge base.

Use the following steps as a guide to import a symptom catalog:

• Select File | Import Symptom Catalog from the main menu.
• On the Import Symptom Catalog screen, choose an appropriate symptom catalog in the From remote host list:
  

  

  In our example, we are using a WAS 7 symptom catalog as, at the time of writing, there are no WAS 8 symptom catalogs available. Symptom catalogs are continually being added and updated by IBM support on a regular basis. Symptom catalogs are still very useful, even if they are for a previous version of WAS, as many errors are generic and similar across versions.

• Click on Finish to import the symptom catalog. The symptom catalog will appear in the Log Navigator, as shown in the following screenshot:
  

  

• Right-click the SystemOut.log entry in the Log Navigator and select Analyze. The result will be a report listing solutions and recommendations for known errors. The report is located in the bottom section of the right-hand log entry panel.
• Locate the Symptom Analysis Result panel and select the symptom you are interested in to view details from IBM Support:
  

  

• In the previous example, we have selected one of the CPU Starvation symptom records. To the right of the Symptom Analysis Result panel is another panel called the Symptom Definition panel. Here, details such as recommendations and solutions are described for the selected symptom. Often, there is a URL link (within the description field) to an online IBM support page detailing the error and known solutions:
  

  

We have now completed a very simple log analysis. The ISA is a very powerful application. By demonstrating just one of the many add-ons, such as Log Analyzer, we see that the ISA is a very important administration tool.

Summary

In this article, we saw that WebSphere Application Server comes with some useful command-line tools. The dumpNameSpace.sh utility can be used to view the JNDI tree of a running application server, which is very useful in helping with debugging the root cause of application failures that involve JNDI resource lookups. Another tool we looked at was the EARExpander.sh utility, which can be used to unpack an EAR file during automated deployments, to manipulate the EAR file, and repackage it on the fly. It can also be used during problem diagnosis if the supplied EAR file has problems during deployment.

---

Further resources on this subject:

• Tuning WebSphere Security [article]
• Replication Alert Monitor: Monitoring Management [article]
• IBM WebSphere Application Server Security: A Threefold View [article]

---

About the Author :

Books From Packt

---

IBM WebSphere Application Server v7.0 Security

Application Development for IBM WebSphere Process Server 7 and Enterprise Service Bus 7

IBM Rational Team Concert 2 Essentials

Getting Started with IBM FileNet P8 Content Manager

IBM InfoSphere Replication Server and Data Event Publisher

IBM Rational ClearCase 7.0: Master the Tools That Monitor, Analyze, and Manage Software Configurations

IBM Cognos 8 Report Studio Cookbook

IBM Lotus Domino: Classic Web Application Development Techniques

---

Average: Select ratingPoorOkayGoodGreatAwesome

No votes yet