API documentation

The following documentation is based on the source code of version 1.2 of the apache-manager package. The following modules are available:

apache_manager

The apache_manager module defines the core logic of the Apache manager.

apache_manager.PORTS_CONF = '/etc/apache2/ports.conf'

The absolute pathname of the configuration file that defines the port(s) that Apache listens on (a string). This constant is used as a default value for ports_config. It’s based on Debian’s Apache 2 packaging.

apache_manager.STATUS_COLUMNS = ('Srv', 'PID', 'Acc', 'M', 'CPU', 'SS', 'Req', 'Conn', 'Child', 'Slot', 'Client', 'VHost', 'Request')

The expected column names in the worker status table of the Apache status page (an iterable of strings).

apache_manager.IDLE_MODES = ('_', 'I', '.')

Worker modes that are considered idle (a tuple of strings). Refer to WorkerStatus.is_idle.

apache_manager.NATIVE_WORKERS_LABEL = 'native'

The label used to identify native Apache workers in exported metrics (a string).

This is used by ApacheManager.save_metrics() to distinguish native Apache workers from WSGI process groups.

apache_manager.HANGING_WORKER_THRESHOLD = 300

The number of seconds before an active worker is considered ‘hanging’ (a number). Refer to ApacheManager.hanging_workers.

class apache_manager.ApacheManager(*args, **kw)[source]

Apache web server manager.

Most of the computed properties on this class are cached to avoid repeated expensive computations (refer to cached_property for details). The easiest way to invalidate all of these cached properties at once is to call the refresh() method.

__init__(*args, **kw)[source]

Initialize a ApacheManager object.

Parameters:args – The first positional argument is used to set ports_config.
num_killed_active[source]

The number of active workers killed by kill_workers() (an integer).

Note

The num_killed_active property is a writable_property. You can change the value of this property using normal attribute assignment syntax.

num_killed_idle[source]

The number of idle workers killed by kill_workers() (an integer).

Note

The num_killed_idle property is a writable_property. You can change the value of this property using normal attribute assignment syntax.

status_response[source]

Whether the status page was fetched successfully by fetch_status_page() (a boolean).

This will be None as long as fetch_status_page hasn’t been called.

Note

The status_response property is a writable_property. You can change the value of this property using normal attribute assignment syntax.

ports_config[source]

The absolute pathname of the ports.conf configuration file (a string).

The configuration file is expected to define the port(s) that Apache listens on. Defaults to PORTS_CONF.

Note

The ports_config property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

listen_addresses[source]

The network address(es) where Apache is listening (a list of NetworkAddress objects).

Raises:AddressDiscoveryError when discovery fails (e.g. because /etc/apache2/ports.conf is missing or can’t be parsed).

Here’s an example:

>>> from apache_manager import ApacheManager
>>> manager = ApacheManager()
>>> manager.listen_addresses
[NetworkAddress(protocol='http',
                address='127.0.0.1',
                port=81,
                url='http://127.0.0.1:81')]

Note

The listen_addresses property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

html_status_url[source]

The URL on which Apache’s HTML status page can be retrieved (a string).

Raises:Any exceptions raised by listen_addresses.

Here’s an example:

>>> from apache_manager import ApacheManager
>>> manager = ApacheManager()
>>> manager.html_status_url
'http://127.0.0.1:80/server-status'

Note

The html_status_url property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

text_status_url[source]

The URL on which Apache’s plain text status page can be retrieved (a string).

Raises:Any exceptions raised by listen_addresses.

Here’s an example:

>>> from apache_manager import ApacheManager
>>> manager = ApacheManager()
>>> manager.text_status_url
'http://127.0.0.1:80/server-status?auto'

Note

The text_status_url property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

html_status[source]

The content of Apache’s HTML status page (a string). See also text_status.

Raises:Any exceptions raised by fetch_status_page().

Note

The html_status property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

text_status[source]

The content of Apache’s plain text status page (a string). See also html_status.

Raises:Any exceptions raised by fetch_status_page().

Here’s an example:

>>> from apache_manager import ApacheManager
>>> manager = ApacheManager()
>>> print manager.text_status
Total Accesses: 100
Total kBytes: 275
CPULoad: .000203794
Uptime: 181556
ReqPerSec: .000550794
BytesPerSec: 1.55104
BytesPerReq: 2816
BusyWorkers: 1
IdleWorkers: 5
Scoreboard: ____W._.......................................

