From 641f4b7f3097556e69b51bf063087d5a9f44e44e Mon Sep 17 00:00:00 2001 From: Phil Neal Date: Mon, 11 Aug 2014 16:37:45 -0600 Subject: [PATCH] Document the standard for PaaS service notifications This spec defines a minimum data set and optional fields to be included in the notification (header+payload) produced by PaaS services. Implements blueprint paas-event-for-ceilometer Change-Id: I44218e7f8e67bbb459bd7fa2eda2c7ab06fffef9 --- doc/source/events.rst | 5 +- doc/source/format.rst | 340 ++++++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 3 files changed, 345 insertions(+), 1 deletion(-) create mode 100644 doc/source/format.rst diff --git a/doc/source/events.rst b/doc/source/events.rst index 96c73c95..c74665e7 100644 --- a/doc/source/events.rst +++ b/doc/source/events.rst @@ -40,7 +40,10 @@ consistently (you do not want to lose one). Event Structure =============== -Events contain the following information: +To facilitate downstream processing (billing and/or aggregation), a +:doc:`minimum required data set and format ` has been defined for +services, however events generally contain the following information: + event_type A dotted string defining what event occurred, such as "compute.instance.resize.start" diff --git a/doc/source/format.rst b/doc/source/format.rst new file mode 100644 index 00000000..bdced9cc --- /dev/null +++ b/doc/source/format.rst @@ -0,0 +1,340 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +================= +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" + } + } + diff --git a/doc/source/index.rst b/doc/source/index.rst index 8bf6a431..e0905112 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -49,6 +49,7 @@ Table of contents architecture measurements events + format install/index configuration webapi/index