How To Write And Use A PHP Metric
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following sections will describe how to develop and deploy
new metric modules using php. The PHP Embed is required, if you
installed php from the sources make sure you compiled it with
the configure option --enable-embed.

Note : the current implementation of the PHP module for ganglia 
parse the php script each time a metric is gathered.

Writing a php metric module
~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are two functions that must be included in every php based
metric module as well as at least one callback handler.
These functions are:

function metric_init($params) { ... }

  This function will be called once at initialization time. It
  can be used to do any kind of initialization that the module
  requires in order to properly gather the intended metric. This
  function also takes a single array type parameter which 
  contains configuration directives that were designated for 
  this module in the gmond.conf file.  In addition to any other 
  initialization that is done, the function must also create, 
  populate and return the metric description array.
  Each metric description array, must supply at least the
  following elements:
        
    $d = array(
        'name' => '<your_metric_name>',
        'call_back' => '<metric_handler_function>',
        'time_max' => int(<your_time_max>),
        'value_type' => '<string | uint | float | double>',
        'units' => '<your_units>',
        'slope' => '<zero | positive | negative | both>',
        'format' => '<your_format>',
        'description' => '<your_description>'
    );

  These elements are basically the same type of data that must be
  supplied to the gmetric commandline utility with the exception
  of the call_back function. See the gmetric help document for 
  more information.  The call_back entry designates a function 
  that will be called whenever the data for this metric needs to
  be gathered.  The format of this function is very simple.  It 
  is just a function name with a 'name' parameter

    function My_Metric_Handler($name) { ... }

  The value of the name parameter will be the name of the metric
  that is being gathered. This allows a call_back function to
  handle more than one metric and to be able to determine which
  metric is being handled when called. This function implements the 
  code that handles the gathering of the metric data. The return 
  value from this function must match the data value type that was 
  specified in the corresponding metric description that was defined 
  during the metric_init() function.

function metric_cleanup() { ... }

  This function will be called once when gmond is shutting down.
  Any module clean up code can be executed here and the function
  must not return a value.
  
Other than the mandatory functions and metric description array as 
specified above, the metric module is free to do whatever it needs 
in order to appropriately gather the intended metric data. Each 
metric description array can also contain additional user defined
elements outside of the mandatory elements listed above. Any additional
elements in the array will be ignored by mod_php but can to used by
the php module itself to hold additional data that should correspond
to the metric.

Deploying a php metric module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once a php metric module has been developed, deploying the module is as
easy as copying a file to a specific directory. In the configuration of
the mod_php module that is part of gmond.conf, a php metric module
directory must have been specified (see next section). To deploy a 
php module, simply copy the .php file to the specified php module 
directory. Once the php module has been copied, start gmond using the 
-m parameter. This will show a list of all of the available metrics that
gmond is capable of gathering. The list should include the name of the
php module that was just deployed. Add this metric to a collection
group, just like any other gmond metric.

Configuring Gmond for php support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Configuring Gmond to support php based modules is as easy as loading
any other type of gmond dynamically loadable metric module. The name of
the php support module is modphp.so. A base configuration file 
is included in the Ganglia source code and should have been installed
automatically if done through an RPM. The basic configuration that
should be added to or included by gmond.conf in your system is as
follows:

  modules {
    module {
      name = "php_module"
      path = "modphp.so"
      param php_modules_path {
          value = "/usr/local/lib64/ganglia/php_modules"
      }
      /*
      param php_ini_path {
          value = "/etc/php.ini"
      }
      */
    }
  }

  include ("/usr/local/etc/conf.d/*.phpconf")

The php module use two config parameters. The most important one is the
php_modules_path. The path that has been assigned to this directive will
be passed down to the mod_php module and used to search for .php
php modules. Any php module that is found in this location will be loaded
and assumed to be a metric gathering module. If the collection groups that
include metrics that are implemented in php, are put into separate
configuration files and the file extension of the configuration files are
.phpconf, they will automatically be loaded and read whenever the mod_php
module is included. 

Configuring a Gmond php module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The configuration of a Gmond php module is really no different
than any other module.  Most php modules will not require any
specialized configuration at all. However, support has been 
provided to allow for parameters to be passed from the gmond.conf
file to a php module.  The syntax for passing parameters to
a specific php module is at follows:

  modules {
    module {
      name = "example"
      language = "python"
      param YouNameIt {
          value = Whatever
      }
      param Another {
          value = NewValue
      }
    }
  }

The "module" section must contain a "name" directive and a 
"language" directive.  The value of the "name" directive must 
match the file name of the php module's .php file and the 
value of the "language" directive must be "php".  The section 
can take multiple "param" sections.  Each "param" section must 
include a name which will be the name of the value when it is 
passed to the php module, and a "value" directive.  The 
"value" directive will always be passed as a string to the 
php module.  It is up to the module itself to determine the 
actual value type.
