Installation

Installation of the system consists of three simple steps:

  1. Install the lamp1701 libraries.
  2. Install the PHP probe by
    1. Installing the “lamp1701.so” extension and
    2. Enabling the extension in your “php.ini” file.

The following assumes the (absolute) path to the extracted package directory is stored in the MOD_TOP_DIR environment variable. Also, please make sure you've removed any earlier installation.

Remove any files from earlier versions before installing a new version.

1. Install the Lamp1701 Libraries

Link to the shared object versions from a system library directory, e.g. “/usr/lib” or “/usr/lib64”:

# ln -s $MOD_TOP_DIR/lib/liblamp1701*.so* /usr/lib

Alternatively, add the library directory to a system-wide LD_LIBRARY_PATH variable.

2. Install the PHP Probe Extension

Link to the PHP probe from your system's PHP extension directory, e.g. “/usr/lib/php5/20060613”:

# ln -s $MOD_TOP_DIR/php/lamp1701.so /usr/lib/php5/20060613

Then enable the extension in your “php.ini” by adding this line to it:

extension=lamp1701.so

Running mod_top

Start the lamp1701d controller agent on the machine to monitor (the one running PHP with the lamp1701.so extension).

% $MOD_TOP_DIR/sbin/lamp1701d

See the lamp1701d(8) man page for supported options.

Run mod_top either without options on that same machine or on any other machine by passing the address of the machine running the server (see the mod_top(1) man page for supported options.)

% $MOD_TOP_DIR/bin/mod_top -s address

Also note that if mod_top is running on a different machine, that machines' clock must not be running faster than one refresh interval compared to the target machine or it will always only request (non-existent) future data.

Finally, run a PHP script from the command line or restart Apache and issue a few requests against an Apache-hosted PHP application and watch mod_top. The PHP probe will record data as long as the lamp1701d agent is running.

mod_top(1) Manual Page

NAME

mod_top  -  lamp1701 ncurses client

SYNOPSIS

mod_top [-h|-V]
mod_top [-s address] [-p port] [-r float]

DESCRIPTION

mod_top is a curses-based client for the lamp1701 suite of LAMP application management tools. It is similar in spirit to the popular UNIX top(1) program, albeit much less complex. mod_top queries a lamp1701 agent at regular intervals, aggregates any probe records received, and presents the data in a sorted display. If the data returned by the agent have been compromised by queue overflows, mod_top flags them as unreliable by displaying them in red.

In addition, mod_top may be used to instruct the agent to suspend or resume data collection (see KEY BINDINGS, below). While suspended, both probes and agent run practically without overhead.

For every block and caller, mod_top displays

  1. how many CALLS have been recorded for the block and its caller
  2. how much aggregate CPU time (in ms) the calls have consumed
  3. how much aggregate wallclock TIME (in ms) the calls have taken
  4. how much aggregate MEMORY (in kB) the calls have allocated or released, and
  5. the block NAME along with its CALLER's name.

Key bindings exist to sort the data by any of these columns at any time (see KEY BINDINGS, below).

OPTIONS

-h, --help
Display a screenfull of help and exit.
-V, --version
Echo the version and exit.
-s, --server address
Contact the lamp1701 agent on address address. Default is to connect to any server listening on localhost (i.e. 127.0.0.1). address is expected in dotted-quad notation.
-p, --port port
Contact the server on port port. Default is to connect to port 1701.
-r, --refresh float
Refresh the display every float seconds. Default is 2s.

KEY BINDINGS

The following key bindings are currently defined:

h
display a brief help overview
p
pause/unpause the program (toggle)
s
suspend/resume the server (toggle)
b
sort by block NAME and CALLER (ascending)
c
sort by CPU consumption (descending, default)
m
sort by MEMORY consumption (descending)
M
sort by MEMORY consumption (ascending)
n
sort by number of CALLS (descending)
t
sort by wallclock TIME (descending)
q
quit the program

BUGS

The Linux kernel does not always report memory size instantaneously. As a result, memory consumption may be occasionally accounted for in a subsequent or calling block.

No security provisions with respect to server suspension are made at this point.

Currently, mod_top requests frames from lamp1701d(8) by referring to absolute time. As a result, no frames may be returned if the time differential between client and server machine exceeds the refresh interval. This might be considered a bug.

SEE ALSO

lamp1701d(8)

AUTHOR

Copyright (c) 2007 Lamp1701, Inc. All rights reserved.

