Apache Module mod_mpmstats

Description:	MPM/thread monitoring module for IBM HTTP Server
Status:	Extension
Module Identifier:	mpmstats_module
Source File:	mod_mpmstats.c

Summary

This module logs periodic information about IBM HTTP Server processing threads in the error log. Prior to V7R0, it was only available as part of the ihsdiag mustgather tool.

mpmstats: rdy 24 bsy 1 rd 0 wr 1 ka 0 log 0 dns 0 cls 0 ... module mod_test.c took 5000ms to return OK in phase handler ... mpmstats (long-running requests): bsy: 3 in mod_test.c

Topics

Limitations
Description of fields

Limitations

In 9.0 and later on z/OS and Linux under the event MPM, the displayed number of threads in the keepalive and close states do not represent dedicated threads. To learn more, read about the Apache MPM event.
Threads that are busy in non-module code cannot be counted with TrackModules

Description of fields

rdy: The number of idle threads
bsy: The number of total threads in any non-idle state
rd: The number of threads reading client requests. All states of processing before the "handler" takes control are in this state
wr: The number of threads in "write" state, which includes all Apache phases after a request has been read, including mapping to a file, access control, and the handler responsible for handling the response.
ka: threads in keepalive state
On Linux (when using event mpm) and z/OS, ka represents the connections (not threads) in keepalive state
log: threads in logging state
dns: threads looking up a hostname
cls: threads in (lingering) close state
On Linux (when using the event mpm) and z/OS, cls represents the connections (not threads) in (lingering) close state

AlwaysReport Directive

Description:	Configures interval based reporting even when all threads are
Syntax:	`AlwaysReport ON\|OFF`
Default:	`OFF`
Context:	server config
Status:	Extension
Module:	mod_mpmstats

Set this directive to on to print a report even when all threads in the server are idle.

MPMStatsBusyThreshold Directive

Description:	Sets threshold for "approaching MaxClients..." notice
Syntax:	`MPMStatsBusyThreshold ratio`
Default:	`MPMStatsBusyThreshold 0.9`
Context:	server config
Status:	Extension
Module:	mod_mpmstats
Compatibility:	IHS 9.0.5.5 and later (PH24265)

By default, IHS periodically warns if 90% of the servers threads are busy. Use this directive to change the threshold by specifying a value between ".01" and "1.0".

MPMStatsSystemLog Directive

Description:	Copies "approacing MaxClients..." notice to z/OS system log
Syntax:	`MPMStatsSystemLog ON\|OFF`
Default:	`MPMStatsSystemLog OFF`
Context:	server config
Status:	Extension
Module:	mod_mpmstats
Compatibility:	IHS 9.0.5.5 and later on z/OS (PH24265)

This directive copies the "approaching MaxClients..." message to the z/OS system log. The message has the format as shown below

BPXM023I ($USERID) CRIHS0003I $JOBNAME mpmstats: approaching MaxClients ($THREADSUSED/$MAXCLIENTS)

ReportInterval Directive

Description:	Configures the interval for writing thread statistics
Syntax:	`ReportInterval #-of-seconds`
Default:	`0, but default configuration has ReportInterval 300`
Context:	server config
Status:	Extension
Module:	mod_mpmstats

Every ReportInterval number of seconds, this module reports thread statistics if the server is non-idle.

SlowThreshold Directive

Description:	Sets a trigger for modules exceeding a specific timeout
Syntax:	`SlowThreshold seconds \| millisecondsms`
Default:	`unset`
Context:	server config
Status:	Extension
Module:	mod_mpmstats

This directive causes requests or module invocations which take more than the specified timeout to generate two new messages:

If the threshold is exceeded by any request during a ReportInterval, that thread will be individually reported in this modules output in the form
mpmstats (long-running requests): bsy: 3 in mod_test.c
With TrackHooksOptions logslow, when a module uses more than the threshold time in any phase of processing, an immediate ErrorLog entry of the form:
module mod_test.c took 5000ms to return OK in phase handler

SMFReportInterval Directive

Description:	Enables SMF reporting of mpmstats data
Syntax:	`SMFReportInterval seconds`
Default:	`0`
Context:	server config
Status:	Extension
Module:	mod_mpmstats
Compatibility:	IHS 8.5.5 and later on z/OS only

If set to a non-zero value, IHS writes an SMF Type 103 Subtype 13 record with the following contents.

field	length
parent process ID	4
ready threads	4
busy threads	4
reading threads	4
writing threads	4
logging threads	4
dns threads	4
closing threads	4
keepalive threads	4
bytes served	8
requests served	8
servername len	4
servername	$servername_len

Keepalive note

Currently the KeepAlive threads is always zero on z/OS using the Event MPM.

TrackHooks Directive

Description:	Enables reporting of time spent in individual Apache phases
Syntax:	`TrackHooks allhooks \| post_read_request \| check_userid \| check_user_access \| auth_checker \| handler`
Default:	`unset`
Context:	server config
Status:	Extension
Module:	mod_mpmstats

This directive allows the time spent in each Apache phase to be recorded in an environment variable. Original documentation on this feature

post_read_request: %{TPR}e
check_userid: %{TCU}e
check_user_access: %{TCA}e
auth_checker: %{TAC}e
handler: %{TRH}e
allhooks: macro setting to enable all hooks

TrackHooksOptions Directive

Description:	Enables more detailed tracking of hooks
Syntax:	`TrackHooksOptions millis\|permodule\|logslow\|notice\|allopts`
Default:	`unset`
Context:	server config
Status:	Extension
Module:	mod_mpmstats

This directive allows the time spent in each Apache phase to be recorded in an environment variable. Original documentation on this feature

millis: %{Txx}e variables will be recorded in millseconds
permodule: For phases where multiple modules participate, record the time each separate module takes to run
logslow: If specified, causes messages like "module mod_test.c took 5000ms to return OK in phase handler" when SlowThreshold is exceeded. Without the "notice" option below, the message is logged at INFO level.
notice: If logslow condition occurs, log at NOTICE level instead of INFO
allopts: macro setting to enable all options

TrackModules Directive

Description:	Enables reporting of individual modules busy on a thread
Syntax:	`TrackModules ON\|OFF`
Default:	`ON`
Context:	server config
Status:	Extension
Module:	mod_mpmstats

This directive, which depends on ExtendedStatus, enables reporting of which Apache modules are executing on active threads.

mpmstats: bsy: 1 in mod_was_ap22_http.c