Note

The text_status property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

fetch_status_page(status_url)[source]

Fetch an Apache status page and return its content.

Parameters:url – The URL of the status page (a string).
Returns:The response body (a string).
Raises:StatusPageError if fetching of the status page fails.
slots[source]

The status of Apache workers (a list of WorkerStatus objects).

Raises:Any exceptions raised by html_status or StatusPageError if parsing of the Apache status page fails.

The slots property contains one WorkerStatus object for each worker “slot” that Apache has allocated. This means that some of the WorkerStatus objects may not have expected properties like pid because they describe an “empty slot”. See the workers property for a list of WorkerStatus objects without empty slots.

Note

The slots property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

workers[source]

The status of the Apache workers, a list of WorkerStatus objects.

Raises:Any exceptions raised by html_status or StatusPageError if parsing of the Apache status page fails.

This property’s value is based on slots but excludes empty slots (i.e. every WorkerStatus object in workers will have expected properties like pid).

Note

The workers property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

hanging_workers[source]

A list of workers that appear to be ‘hanging’ (unresponsive).

Raises:Any exceptions raised by html_status or StatusPageError if parsing of the Apache status page fails.

This property’s value is based on workers but excludes workers that aren’t active and workers whose ‘seconds since the beginning of the current request’ is lower than HANGING_WORKER_THRESHOLD.

Note

The hanging_workers property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

killable_workers[source]

A list of KillableWorker objects.

Note

The killable_workers property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

manager_metrics

Information about the interaction between the Apache manager and the Apache web server.

Here’s an example of the resulting dictionary:

>>> from apache_manager import ApacheManager
>>> from pprint import pprint
>>> manager = ApacheManager()
>>> pprint(manager.manager_metrics)
{'workers_hanging': 0,
 'workers_killed_active': 0,
 'workers_killed_idle': 0,
 'status_response': None}

Notes about these metrics:

  • The status_response key is None by default. Once an Apache status page has been fetched it becomes True if the status page was fetched successfully or False if fetching of the status page failed (see fetch_status_page(), html_status and text_status).
  • The workers_hanging key gives the number of hanging workers (based on the length of hanging_workers).
  • The workers_killed_active and workers_killed_idle keys give the number of Apache workers killed by kill_workers().
server_metrics[source]

Global web server metrics parsed from the machine readable plain text status page.

Here’s an example of the values you can expect:

>>> from apache_manager import ApacheManager
>>> from pprint import pprint
>>> manager = ApacheManager()
>>> pprint(manager.server_metrics)
{'busy_workers': 1,
 'bytes_per_request': 3120.19,
 'bytes_per_second': 1.52158,
 'cpu_load': 0.000195063,
 'idle_workers': 4,
 'requests_per_second': 0.000487657,
 'total_accesses': 85,
 'total_traffic': 259,
 'uptime': 174303}

Note

The server_metrics property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

extract_metric(pattern, default='0')[source]

Extract a metric from the Apache text status page.

Parameters:
  • pattern – A regular expression that captures a metric from the text status page (a string).
  • default – The default value to return if the pattern isn’t matched (a string).
Returns:

The value of the capture group in the matched pattern or the default value (if the pattern didn’t match).

This method is a helper for server_metrics that extracts metrics from the Apache text status page based on a regular expression pattern.

memory_usage[source]

The memory usage of the Apache workers (a StatsList object).

Based on proc.apache.find_apache_memory_usage(). See also wsgi_process_groups.

Here’s an example:

>>> from apache_manager import ApacheManager
>>> from pprint import pprint
>>> manager = ApacheManager()
>>> pprint(manager.memory_usage)
[13697024, 466776064, 735391744, 180432896, 465453056]
>>> print(manager.memory_usage.min)
13697024
>>> print(manager.memory_usage.average)
141787428.571
>>> print(manager.memory_usage.max)
735391744

Note

The memory_usage property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

wsgi_process_groups[source]

The memory usage of Apache workers in WSGI process groups.

The value of this property is a dictionary with process group names as keys and StatsList objects as values.