lamp1701d(8) Manual Page

NAME

lamp1701d  -  lamp1701 agent

SYNOPSIS

lamp1701d -h|-V
lamp1701d [-l address] [-p port] [-X]
          [--aggregation-rate seconds] [--log-level
level]
          [--start-suspended] [--ipc-permissions mode]
          [--client-buffer-size n] [--probe-buffer-size n]
          [--frame-records-max n]

DESCRIPTION

lamp1701d acts as an agent between probes and clients, controlling IPC communication structures as well as client interaction.

On the probe side, lamp1701d creates a queue in which probes store their data records. The queue is allocated in shared memory and controlled by the --probe-buffer-size option. On the client side, lamp1701d listens for client connections on an address and port specified by the -l and -p options. The rate at which probe records are aggregated into time slices (``frames'') may be specified via the --aggregation-rate option and the number of frames stored in the client queue via --client-buffer-size. In addition, --frame-records-max may be used to fine-tune the number of distinct block records each frame can hold.

Clients may instruct the agent to suspend or resume data collection by sending it a /suspend or /resume HTTP POST request (see mod_top(1)). While suspended, both probes and agent run practically without overhead.

Unless the --startup-suspended option is given, probes begin recording as soon as the agent is started and continue to do so until it is stopped or suspended.

The --ipc-permissions option may be used to restrict read or write access to the IPC data structures on systems where this type of security is desired.

Finally, --log-level allows administrators to control exactly which (and how many) messages are written to the LOG_DAEMON facility, or, if the -X option is given, to stderr.

OPTIONS

-h, --help
Display a screenfull of help and exit.
-V, --version
Echo the version and exit.
-l, --listen address
Listen on address address. Default is to listen on any address (i.e. 0.0.0.0), which is not very secure. address is expected in dotted-quad notation.
-p, --port port
Listen on port port. Default is to listen for incoming client connections on port 1701. Unfortunately however, that port is reserved for L2TP, the Layer 2 Tunneling Protocol. Use this option to specify a different port if so needed or desired.
-X, --no-daemon
Run in the foreground without detaching from the terminal. Use this option to e.g. watch for log output on stderr instead of wherever your syslogd(8) configuration directs messages from the LOG_DAEMON facility.
--aggregation-rate float
Collect and aggregate system probe data every float seconds. Default is 0.1s. Note that this rate together with the number of frames that are storable in the queue (see next option) determine how much history the agent can hold for clients.
--log-level level
Log messages at level level or lower. Levels are taken from syslog(3) and expected in integer format as defined in /usr/include/syslog.h. The default is to log messages with importance LOG_NOTICE or higher, i.e. 5 or lower on most systems.
--start-suspended
Start with data collection suspended. Use this option if lamp1701d is to be started at system startup time and you do not want to start collecting data immediately.
--ipc-permissions mode
By default, the IPC structures used to communicate with probes are created with permissions 0666, making them group- as well as world-writable, which, while hassle-free from an operations point of view, is everything but secure and not recommended for production use. Use this option to restrict read/write access to either owner or owner and group. (Note that both, probes and lamp1701d, need read as well as write access to these structures.)
--client-buffer-size n
Number of frames to reserve storage for in the client queue. Coupled with the aggregation rate (see above), this determines how much history a client is guaranteed. The default is to size the queue to hold 100 frames, which, at a 0.1s aggregation rate, supports client refresh rates up to 10s.
--probe-buffer-size n
Number of probe records to reserve storage for in the probe queue. The default is 4096. Adjust if you incur probe queue overflows.
--frame-records-max n
Maximum number of distinct block records to reserve storage for within each frame. The default is 512. Adjust this if you need to conserve memory or incur too many frame record overflows.

CAVEATS

For installation and testing simplicity, the IPC structures are left world-writable. This presents a security risk in the event of malicious local users writing specially crafted data to these structures that either crash the agent or applications hosting the probes or get these components to execute code with possibly elevated privilege. For this reason, it is highly recommended to start the agent with restrictive permissions in production environments. See the --ipc-permissions option.

BUGS

On some systems, values reported for system and user time may occasionally in sum exceed the value reported for real (wallclock) time. This is an artefact due to the different timing sources (on-chip timing registers vs. system-wide clock) and resolutions used by the system to provide these values.

SEE ALSO

mod_top(1)

AUTHOR

Copyright (c) 2007 Lamp1701, Inc. All rights reserved.