..
 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"
                }
    }