Module Tour: mod_status
by Rael Dornfest
04/21/2000
| |
Module Tour Stops: |
|
• mod_info
• mod_status
|
Apache's mod_status gives administrators a quick snapshot of server
performance and activity.
This week we'll take a peek at mod_status, one of my favorite Apache
modules. Mod_status displays a nice compact representation of your Web
server's internal state and the comings and goings of its child processes.
I've found mod_status an invaluable monitoring and initial debugging tool.
gobbledegook
To the uninitiated, the mod_status output can look like so much gobbledegook,
but it's really quite straightforward. Let's take a look at some sample output.
Apache Server Status for somedomain.com
Server Version: Apache/1.3.9 (Unix) PHP/4.0b3
Server Built: Mar 4 2000 17:01:01
The first few lines identify and provide a brief description of
your server. The server version information includes
an incomplete list of some of the modules compiled into your server.
Our example server is running on a Unix system and has been compiled
with support for the
PHP scripting language. (The level
of detail provided by the server version line may be
limited by the
ServerTokens
configuration directive.)
Current Time: Thursday, 13-Apr-2000 17:22:36 PDT
Restart Time: Thursday, 13-Apr-2000 17:15:26 PDT
Parent Server Generation: 14
Server uptime: 7 minutes 10 seconds
Total accesses: 42 - Total Traffic: 187 kB
CPU Usage: u.1 s.1 cu0 cs0 - .0465% CPU load
.0977 requests/sec - 445 B/second - 4559 B/request
3 requests currently being processed, 5 idle servers
The next block represents the server's current state. Our example server
has only been up for a few minutes and hasn't yet seen much activity.
It is currently dealing with three requests, one of which is my request
for the server status itself. The message that five servers are idle servers is a clue
that this server is configured to maintain a pool of at least five spare
child processes ready to spring into action should the need arise.
K___K_W_........................................................
................................................................
................................................................
................................................................
Scoreboard Key:
"_" Waiting for Connection, "S" Starting up, "R" Reading Request,
"W" Sending Reply, "K" KeepAlive (read), "D" DNS Lookup, "L" Logging,
"G" Gracefully finishing, "." Open slot with no current process
No, that's not boring morse-code; it's the "scoreboard," a
pseudo-graphical representation of the state of the server's child
processes. According to the included Scoreboard Key, our server is
replying to one request, maintaining two KeepAlive connections,
and is maintaining five idle processes. A busier server's scoreboard
would look more like:
WWKW__WW_KKKWK__KKKKWKKKKK_WKKK_KK__KRWKKK__KK___K____WKK__KWWKK
_K___K___WWKWWW_W_W_WWWK_WW_WWWLWWW_KWWKKWKWWKWWKKWW_KWKKKKW__WK
WKWWW_KKWKKKWK_KW_KKKK__KK_KKKWWK_KW__K_KKK_K..........W........
................................................................
For more on pool regulation and KeepAlive, see my earlier
HTTP Wrangler column,
"An Amble Through Apache Configuration."
Srv PID Acc M CPU SS Req Conn Child Slot
0-14 29987 0/24/24 W 0.09 2 0 0.0 0.16 0.16
Client VHost Request Request
127.0.0.1 www.mydomain.net GET /server-status HTTP/1.0
In addition to a more general overview of your server's activity,
mod_status gets down to the nitty-gritty, displaying a snapshot of
the individual requests it is currently handling. Let's take a
gander at a fairly representative request. Please note that the
output above has been split in half for display purposes.
0-14
|
Srv
The ID of the child process and its generation. The generation increases
each time a child process is restarted, whether due to a server-restart or
a limit placed on the number of processes a child is allowed to handle.
See the MaxRequestsPerChild
directive.
|
29987
|
PID
The child's process ID.
|
0/24/24
|
Acc
The first number in this trio is the number of accesses or requests using
this connection. For non-KeepAlive connections, this will be 0 since
each request makes its own connection and so is always the first (and
last). The second is the number of requests handled thus far by this
child. The third is the number of requests handled by this slot; the
child may have come and gone, its slot taken by another.
|
W
|
Mode
The child's mode of operation; one of the following possibilities:
"_" Waiting for Connection, "S" Starting up,
"R" Reading Request, "W" Sending Reply,
"K" KeepAlive (read),
"D" DNS Lookup, "L" Logging, "G" Gracefully finishing,
"." Open slot with no current process
|
0.09
2
0
0.0
0.16
0.16
|
CPU SS Req Conn Child Slot
Some of the less useful bits and pieces...
CPU: The child's CPU usage in number of seconds.
SS: Seconds elapsed since the beginning of the request.
Req: Milliseconds taken to process the request.
Conn: Kilobytes transferred across this connection.
Child: Megabytes transferred by this child process.
Slot: Megabytes transferred by this slot, across children.
|
www.mydomain.net
|
VHost
Perhaps your server hosts multiple virtual domains; how would you determine
which page is being requested by GET /index.html?. The VHost
column helps you sort out which request is coming to which virtual host --
in this example, www.mydomain.net.
|
GET /server-status HTTP/1.0
|
Request
This particular hit is my request for server-status. The GET
bit indicates a simple request for a document (as opposed to sending data
to the server using POST). The browser (in this case the Unix command-line
wget program) is using HTTP version 1.0.
For more on HTTP, see my earlier
HTTP Wrangler column,
"Introducing Apache."
|
Installation
So how do you install and configure mod_status? I
make the assumption here that you built and installed Apache from source.
If you're not familiar with building Apache, may I suggest you read my earlier
HTTP Wrangler column,
Getting, Installing, and Running Apache.
First, move into your Apache source directory.
% cd /usr/local/src/apache_1.3.x
Thankfully Apache's configure script creates a cache
file, config.status, saving us the bother of completely
reconfiguring our Apache build from scratch. All we need to do is run
config.status, supplying the one argument necessary
to add mod_status.
If you've not already done so, now would be the time to become root.
# ./config.status --enable-module=status
Configuring for Apache, Version 1.3.11
...
Creating Makefile
Creating Configuration.apaci in src
Creating Makefile in src
+ configured for Linux platform
+ setting C compiler to gcc
+ setting C pre-processor to gcc -E
+ checking for system header files
+ adding selected modules
+ checking sizeof various data types
+ doing sanity check on compiler and options
...
Creating Makefile in src/modules/standard
Note: Apache's configure script automagically updates
config.status to include mod_status; next time you
configure you will not need to enable mod_status again.
Now that we've reconfigured Apache, let's rebuild.
# make
Your screen should look something like:
# make
===> src
make[1]: Entering directory `src/httpd/apache_1.3.11'
make[2]: Entering directory `src/httpd/apache_1.3.11/src'
===> src/regex
...
[several unsightly lines later]
...
gcc -DLINUX=2 -DUSE_HSREGEX -DUSE_EXPAT -I../lib/expat-lite
-DNO_DL_NEEDED `../apaci` -o ab -L../os/unix -L../ap ab.o
-lap -los -lm -lcrypt
make[2]: Leaving directory `src/httpd/apache_1.3.11/src/support'
<=== src/support
make[1]: Leaving directory `src/httpd/apache_1.3.11'
<=== src
#
Finally, you're ready to install your newly freshly built Apache.
# make install
(While not strictly necessary -- reinstalling should only overwrite files
that probably haven't changed since your last install -- I always advise
backing up your Apache directory.)
Configuration
Mod_status is easy to configure; in fact the directives already exist
in your httpd.conf file and simply need to be uncommented
and edited slightly.
If you're not familiar with Apache configuration, may I suggest you read my
earlier HTTP Wrangler column,
An Amble Through Apache Configuration.
# cd /usr/local/apache/conf
(or wherever your Apache installation's configuration files are located)
Open your httpd.conf file in the text editor of your choice and search for
the following set of configuration directives:
# Allow server status reports, with the URL of http://servername/server-status
# Change the ".your_domain.com" to match your domain to enable.
#
#<Location /server-status>
# SetHandler server-status
# Order deny,allow
# Deny from all
# Allow from .your_domain.com
#</Location>
Uncomment everything from &lt;Location /server-status&gt; to
&lt;/Location&gt; by removing the # characters
from the beginning of each line.
It's wise to protect your server-status output from prying eyes. The easiest way
to do this is to restrict its access to one computer or domain. Change the
.your_domain.com to the name of a computer or domain you wish to
allow a peek at server-status. For example, if you're the webmaven for your
server, you may want to allow only your computer, mycomputer.mydomain.org
access, your server-status configuration would look something like:
# Allow server status reports, with the URL of http://servername/server-status
# Change the ".your_domain.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from mycomputer.mydomain.org
</Location>
Only one tiny piece left. The default status display isn't as detailed as what you I showed you above. The more
abbreviated version looks something like:
PID Key:
29955 in state: _ , 29956 in state: _ , 29957 in state: _
29958 in state: _ , 29959 in state: W , 29978 in state: _
In order to see all the gory details, you need to enable "full" status. Find
the following lines and uncomment (remove the initial #) the
ExtendedStatus directive; the result should look like:
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On
That's all there is to mod_status configuration. Save your httpd.conf
file, shut down and start Apache.
# /usr/local/apache/sbin/apachectl stop
/usr/local/apache/sbin/apachectl stop: httpd stopped
# /usr/local/apache/sbin/apachectl start
/usr/local/apache/sbin/apachectl start: httpd started
#
Fire up your Web browser on a machine allowed access to your server's server-status
and point it at the URL:
http://servername/server-status
Happy reading! For more information on mod_status and other aspects of Apache
we touched on along the way, visit the Resources
section below.
Resources
The following is a list of starting points from which to explore further
some of the topics covered (or not) in this article.
- The Apache Software Foundation
- The Apache HTTP Server Project
- Apache 1.3 User's Guide
- mod_status
- ServerTokens
Tune in Next Time...
Our module tour continues with mod_info...
As always, if you'd like me to cover anything in particular, feel free to
post your suggestions to the
O'Reilly Network Apache Forum.
Rael Dornfest
is Chief Technology Officer at O'Reilly Media.
Read more HTTP Wrangler columns.
Return to the Apache DevCenter.
