Apache Module mod_net_trace

Description:	Network trace module for IBM HTTP Server
Status:	Extension
Module Identifier:	net_trace_module
Source File:	mod_net_trace.c

Summary

This module allow IHS to trace socket-level interactions with the client, including plaintext headers and bodies for SSL requests and detailed timing info of socket operations.

Topics

Example configuration
Tuning

Example configuration

All modern releases of IHS ship with a sample configuration for this module that can be activated simply by uncommenting the #LoadModule net_trace_module... in httpd.conf. If your httpd.conf does not have this stanza, it can be copied from the file $IHSROOT/conf/httpd.conf.default.

LoadModule net_trace_module modules/debug/mod_net_trace.so
<IfModule mod_net_trace.c>
  NetTraceFile /tmp/nettrace
  NetTrace client * dest file event senddata=65535 event recvdata=65535 event misccalls
</IfModule>

Tuning

If the problem you are debugging requires high load or a long run, you can limit the amount of data collected several ways:

Isolate the capture to a specific client IP address by replacing the * after the client keyword.
Isolate the capture of response data to a specific URL using the url option. It does not match against the query string, only the path component
Setting 'senddata' and 'recvdata' bytelimit parameter to 0 if data in that direction is not needed (this is rarely useful).

NetTrace Directive

Description:	Configures one or more capture specifications
Syntax:	`NetTrace [keyword val]...`
Default:	`unset`
Context:	server config, virtual host
Status:	Extension
Module:	mod_net_trace

Each instance of this directive instructs the server to record network traces with the specified criteria. Usually, the example from the default configuration is sufficient to target a single client IP and obtain the necessary data.

NetTraceFile /tmp/nettrace NetTrace client 127.0.0.1 dest file event senddata=65535 event recvdata=65535 event misccalls NetTrace client 127.0.0.2 dest file event senddata=100 event recvdata=100 event misccalls

The supported keywords and their values follow.

client

This allows you to match on specific client IP addresses. The value for this keyword can be * to match all clients or ip-address to match a particular client or ip-address/num-prefix-bits to match particular subnets. It only works with numeric IP addresses (IPv4 or IPv6).

You shouldn't code client more than once.

To trace requests where IHS acts as a proxy, you can use the IP address of the origin server as an argument to client

dest

This specifies the destination of the collected data for this rule. You can specify more than one destination. Here are the values for dest:

file
Data will be written to the file specified by the NetTraceFile directive.

This is the default.
memory
Data will be stored in memory.

The memory is released at the end of the connection, but if the server crashes while processing a request on the connection the data will be available in the core dump for debugging.
errlog
Data will be written to the server error log. The priority is notice, so the trace records will be written regardless of the value of the LogLevel directive.

serverport

If specified, the server port for the connection must match the value of this operand.

clientport

If specified, the client port for the connection must match the value of this operand.

This is only useful in some limited test scenarios.

event

This specifies the events which will be traced. By default, send and receive-related API crossings will be traced. Here are the possible values for event:

senddata[=bytelimit]
Capture data sent by IHS. The default bytelimit (limit on how much sent data will be captured on a connection) is 1024. Note: file contents sent via apr_sendfile() will not be traced.

Note: The bytelimit currently has no effect, other than a value of 0 to disable dumping of data in the specified direction.
recvdata[=bytelimit]
Capture data received by IHS. The default bytelimit (limit on how much received data will be captured on a connection) is 1024.

Note: The bytelimit currently has no effect, other than a value of 0 to disable dumping of data in the specified direction.
misccalls
Trace miscellaneous socket calls (e.g., apr_socket_close(), apr_socket_timeout_set(), etc.).

miscopt

Miscellaneous options

usec
Record microsecond timestamp for some important trace points

url

If specified, the URL for the request must match this value. This is not determined until after the request has been read, so the HTTP request header will be traced even if the URL is different.

NetTraceFile Directive

Description:	Configures an external trace file
Syntax:	`NetTraceFile filesystem-path`
Default:	`unset`
Context:	server config, virtual host
Status:	Extension
Module:	mod_net_trace

This directive specifies the trace file used for any NetTrace directive that includes an option of "dest" with the sub-option "file".