Enabling Tracing

The IBM Application Gateway (IAG) provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.
Trace data is intended primarily for use by IBM Software Support. Trace data might be requested as part of diagnosing a reported problem. However, experienced product administrators can use trace data to diagnose and correct problems in an IAG environment.

🚧

Note

Use trace with caution. It is intended as a tool to use under the direction of IBM Software Support. Messages from tracing are sometimes cryptic, are not translated, and can severely degrade system performance.

Trace logs are best suited to situations where a problem is easily reproduced, is short-lived in duration, and can be reproduced without significant trace generation from other system activity. Enabling tracing can adversely affect the performance of the IAG.

Configuration

In order to enable tracing the settings must be added to the IAG configuration YAML file in the logging tracing node. The configuration options are detailed in the YAML reference documentation: Tracing.

Example

An example configuration to enable tracing is provided below:

logging:
  tracing:
    - file_name: /var/iag/trace.log
      component: pdweb.debug
      level: 9
    - file_name: /var/iag/trace.log
      component: pdweb.http.transformation
      level: 5

Components

NameDescription
iag.aznUsed to trace the IAG authorization decisions.
iag.statsdUsed to trace statistical events which are sent to a statsd server.
pdweb.authnUsed to trace the IAG authentication activity.
pdweb.debugUsed to trace the HTTP headers sent between the IAG and the client. Caution: This trace could contain sensitive information.
pdweb.doccacheUsed to trace the IAG document caching activity.
pdweb.drainsUsed to trace the IAG activity for the normal closing of Internet Explorer browsers (where the 'user-agent' header contains "MSIE") sockets.
pdweb.filterUsed to trace all IAG filter activity.
pdweb.filter.snippetUsed to trace the IAG snippet filter activity.
pdweb.httpUsed to trace the IAG HTTP communication.
pdweb.http.corsUsed to trace the IAG CORS activity.
pdweb.http.ratelimitUsed to trace the IAG HTTP rate limiting activity.
pdweb.http2statsUsed to trace the IAG HTTP statistics activity.
pdweb.http.transformationUsed to trace HTTP transformation processing. Caution: This component traces the header information in the request, which might contain sensitive information.
pdweb.httpsUsed to trace the IAG HTTPS communication.
pdweb.http2.clientUsed to trace HTTP/2 client connections.
pdweb.http2.jctUsed to trace HTTP/2 resource server connections.
pdweb.sescacheUsed to trace the IAG session cache activity.
pdweb.snoopUsed to trace all HTTP packets that are sent to or from the IAG. This component logs the HTTP headers and the message body for requests and responses. Caution: This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information.
pdweb.snoop.clientUsed to trace the HTTP packets that are transmitted between the IAG and the client. Caution: This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information.
pdweb.snoop.jctUsed to trace the HTTP packets that are transmitted between the IAG and the back-end resource servers. Caution: This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information.
pdweb.snoop.oidcUsed to trace the HTTP OIDC activity. Caution: This trace could contain sensitive information.
pdweb.threadUsed to trace the IAG thread activity.
pdweb.threadsUsed to trace the IAG worker thread activity.
pdweb.usersessidcacheUsed to trace the IAG user session ID cache activity.
pdweb.urlUsed to trace the creation and parsing of the URL.
pdweb.wan.cacheUsed to trace the caching activity between the IAG and the back-end resource servers.
pdweb.wan.eaiUsed to trace the external authentication processing.
pdweb.wan.generalUsed to trace the general activity between the IAG and the back-end resource servers.
pdweb.wan.httpUsed to trace the HTTP communication between the IAG and the back-end resource servers.
pdweb.wan.serverUsed to trace the IAG HTTP server activity.
pdweb.wan.sslUsed to trace the SSL connection between the IAG and the back-end resource servers.
pdweb.websocketUsed to trace the IAG WebSocket communication.
pdweb.wns.authnUsed to trace the authentication processing.
pdweb.wns.compressUsed to trace the IAG compression of HTTP messages.
pdweb.wns.sessionUsed to trace the IAG sessions, as they are stored within the session cache and retrieved or removed from the session cache.
pdweb.wns.templatesUsed to trace the IAG template activity.