IBM Support

DataPower off-device logging: a configuration example

Technote (troubleshooting)


Problem(Abstract)

This technote gives an example of how to enable off-device logging on an IBM® WebSphere® DataPower® appliance. This can be very helpful when a debug log level is needed to help isolate a problem or monitor behavior over a long period of time or can be used in production environment as DataPower only keeps a limited number of log files (the default is 3 files) in the file system in a rotational basis.

Cause

The DataPower device has a finite amount of space to hold larger than average log files or long term logging needs in production environment.

It should be noted that if used while debugging at load or in a capacity issue, log events may be dropped. There is a prioritization of events within the device and client traffic always comes first. Log events dropped can be confirmed or counted from the Status>Log Targets menu in the WebGUI.


Resolving the problem

Configure a server daemon to listen and capture the DataPower devices events. First, this example shows how to create the log target sending events to a syslog destination. The other examples listed below will have their own strong points to be considered depending on the problem scenario.

Syslog:

* The syslog protocol operates over UDP which has no guarantee on packet delivery - a fast fire and forget method.

To create the new log target, go into the default domain: Objects > Log Targets

Configure the log target with settings as follows from the WebGUI:

  1. Name the log target
  2. Select Target Type of syslog
  3. Fill in the Local Identifier with a descriptive string that may be used by a remote recipient to identify this specific log target
  4. Enter the Remote Host Address and the Remote IP Port as in the screen shot where x.x.x.x is the IP address of the remote syslog server that listens on port 514
  5. Take all other defaults


Under the Event Subscriptions tab, you can select all and debug as indicated here:



    6. Generate log events in the DataPower by using some transactions, for example by saving the configuration from the WebGUI or running some test load into a domain.


Syslog-ng, will simply work over the TCP protocol to ensure the packet is delivered to the destination. The same consideration should be applied to a device under high load in that a log event could be dropped if not able to be wrote out to the network within time.

NFS:
All NFS limitations apply from file size and permission settings. This is a more common approach using an NFS static mount to capture a log target and can allow for slightly more reliable messages to be logged. The limiting factor again is the speed of the network and NFS server response time.

File type:

Using a file type log target with a backup method as seen here:

This will allow log events to quickly be written to a local file on the device's file system. Once the file reaches its set size a connection to the destination will upload the file from the device. This will upload with a unique time and date stamp on the uploaded file.

This is a useful method to capture sporadic problems. This is also useful for long running transactions that may span more than one file depending on device load.


HTTP service:
Finally a clever method that may be used in some senarios would be an HTTP service on the device.
Using an HTTP service configured in the following way,

Once the file type log is created in the logtemp:/// directory, a client browser or wget type client can easily retrieve the file from the device.

This is very useful when there is no local or accessible remote log storage location to the device, due to firewall or network restrictions.

This is also removing the limitation of the device dropping the log event should it not be able to write the log event to the network.

Each of the above methods are very useful and work better in some scenarios than others depending on the network, load, problem, and information needed. This is intended to be a guide to help you decide which method would be best for your scenario.

Document information

More support for: IBM DataPower Gateways

Software version: 3.8, 4.0.1, 4.0.2

Operating system(s): Firmware

Software edition: Edition Independent

Reference #: 1269136

Modified date: 03 November 2008