Ceilometer/blueprints/Ceilometer-api-extensions

Introduction
There are some gaps that we see in the capabilities of the Ceilometer API when we align it against our use cases. The following are proposed extensions to the API which we believe will bring about better functionality for the community of Ceilometer users and eliminate scaling issues.

Targeted Use Cases
Usage Reporting is our primary use case for the proposed API extensions. We would like to use an implementation of the Ceilometer API as the front end for our reporting service. The following requests illustrate the need for this functionality:


 * End Customer Usage Reporting
 * Ability to see a summary of my month-to-date (MTD) usage on a Dashboard - this would include one summary per Region with MTD totals for one or more usage metrics for each service
 * Ability to see a graphical and/or tabular summary of my usage per service for a specified month - I can specifiy the interval that the data is displayed at (i.e. per week, day, hour).
 * Ability to further drill down into the usage report to see reports by
 * service characteristics (i.e. compute flavor, application type, operating system type, volume type, ...)
 * location (region and availability zone)
 * instance level (specific instance for the service, i.e. VM, volume, storage container, ...)
 * Internal Provider Reporting
 * Ability to generate a monthly report of service usage (all usage by service plus drill down by service and customer characteristics)
 * Ability to generate licensing related reports (number of nodes, VM, tenants running a specified operating system or application type)

Proposed API Updates
In order to support the specified use cases, a set of API updates and extensions are needed.

API Extensions and Rationale
The following extensions are proposed:
 * Add support for passing in an interval parameter as part of the query. This will allow a client to query for a larger set of data with a single call. Currently the client would have to make a single call for each time period they want to report on. This will generate a large number of queries and resulting traffic. An example of this would be to query for compute CPU usage for a one month period but slice the returned data by week. The returned information would contain a value for each week in the time period that was specified by the start and end dates in the query.
 * This seems like it serves a similar purpose to the "period" argument added to the statistics API recently. -- dhellmann
 * For example:

../projects/(project)/meter/obj.size?start=2011-09-01T12:00:00&end=2011-10-26T12:00:00&op=sum&interval=day : returns a series of data for the specified period summed into day increments
 * Add support for concept of location (region, availability zone, etc.). Providers will be deploying their services in multiple regions and availability zones. Usage in different locations will potentially be charged differently. The data model and API need to be able to support queries using the location characteristics as search criteria.
 * Doesn't the query argument to /v2/resources handle this? -- dhellmann
 * This assumes the region info is stored in metadata and could be filtered to select in the query? If so, I think it would work.  -- epende
 * For example:

.../projects/(project)/resources/ : returns a list of all known project names for the given region
 * Add support for the concept of a multi-tier account hierarchy: The current hierarchy in OpenStack is limited to tenants and users**. The metering of large-scale OpenStack implementations relies on being able to distinguish between different clusters of active services. Providers are adding additional layers of account hierarchy to allow their customers to manage their accounts and billing relationships with more granularity. This additional account hierarchy will be relevant to customers usage reporting requirements and thus needs to be able to be stored and accessed in Ceilometer.
 * FWIW, the v1 API won't change during Havana (it is being deprecated), so think in terms of the v2 API. -- dhellmann
 * For example:

../projects/(project)/resources/object.loc?loc=AZ1 : returns a list of project-specific resources filtered by location or in API v2: ../the API v2 equivalent
 * Add support for concept of service types. The current implementation is focused on base OpenStack services, the next logical step is to start to deploy chargeable applications on top of the OpenStack infrastructure. Being able to extract this information via the API will require the ability to enumerate the service types available and then specify a service type in the query.
 * Why does this require a new data model ("service type") instead of using a new meter name and listing the service type as part of the metadata for the resource? -- dhellmann
 * For example:

.../serviceTypes : returns a list of service types that are available in the system .../serviceTypes/{serviceType}/projects: list of projects that have this service type .../projects/{project}/serviceTypes/: list of service types used by this project .../serviceTypes/{serviceType}/projects/{project}/instances: list of instances for the specified project that have this service type .../serviceTypes/{serviceType}/instances: list of instances for all projects that have this service type (should also be able to filter on project)
 * Add support for requesting meter types available for a given service: Provides a programmatic check for what meters are available for a given service on an instance.
 * For example:

.../serviceTypes/(serviceType)/meters : returns a list of meters that are currently implemented on the service

© Copyright 2013 Hewlett-Packard Development Company, L.P.