mod_bmx Monitoring Module for Apache
Copyright (c) 2007 Codemass, Inc.
Copyright (c) 2007 Hyperic, Inc.
All rights reserved.  See the LICENSE.txt file distributed with this work
for additional information regarding copyright ownership.
=====================================================================

Please see the INSTALL.txt file for installation and configuration
details. You will also find source code documentation in HTML form
(generated by doxygen) within the docs/html directory.

Overview:
---------

BMX is a framework for Apache to provide internal runtime statistics
and configuration information to interested remote agents. It can
be used to report on the internal workings and status of Apache at
runtime, such as performance metrics and current capacity.

BMX comes with a number of Apache Modules, as well as an API for
creating new BMX plugins.

Provided Modules:
-----------------

Core Module - mod_bmx
    The mod_bmx module is the core BMX module and must be loaded
    in order to support any BMX plugins. It provides base functionality
    for satisfying BMX queries.


BMX Plugins:

mod_bmx_status
    The mod_bmx_status module provides information similar to
    mod_status, such as runtime statistics about the overall health
    of the Apache server and its children.

mod_bmx_vhost
    The mod_bmx_vhost module provides information on the virtual
    hosts running within Apache, such as per-page counts, byte
    counts, error counts, etc. Data is stored and collected for each
    vhost, and also across 3 different time ranges, including
    the time since Apache was last started, the time since Apache
    was last _restarted_, and also for all time. To clear the
    data that mod_bmx_vhost maintains, simply remove the DBM file
    and then restart Apache. See the INSTALL.txt document for
    details.


Example BMX Plugins:

mod_bmx_example
    The mod_bmx_example module is an example BMX plugin that shows
    various ways to satisfy BMX queries and various response data
    types.


API Documentation:
------------------

The BMX Plugin API provides a querying mechanism and a response
mechanism. The query mechanism allows plugins to decide at runtime
if they would like to respond to a particular BMX query. The response
mechanism provides a way for plugins to return data to a querying
client without having to specify the transport mechanism.

Terms:

BMX Plugin
    An BMX Plugin is an Apache Module that depends on the presence
    of the mod_bmx module, and provides some specialized reporting
    of internal Apache metrics and information by returning one or
    more BMX Beans in response to an BMX Query.

BMX Query
    An BMX Query is a request for information from one or more BMX Beans.
    There are three BMX Query types:
        - Request for All Beans
            For example, "*:*"
        - Request for a Specific Bean
            For example, "mod_bmx_vhost:*"
        - Request for a Bean with specific Bean Properties
            For example:
                "mod_bmx_vhost:ServerName=www.example.com"
                "mod_bmx_vhost:Port=80,ServerName=www.example.com"

BMX Objectname
    An BMX Objectname is the name of an BMX Bean and a set of BMX
    Objectname Properties. When represented as a string, the name
    is followed by a colon followed by a comma-separated set of the
    Key=Value pairs from the BMX Properties.

BMX Objectname Properties
    A set of Key-Value pairs that are used to differentiate between
    beans that have the same name.

BMX Bean
    The base container of data metrics, and the smallest unit of
    data that can be requested in an BMX Query.  Beans contain the
    BMX Objectname (with Properties) and a set of Bean Properties.

BMX Bean Properties
    BMX Bean Properties are individual data keys and values. The
    keys are simple string names, and the values can represent any
    data that an BMX Plugin wishes to report about the internal
    metrics of Apache. The BMX API provides a number of portable
    data types, and also provides a way for developers to add their
    own data types.

    Supported Bean Types (mostly portable APR types):
        NULL
            A key without a value.
        boolean
            A simple 'true' or 'false'.
        byte
            A single byte (0-255).
        apr_int16
            A signed 16-bit short.
        apr_uint16
            An unsigned 16-bit short.
        apr_int32
            A signed 32-bit integer.
        apr_uint32
            An unsigned 32-bit integer.
        apr_int64
            A signed 64-bit integer.
        apr_uint64
            An unsigned 64-bit integer.
        float
            A native floating point.
        double
            A native double floating point.
        string
            A character string, null terminated.
        other
            A user-defined data type.


$Id: README.txt,v 1.5 2007/11/05 22:15:44 aaron Exp $