1818955675
this patch moves some event related topics out of main TOC and into events section. this patch does not remove any information. removal/cleanup of information and restructing of toc will be done in future patch Change-Id: Ic522b9e64c43fbdb5769fd9956cb266571615ecf
342 lines
12 KiB
ReStructuredText
342 lines
12 KiB
ReStructuredText
..
|
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
|
License.
|
|
|
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
|
|
|
|
|
.. _paas_event_format:
|
|
|
|
=================
|
|
PaaS Event Format
|
|
=================
|
|
|
|
There are a number of PaaS services that are currently under development
|
|
and a growing number of applications running on top of OpenStack infrastructure.
|
|
In an effort to avoid significant integration work that would be required if
|
|
each service produced a unique notification payload, we have defined a minimum
|
|
data set that provides the core data elements needed for downstream metering
|
|
processes. This format is not enforced by Ceilometer but serves as an advisory
|
|
guideline for PaaS service developers:
|
|
|
|
::
|
|
|
|
[
|
|
{
|
|
"Field": "event_type",
|
|
"Type": "enumeration",
|
|
"Description": "for event type records, this describes the actual event that occurred",
|
|
"Compliance": "required for events",
|
|
"Notes": "depends on service, defaults to create, exists, delete"
|
|
},
|
|
{
|
|
"Field": "timestamp",
|
|
"Type": "UTC DateTime",
|
|
"Description": "timestamp of when this event was generated at the resource",
|
|
"Compliance": "required",
|
|
"Notes": "ISO 8859 date YYYY-mm-ddThh:mm:ss"
|
|
},
|
|
{
|
|
"Field": "message_id",
|
|
"Type": "String",
|
|
"Description": "unique identifier for event",
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"payload": [
|
|
{
|
|
"Field": "version",
|
|
"Type": "String",
|
|
"Description": "Version of event format",
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "audit_period_beginning",
|
|
"Type": "UTC DateTime",
|
|
"Description": "Represents start time for metrics reported",
|
|
"Compliance": "required",
|
|
"Notes": "Format ISO 8859 date YYYY-mm-ddThh:mm:ss"
|
|
},
|
|
{
|
|
"Field": "audit_period_ending",
|
|
"Type": "UTC DateTime",
|
|
"Description": "Represents end time for metrics reported",
|
|
"Compliance": "required",
|
|
"Notes": "Format ISO 8859 date YYYY-mm-ddThh:mm:ss"
|
|
},
|
|
{
|
|
"Field": "record_type",
|
|
"Type": "enumeration ",
|
|
"Values": {
|
|
"event": "events describe some kind of state change in the service",
|
|
"quantity": "quantity describes a usage metric value"
|
|
},
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "project_id",
|
|
"Type": "UUID",
|
|
"Description": "Keystone project_id identifies the owner of
|
|
the service instance",
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "user_id",
|
|
"Type": "UUID",
|
|
"Description": "Keystone user_id identifies specific user",
|
|
"Compliance": "optional",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "service_id",
|
|
"Type": "UUID",
|
|
"Description": "Keystone service_id uniquely identifies a service",
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "service_type",
|
|
"Type": "String",
|
|
"Description": "Keystone service_type uniquely identifies a service",
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "instance_id",
|
|
"Type": "UUID",
|
|
"Description": "uniquely identifies an instance of the service",
|
|
"Compliance": "required",
|
|
"Notes": "assuming instance level reporting"
|
|
},
|
|
{
|
|
"Field": "display_name",
|
|
"Type": "String",
|
|
"Description": "text description of service",
|
|
"Compliance": "optional",
|
|
"Notes": "used if customer names instances"
|
|
},
|
|
{
|
|
"Field": "instance_type_id",
|
|
"Type": "enumeration",
|
|
"Description": "used to describe variations of a service",
|
|
"Compliance": "required",
|
|
"Notes": "needed if variations of service have different prices or
|
|
need to be broken out separately"
|
|
},
|
|
{
|
|
"Field": "instance_type",
|
|
"Type": "String",
|
|
"Description": "text description of service variations",
|
|
"Compliance": "optional",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "availability_zone",
|
|
"Type": "String",
|
|
"Description": "where the service is deployed",
|
|
"Compliance": "optional",
|
|
"Notes": "required if service is deployed at an AZ level"
|
|
},
|
|
{
|
|
"Field": "region",
|
|
"Type": "String",
|
|
"Description": "data center that the service is deployed in",
|
|
"Compliance": "optional",
|
|
"Notes": "required if service is billed at a regional level"
|
|
},
|
|
{
|
|
"Field": "state",
|
|
"Type": "enumeration",
|
|
"Description": "status of the service at the time of record generation",
|
|
"Compliance": "optional",
|
|
"Notes": "required for existence events"
|
|
},
|
|
{
|
|
"Field": "state_description",
|
|
"Type": "String",
|
|
"Description": "text description of state of service",
|
|
"Compliance": "",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "license_code",
|
|
"Type": "enumeration",
|
|
"Description": "value that describes a specific license model",
|
|
"Compliance": "optional",
|
|
"Notes": "this field is TBD depending on dev_pay design work"
|
|
},
|
|
{
|
|
"metrics": [
|
|
{
|
|
"Field": "metric_name",
|
|
"Type": "String",
|
|
"Description": "unique name for the metric that is represented
|
|
in this record",
|
|
"Compliance": "required",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "metric_type",
|
|
"Type": "enumeration",
|
|
"Description": "gauge, cumulative, delta",
|
|
"Compliance": "required",
|
|
"Notes": "describes the behavior of the metric, from Ceilometer"
|
|
},
|
|
{
|
|
"Field": "metric_value",
|
|
"Type": "Float",
|
|
"Description": "value of metric for quantity type records",
|
|
"Compliance": "required for quantities",
|
|
"Notes": ""
|
|
},
|
|
{
|
|
"Field": "metric_units",
|
|
"Type": "enumeration",
|
|
"Description": "describes the units for the quantity",
|
|
"Compliance": "optional",
|
|
"Notes": ""
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
|
|
|
|
.. note::
|
|
|
|
**Required** means that it must be present and described as in the specification.
|
|
**Optional** indicates it can be present or not, but if present it must be described
|
|
as in the specifications.
|
|
**Audit period timestamps** are not currently enforced against the audit period.
|
|
|
|
Sample Events
|
|
=============
|
|
|
|
The event format listed above is used to deliver two basic types of events:
|
|
*quantity* and *state* events.
|
|
|
|
Sample state events
|
|
-------------------
|
|
|
|
These events describe the state of the metered service. They are very similar to
|
|
the existing state events generated by Infrastructure. Generally there would be at
|
|
least three types of events: create, exists and delete. Examples of these events for
|
|
a DNS service are listed below.
|
|
|
|
``dns.zone.create`` event is sent after a zone has been created::
|
|
|
|
{
|
|
"event_type": "dns.zone.create",
|
|
"time_stamp": "2013-04-07 22:56:30.026191",
|
|
"message_id": 52232791371,
|
|
"payload": {
|
|
"instance_type": "type1",
|
|
"availability_zone": "az1",
|
|
"instance_id": "6accc078-81de-4567-894f-53af5653ac63",
|
|
"audit_period_beginning": "2013-04-07 21:56:32.249876",
|
|
"state": "active",
|
|
"audit_period_ending": "2013-04-07 22:56:32.249712",
|
|
"service_id": "1abbb078-81cd-4758-974e-35fa5653ac63",
|
|
"version": "1.0",
|
|
"tenant_id": "12345",
|
|
"instance_type_id": 1,
|
|
"display_name": "example100.com",
|
|
"message_id": 52232791371,
|
|
"user_id": "6789",
|
|
"state_description": "happy DNS"
|
|
}
|
|
}
|
|
|
|
``dns.zone.exists`` event is sent every hour for existing zones::
|
|
|
|
{
|
|
"event_type": "dns.zone.exists",
|
|
"time_stamp": "2013-04-07 22:56:37.782573",
|
|
"message_id": 52232791372,
|
|
"payload": {
|
|
"instance_type": "type1",
|
|
"availability_zone": "az1",
|
|
"instance_id": "6accc078-81de-4567-894f-53af5653ac63",
|
|
"audit_period_beginning": "2013-04-07 21:56:37.783215",
|
|
"state": "active",
|
|
"audit_period_ending": "2013-04-07 22:56:37.783153",
|
|
"service_id": "1abbb078-81cd-4758-974e-35fa5653ac63",
|
|
"version": "1.0",
|
|
"tenant_id": "12345",
|
|
"instance_type_id": 1,
|
|
"display_name": "example100.com",
|
|
"message_id": 52232791371,
|
|
"user_id": "6789",
|
|
"state_description": "happy DNS"
|
|
}
|
|
}
|
|
|
|
The ``dns.zone.delete`` event is sent when a zone is deleted::
|
|
|
|
{
|
|
"event_type": "dns.zone.delete",
|
|
"time_stamp": "2013-04-07 22:56:37.787774",
|
|
"message_id": 52232791373,
|
|
"payload": {
|
|
"instance_type": "type1",
|
|
"availability_zone": "az1",
|
|
"instance_id": "6accc078-81de-4567-894f-53af5653ac63",
|
|
"audit_period_beginning": "2013-04-07 21:56:37.788177",
|
|
"state": "active",
|
|
"audit_period_ending": "2013-04-07 22:56:37.788144",
|
|
"service_id": "1abbb078-81cd-4758-974e-35fa5653ac63",
|
|
"version": "1.0",
|
|
"tenant_id": "12345",
|
|
"instance_type_id": 1,
|
|
"display_name": "example100.com",
|
|
"message_id": 52232791371,
|
|
"user_id": "6789",
|
|
"state_description": "happy DNS"
|
|
}
|
|
}
|
|
|
|
Sample quantity events
|
|
----------------------
|
|
Quantity events have the same overall format, but additionally have a section
|
|
called metrics which is a section called metrics which is an array of
|
|
information about the meters that the event is reporting on. Each metric entry
|
|
has a type, unit, name and volume. Multiple values can be reported in one
|
|
event.
|
|
|
|
``dns.zone.usage`` is hourly event sent with usage for each zone instance::
|
|
|
|
{
|
|
"event_type": "dns.zone.usage",
|
|
"time_stamp": "2013-04-08 10:05:31.618074",
|
|
"message_id": 52232791371,
|
|
"payload": {
|
|
"metrics": [
|
|
{
|
|
"metric_type": "delta",
|
|
"metric_value": 42,
|
|
"metric_units": "hits",
|
|
"metric_name": "queries"
|
|
}
|
|
],
|
|
"instance_type": "type1",
|
|
"availability_zone": "az1",
|
|
"instance_id": "6accc078-81de-4567-894f-53af5653ac63",
|
|
"audit_period_beginning": "2013-04-08 09:05:31.618204",
|
|
"state": "active",
|
|
"audit_period_ending": "2013-04-08 10:05:31.618191",
|
|
"service_id": "1abbb078-81cd-4758-974e-35fa5653ac63",
|
|
"version": "1.0",
|
|
"tenant_id": "12345",
|
|
"instance_type_id": 1,
|
|
"display_name": "example100.com",
|
|
"message_id": 52232791371,
|
|
"user_id": "6789",
|
|
"state_description": "happy DNS"
|
|
}
|
|
}
|