Enabling Statistics Gathering

IBM Application Gateway (IAG) provides a series of built-in software modules that, when enabled, can monitor specific server activity and collect information about those activities. This statistical information is periodically sent to a remote statsd server over UDP.

The information gathered by IAG statistics provides a relative view of the activity being recorded. If statistics are captured at regular intervals over a period of time, you can generate a graphical view of the relative relationship of the server activities.

Configuration

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

Example

An example configuration to enable statistics gathering is provided below:

logging:
  statistics:
    server: 127.0.0.1
    port: 8125
    frequency: 10
    components:
      - iag.https
      - iag.resource_servers

Components

iag.authn

The iag.authn statistics component gathers information related to IAG authentication. The following table describes the statistical information available:

NameDescriptionType
iag.authn.passThe total number of successful authentications.Counter
iag.authn.failThe total number of failed authentications.Counter
iag.authn.timeThe time that it took to process an authentication operation.Timer

iag.https

The iag.https statistics component gathers information about IAG HTTPS communication. The following table describes the statistical information available:

NameDescriptionType
iag.http.reqsThe total number of HTTPS requests received.Counter
iag.http.worker.timeThe time that is used by a single worker thread to process a HTTPS request.Timer
iag.http.process.timeThe time that is used to process a single HTTPS request - measured inside the worker thread, after the request headers are read, and eliminating connection setup overhead.Timer

iag.http2

The iag.http2stats statistics component gathers information about IAG HTTP/2 communication. The following table describes the statistical information available:

NameDescriptionType
iag.http2.browser_total_connectionsThe total number of HTTP/2 requests received.Counter
iag.http2.browser_current_connectionsThe number of active HTTP/2 connections.Gauge
iag.http2.application_total_connectionsThe total number of requests sent to HTTP/2 resource servers.Counter
iag.http2.application_current_connectionsThe number of active HTTP/2 connections to resource servers.Gauge
iag.http2.browser_total_streamsThe total number of HTTP/2 streams created.Counter
iag.http2.browser_current_streamsNumber of active HTTP/2 streams.Gauge
iag.http2.application_total_streamsTotal number of streams sent to HTTP/2 resource servers.Counter
iag.http2.application_current_streamsCurrent active streams over HTTP/2 resource servers.Gauge
iag.http2.browser_idle_timeoutsNumber of HTTP/2 client connections closed due to idle timeout.Counter
iag.http2.browser_full_timeoutsNumber of HTTP/2 client connections closed due to session timeout.Counter
iag.http2.browser_exceeded_max_connectionsNumber of HTTP/2 client connections closed due to exceeding max connections.Counter
iag.http2.browser_stream_read_timeoutsNumber of HTTP/2 client connections closed waiting on a response.Counter
iag.http2.application_stream_read_timeoutsNumber of HTTP/2 resource server connections closed waiting on a response.Counter

iag.redis

The iag.redis statistics component gathers information related to IAG communication with Redis servers for remote session storage. The following table describes the statistical information available:

NameDescriptionType
iag.redis..timeThe time that is consumed by a single request to this collection of replicated Redis servers.Timer
iag.redis..reqsThe total number of requests which have been set to this collection of replicated Redis servers.Counter

iag.resource_servers

The iag.resource_servers statistics component gathers information about configured resource servers. The following table describes the statistical information available:

NameDescriptionType
iag.rs.<rs-id>.reqsThe total number of requests that are routed to this resource server.Counter
iag.rs.<rs-id>.timeThe time that is consumed by a single request to this resource server.Timer

The <rs-id> component of the statistic name will match the name of the hosting resource server, where the ':' character in the name is replaced with '_'. For path based resource servers this will correspond to the configured 'path', and for virtual host based resource servers this will correspond to the configured 'host'.

iag.sescache

The iag.sescache statistics component gathers information related to the IAG session cache activity. The following table describes the statistical information available:

NameDescriptionType
iag.sescache.hitThe number of requests that resulted in a session cache hit - that is, the user had a session cache entry and it was successfully referenced.Counter
iag.sescache.missThe number of requests that missed a session cache hit.Counter
iag.sescache.addThe number of entries that have been added to the session cache.Counter
iag.sescache.delThe number of entries that have been deleted from the cache.Counter
iag.sescache.inactiveThe number of entries removed from the cache because the inactivity timeout value had expired.Counter
iag.sescache.lifetimeThe number of entries removed from the cache because the lifetime timeout value had expired.Counter
iag.sescache.lru_expiredThe number of times a "Least Recently Used" cache entry is expired or removed to make room for a new entry.Counter

iag.threads

The iag.threads statistics component gathers information about IAG worker thread activity. It reports the overall thread usage statistics that include not just request traffic, but all of the worker threads for the IAG process. The following table describes the statistical information available:

NameDescriptionType
iag.threads.activeThe total number of active worker threads that are handling requests.Gauge
iag.threads.totalThe total number of worker threads that are configured.Gauge

iag.websocket

The iag.websocket statistics component gathers information related to IAG WebSocket communication. The following table describes the statistical information available:

NameDescriptionType
iag.websocket.requestsTotal WebSocket proxy requests received.Counter
iag.websocket.rejectedTotal WebSocket proxy requests rejected.Counter
iag.websocket.timeoutsThe number of timeouts that have occurred when reading or writing through a proxied WebSocket connection.Counter
iag.websocket.activeThe current number of WebSocket connections that are proxied.Gauge
iag.websocket.client_bytesThe number of bytes read from the client side.Counter
iag.websocket.application_bytesThe number of bytes read from the resource server.Counter

Example Output

Example 'statsd' output is shown below:

iag.authn.pass:2|c
iag.authn.time:392.5|ms|@0.5
iag.https.reqs:8|c
iag.https.worker.time:587.625|ms|@0.125
iag.https.process.time:99|ms|@0.125
iag.rs./.reqs:5|c
iag.rs./.time:0.4|ms|@0.2
iag.https.reqs:8|c
iag.https.worker.time:492|ms|@0.125
iag.https.process.time:1.5|ms|@0.125
iag.rs./.reqs:2|c
iag.rs./.time:1.5|ms|@0.5

Please note that the protocol supports sending multiple metrics in a single packet by separating the metrics with a newline (\n) character. When using this method, it is important that the packet size does not exceed the Maximum Transmission Unit (MTU) of any single machine in the network traversal path. For this reason, an MTU size of 512 will be assumed, and a single packet will never exceed this length.