third-party module troubleshooting¶

Introduction¶

This documentation applies to catastrophic symptoms such as crashes, hangs, and high CPU conditions which are not reproducible without a third-party module loaded.

Customers frequently open PMRs with IBM HTTP Server support to investigate problem symptoms encountered in configurations which include third-party modules. These problem symptoms include crashes, hangs, high CPU, incorrect output, and other issues. In most cases, the root cause of the problem symptom is not caused by IBM HTTP Server and is not something that IBM can diagnose.

If you need IBM to investigate an IBM HTTP Server problem which is encountered in an environment with a third-party module, you need to apply our latest applicable fixes and recreate the problem before a PMR can be investigated. In addition, you need to utilize applicable IBM HTTP Server serviceability features to collect the necessary documentation. There are several reasons for this requirement:

Some problems in these environments are known to have been caused by IBM HTTP Server defects which are resolved with the latest fixes.
It is not always possible for IBM HTTP Server support to know how past IBM HTTP Server defects will manifest themselves in environments with third-party modules.
Recent maintenance levels include new serviceability features implemented specifically to shorten the time required to diagnose problems in environments with third-party modules.

Even when all available serviceability features are utilized, it may still be impossible for IBM HTTP Server support to diagnose the cause of a problem with third-party modules loaded. All possible attempts should be made to reproduce the problem with only IBM code loaded into the web server.

Other limitations of third party modules in IBM HTTP Server¶

IBM HTTP Server support cannot assist with building, configuring, testing, certification, debugging, or providing support for code from third parties.
IBM HTTP Server releases provide a stable Apache API that is frozen at general availability, but the Apache HTTP Server API provides mechanisms where module authors can discover and cope with this level.
Use of third party modules does not invalidate any support you otherwise have, as long as IBM HTTP Server is still used only in support of the program it was bundled with.

Unexpexted HTTP request failures.¶

Occasionally, third-party modules may fail requests without reporting the reason of the failure to log files, making it difficult to diagnose the problem. Newer levels of IBM HTTP Server have the capability of tracking the name of the module which failed, or successfully handled, the request. This information can be reported to the access log.

Make sure ExtendedStatus ON is present, even if not using mod_status or /server-status. Prior to 8.5.5.25/9.0.5.18, ExtendedStatus ON was only on by default when mod_status was loaded.
Add %{RH}e to the format string used for the access log. Here is an example LogFormat directive:
```
LogFormat "%h %l %u %t \"%r\" %>s %b %D %{RH}e" common
```

A new field will be written to the end of every access log record.

Web server hangs or other unresponsive behavior¶

If experiencing an intermittent hang, there are a few things you can do in advance to prepare to troubleshoot the environment.

Make sure mod_mpmstats is configured with a reasonable ReportInterval
Be prepared to run the hang mustgather.

Web server high CPU conditions¶

Be prepared to run the high CPU instructions for Unix and Linux.