Based on proc.apache.find_apache_memory_usage(). See also memory_usage.

Here’s an example:

>>> from apache_manager import ApacheManager
>>> from pprint import pprint
>>> manager = ApacheManager()
>>> pprint(manager.wsgi_process_groups)
{'group-one': [44048384, 44724224, 44048384],
 'group-two': [52088832, 51879936, 55554048, 54956032, 54968320],
 'other-group': [13697024, 13697024, 13697024, 13697024]}

Note

The wsgi_process_groups property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

combined_memory_usage[source]

The result of find_apache_memory_usage().

This property caches the result so that when memory_usage and wsgi_process_groups are both dereferenced, the function find_apache_memory_usage() only has to be called once.

Note

The combined_memory_usage property is a cached_property. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

kill_workers(max_memory_active=0, max_memory_idle=0, timeout=0, dry_run=False)[source]

Kill Apache worker processes that exceed resource usage thresholds.

Parameters:
  • max_memory_active – The maximum number of bytes of memory that active Apache worker processes are allowed to use (an integer).
  • max_memory_idle – The maximum number of bytes of memory that idle Apache worker processes are allowed to use (an integer).
  • timeout – The maximum number of seconds since the beginning of the most recent request (a number).
Returns:

A list of integers with process ids of killed workers.

Some implementation notes about this method:

  • If any of the parameters are zero the respective resource usage threshold will not be applied.
  • Memory usage is measured using memory_usage.
  • The number of seconds since the beginning of the most recent request is measured using WorkerStatus.ss.
  • Worker processes are killed using the kill() method of the proc.core.Process class.

See also num_killed_active and num_killed_idle.

save_metrics(data_file)[source]

Store monitoring metrics in a data file.

Parameters:data_file – The pathname of the data file (a string).

This method stores the metrics provided by manager_metrics and server_metrics in a text file in an easy to parse format. Here’s an example of what the contents of the file look like:

# Global Apache server metrics.
busy-workers         1
bytes-per-request    0.0
bytes-per-second     0.0
cpu-load             1.13893
idle-workers         4
requests-per-second  1.89822
total-accesses       15
total-traffic        0
uptime               790212

# Metrics internal to apache-manager.
status-response        0
workers-killed-active  0
workers-killed-idle    0

# Memory usage of native Apache worker processes.
memory-usage  native  count    5
memory-usage  native  min      331776
memory-usage  native  max      1662976
memory-usage  native  average  598016.0
memory-usage  native  median   331776

# Memory usage of 'example' WSGI worker processes.
memory-usage  example  count    4
memory-usage  example  min      356352
memory-usage  example  max      372736
memory-usage  example  average  368640.0
memory-usage  example  median   372736.0

The values in the example above have been aligned to ease readability; in reality the names and values are delimited by tab characters (as long as you parse the file as whitespace delimited name/value pairs it will be fine, this is trivial to do with e.g. AWK).

refresh()[source]

Clear cached properties so that their values are recomputed when dereferenced.

class apache_manager.NetworkAddress(**kw)[source]

Network address objects encapsulate everything we need to know to connect to Apache.

url

The URL corresponding to protocol, address and port (a string).

protocol[source]

The protocol that Apache is listening for (one of the strings ‘http’ or ‘https’).

Note

