Add documentation for selectable aggregates

[Eoghan Glynn]

The following two blueprints landed for icehouse-3:

  https://blueprints.launchpad.net/ceilometer/+spec/selectable-aggregates
  https://blueprints.launchpad.net/ceilometer/+spec/wider-aggregate-range

extending the statistics API to allow the required aggregate function(s) to be explicitly requested.

The relevant commit messages contain a lot of detail, e.g.:

  https://review.openstack.org/70454
  https://review.openstack.org/76879

but this needs to be also reflected in the API documentation:

  https://github.com/openstack/ceilometer/blob/master/doc/source/webapi/v2.rst

The basic points to cover would be:

(a) how to select a "standard" aggregate, e.g.

  GET /v2/meters/cpu_util/statistics?aggregate.func=avg

(b) how to select an "extended" aggregate, e.g.

  GET /v2/meters/cpu_util/statistics?aggregate.func=stddev
  GET /v2/meters/cpu_util/statistics?aggregate.func=cardinality&aggregate.param=resource_id

(c) what additional aggregation functions are now available, e.g. for mongo & sqlalchemy:

  * stddev: population standard deviation (unparameterized)
  * cardinality: count of distinct values for a sample attribute (parameterized by attribute name)

The set of selectable aggregates supported by the currently configured storage driver can be determined via the capabilities API under "statistics:aggregation:selectable", see:

  https://review.openstack.org/76273

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/80299

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/80299
Committed: https://git.openstack.org/cgit/openstack/ceilometer/commit/?id=654dab111e7c9b960d8cacb8e3cea172a74d2ec1
Submitter: Jenkins
Branch: master

commit 654dab111e7c9b960d8cacb8e3cea172a74d2ec1
Author: Ana Malagon <email address hidden>
Date: Thu Mar 13 10:15:57 2014 -0400

    Added documentation for selectable aggregates

    Documented available aggregate functions
    and added example syntax showing how to use
    improved Statistics API, which allows the user to
    selectively access aggregate functions. Also
    documented the Capabilities API, which allows
    the user to find out what functionality is supported
    by their storage driver.

    Closes-Bug: #1290924
    Change-Id: I9739d2102baf6040de017843ae20391c4c9b6fff