The protocol property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named protocol (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

address[source]

The IP address on which Apache is listening (a string).

Note

The address property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named address (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

port[source]

The port number on which Apache is listening (an integer).

Note

The port property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named port (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

__str__()[source]

Use url for a human friendly representation.

class apache_manager.KillableWorker(**kw)[source]

Abstract base class to represent killable Apache worker processes.

Worker processes can be killed based on resource usage thresholds like memory usage and/or requests that are taking too long to process. There are currently two implementations of killable workers:

  • WorkerStatus represents the information about a worker process that was retrieved from Apache’s status page.
  • NonNativeWorker represents processes that are direct descendants of the master Apache process but are not included in the workers listed on Apache’s status page (e.g. WSGI daemon processes spawned by mod_wsgi).
is_active[source]

True if the worker is processing a request, False otherwise.

Note

The is_active property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named is_active (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

is_alive

True if process is running, False otherwise.

memory_usage[source]

The memory usage of the worker process in bytes.

The value of this property is an integer or None (if the process disappeared before the process information is requested).

The value of this property is based on the rss property of the proc.core.Process class.

Note

The memory_usage property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

pid[source]

The process ID of the Apache worker (an integer or None).

If process is set then the value of pid defaults to proc.core.Process.pid.

Note

The pid property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named pid (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

process[source]

The proc.core.Process object for this worker process (or None).

If pid is set then the value of process defaults to the result of proc.core.Process.from_pid(). If the worker process disappears before the process information is requested process will be None.

Note

The process property is a custom_property. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can use del or delattr().

request[source]

The HTTP status line of the most recent request (a string or None).

Note

The request property is a mutable_property. You can change the value of this property using normal attribute assignment syntax. To reset it to its default (computed) value you can use del or delattr().

class apache_manager.NonNativeWorker(**kw)[source]

Non-native Apache worker processes.

Objects of this type represent processes that are direct descendants of the master Apache process but are not included in the workers listed on Apache’s status page (e.g. WSGI daemon processes spawned by mod_wsgi).

These processes (assumed to be workers of one kind or another) can only be killed based on their memory usage, because this information can be easily retrieved from the Linux /proc file system without an API provided by the Apache web server (because there is no such API for non-native workers, to the best of my knowledge).

process[source]

The proc.core.Process object for this worker process.

Note

The process property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named process (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

is_active[source]

True because this information isn’t available for non-native workers.

Note

The is_active property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named is_active (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

__str__()[source]

Render a human friendly representation of a non-native Apache worker.

class apache_manager.WorkerStatus(**kw)[source]

WorkerStatus objects represent the state of an Apache worker.

These objects are constructed by the ApacheManager.workers property. To give you an idea of what WorkerStatus objects look like, here’s a simple example:

>>> from apache_manager import ApacheManager
>>> manager = ApacheManager()
>>> print(manager.workers[0])
WorkerStatus(acc=(0, 6, 128),
             child=0.01,
             conn=0.0,
             cpu=0.03,
             is_active=False,
             is_alive=True,
             is_idle=True,
             m='_',
             memory_usage=5185536,
             pid=31212,
             process=Process(...),
             req=1,
             request='GET /server-status HTTP/1.1',
             slot=0.2,
             srv=(0, 38),
             ss=234)

The naming of the fields may look somewhat obscure, this is because they match the names given on the Apache status page. If any of the fields are not available their value will be None. The following properties are parsed from the Apache status page:

The following computed properties are based on the properties parsed from the Apache status page:

status_fields[source]

The raw status fields extracted from Apache’s status page (a dictionary).

Note

The status_fields property is a required_property. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named status_fields (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.

acc[source]

The number of accesses this connection / this child / this slot (a tuple of three integers).

Note

The acc property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

child[source]

The number of megabytes transferred this child (a float).

Note

The child property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

client[source]

The IP address of the client that was last served (a string).

Note

The client property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

conn[source]

The number of kilobytes transferred this connection (a float).

Note

The conn property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

cpu[source]

The CPU usage (number of seconds as a floating point number).

Note

The cpu property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

is_idle

True if the worker is idle, False otherwise.

The value of this property is based on m and IDLE_MODES.

is_active

True if the worker isn’t idle, False otherwise.

The value of this property is based on is_idle.

m[source]

The mode of operation (a string).

Here’s an overview of known modes (not intended as an exhaustive list):

Mode Description
_ Waiting for connection
S Starting up
R Reading request
W Sending reply
K Keepalive (read)
D DNS lookup
C Closing connection
L Logging
G Gracefully finishing
I Idle cleanup of worker
. Open slot with no current process

See also is_active and is_idle.

Note

The m property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

pid[source]

The process ID of the Apache worker (an integer).

Note

The pid property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

req[source]

The number of milliseconds required to process the most recent request (an integer).

Note

The req property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

request[source]

The HTTP status line of the most recent request (a string or None).

The default value of the request field on Apache’s status page is the string NULL. This obscure implementation detail is hidden by the request property.

Note

The request property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

slot[source]

The total number of megabytes transferred this slot (a float).

Note

The slot property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

srv[source]

Child Server number and generation (a tuple of two integers).

Note

The srv property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

ss[source]

The number of seconds since the beginning of the most recent request (a float).

Note

The ss property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

vhost[source]

The server name and port of the virtual host that served the last request (a string).

Note

The vhost property is a lazy_property. This property’s value is computed once (the first time it is accessed) and the result is cached.

__str__()[source]

Render a human friendly representation of a native Apache worker.

apache_manager.cli

Usage: apache-manager [OPTIONS]

Command line interface to monitor the Apache web server and kill worker processes that exceed resource thresholds. When no options are given the server metrics and memory usage of workers are printed to the terminal.

Supported options:

Option Description
-w, --watch This option causes the Apache manager to redraw the collected metrics once every 10 seconds in a “top” like interface until interrupted using “q” (for quite) or Control-C.
-a, --max-memory-active=SIZE Kill active Apache workers that are using more memory than specified by the SIZE argument. SIZE is expected to be a human readable memory size like 50K (50 kilobytes), 42M (42 megabytes), 2G (2 gigabytes), etc.
-i, --max-memory-idle=SIZE Kill Apache workers that are using more memory than specified by the SIZE argument (see --max-memory-active for acceptable values of SIZE).
-t, --max-ss, --max-time=TIMESPAN Kill Apache workers whose “time since the beginning of the most recent request” is greater than specified by the TIMESPAN argument. TIMESPAN is expected to be a human readable timespan like 2s (2 seconds), 3m (3 minutes), 5h (5 hours), 2d (2 days), etc.
-f, --data-file=PATH Change the pathname of the file where the Apache manager stores monitoring metrics after every run. Defaults to “/tmp/apache-manager.txt”.
-z, --zabbix-discovery Generate a JSON fragment that’s compatible with the low-level discovery support in the Zabbix monitoring system. With the right template in place this enables the Zabbix server to discover the names of the WSGI process groups that are active on any given server. This makes it possible to collect and analyze the memory usage of specific WSGI process groups.
-n, --dry-run, --simulate Don’t actually kill any Apache workers.
-v, --verbose Increase verbosity (can be repeated).
-q, --quiet Decrease verbosity (can be repeated).
-h, --help Show this message and exit.
apache_manager.cli.main()[source]

Command line interface for the apache-manager program.

apache_manager.cli.report_metrics(manager)[source]

Create a textual summary of Apache web server metrics.

apache_manager.cli.report_memory_usage(lines, label, memory_usage)[source]

Create a textual summary of Apache worker memory usage.

apache_manager.cli.report_zabbix_discovery(manager)[source]

Enable Zabbix low-level discovery of WSGI application groups.

apache_manager.cli.line_is_heading(line)[source]

Check whether a line of output generated by report_metrics() should be highlighted as a heading.

apache_manager.interactive

A top like interactive viewer for Apache web server metrics.

The interactive module implements a top like interactive viewer for Apache web server metrics using curses. It can be invoked from the command line using apache-manager --watch.

Please note that the functions in this module are not included in the test suite and are excluded from coverage calculations because:

  1. For now this module is just an interesting experiment. It might disappear completely or I might change it significantly, it all depends on time and interest. For example it would be cool to have a tool like mytop or innotop for Apache workers, but it’s going to take time to build something like that and I have 40+ open source projects and limited spare time, so I’m not going to commit to anything :-).
  2. This is my first time working with Python’s curses module (and curses interfaces in general) and it’s not yet clear to me how feasible it is to test an interactive command line interface that’s not line based.
apache_manager.interactive.watch_metrics(manager)[source]

Watch Apache web server metrics in a top like interface.

apache_manager.interactive.redraw_loop(screen, manager)[source]

The main loop that continuously redraws Apache web server metrics.

apache_manager.exceptions

Custom exceptions raised by the Apache manager.

The exceptions module defines custom exceptions raised by the Apache manager.

exception apache_manager.exceptions.ApacheManagerError[source]

Base exception for custom exceptions raised by apache_manager.

exception apache_manager.exceptions.AddressDiscoveryError[source]

Raised by ApacheManager.listen_addresses when port discovery fails.

exception apache_manager.exceptions.StatusPageError[source]

Raised by ApacheManager.workers when the status page can’t be retrieved.