NotificationEventExamples

= Notification Examples and Quick Reference: =

Tips:

 * Notifications generated by Nova are generated in JSON format, and placed on an AMQP queue.
 * An external app, such as Yagi can format them into ATOM format and publish them as a feed.
 * Notifications can be immediate notifications, which are generated when a specific event happens, or periodic notifications, which cover usage over a period of time.
 * Currently most notifications are immediate, with the "compute.instance.exists" event being the only periodic event so far.
 * Notifications all contain some metadata, (such as event type, and message id), and payload which varies depending on message type.
 * Nova will often emit two immediate notifications for many tasks, one as the beginning of a lengthy task, such as instance create, and one upon successful completion of that task. The event types will distinguish the two.

Immediate Notifications:
{"event_type": "compute.instance.resize.confirm.start", "timestamp": "2012-03-12 17:01:29.899834", "message_id": "1234653e-ce46-4a82-979f-a9286cac5258", "priority": "INFO", "publisher_id": "compute.compute-1-2-3-4", "payload": {"state_description": "", "display_name": "testserver", "memory_mb": 512, "disk_gb": 20, "tenant_id": "12345", "created_at": "2012-03-12 16:55:17", "instance_type_id": 2, "instance_id": "abcbd165-fd41-4fd7-96ac-d70639a042c1", "instance_type": "512MB instance", "state": "active", "user_id": "67890", "launched_at": "2012-03-12 16:57:29", "image_ref_url": "http://127.0.0.1:9292/images/a1b2c3b4-575f-4381-9c6d-fcd3b7d07d17"}}

{"event_type": "compute.instance.create.end", "timestamp": "2012-03-12 17:00:24.156710", "message_id": "00004e00-8da5-4c39-8ffb-c94ed0b5278c", "priority": "INFO", "publisher_id": "compute.compute-1-5-6-7", "payload": {"state_description": "", "display_name": "testserver", "memory_mb": 512, "disk_gb": 20, "tenant_id": "12345", "created_at": "2012-03-12 16:58:32", "instance_type_id": 2, "instance_id": "abcdef01-7b76-4b43-9143-fb2385df48a3", "instance_type": "512MB instance", "state": "active", "user_id": "67890", "fixed_ips": [{"floating_ips": [], "meta": {}, "type": "fixed", "version": 6, "address": "fe80::1234:5678"}, {"floating_ips": [], "meta": {}, "type": "fixed", "version": 4, "address": "127.0.1.1"}, {"floating_ips": [], "meta": {}, "type": "fixed", "version": 4, "address": "10.180.0.151"}], "launched_at": "2012-03-12 17:00:23.998518", "image_ref_url": "http://127.0.0.1:9292/images/12345678-201f-4600-b5a1-0b97e2b1cb31"}}

Periodic Notifications:

 * These notifications cover events, such as usage over a range of time. The period covered by such an event is called the audit period. Generally, these periodic notifications are generated by a a periodic task in the worker process (i.e. nova-compute) or a cronjob once per audit period from cron. Nova has the notion of a system-wide audit period set in it's config file. Nova will collect and aggregate statistics, such as bandwidth usage over that period. When the periodic events are generated, they will be generated for the most recently completed audit period. (Note that the timing of audit periods is *not* affected by when the script or task is run.)

System audit period: This is configured in Novas config file under the "instance_usage_audit_period" option.

hour    Each hour, for example "2012-03-01 01:00UTC" to "2012-03-01 02:00UTC". day     Daily. For example "2012-03-01 00:00UTC" to "2012-03-02 00:00UTC" month   Monthly. For example: "2012-03-01 00:00UTC" to "2012-04-01 00:00UTC". year    Yearly. For example: "2011-01-01 00:00UTC" to "2012-01-01 00:00UTC".
 * Valid audit periods are:
 * May be suffixed with @ to specify minute of hour. (for example hour@30 for 01:30UTC-02:30UTC)
 * May be suffixed with @ to specify hour of day. (for example day@6 for "2012-03-01 06:00UTC" to "2012-03-02 06:00UTC")
 * May be suffixed with @ to specify day of month. (for example month@15 for "2012-03-15 00:00UTC" to "2012-04-15 00:00UTC")
 * May be suffixed with @ to specify month. (for example year@4 for "2011-04-01 00:00UTC" to "2012-04-01 00:00UTC")

Examples:

{"event_type": "compute.instance.exists", "timestamp": "2012-03-13 17:01", "message_id": "0ab1ac0a-2867-402d-83c7-d7087262470c", "priority": "INFO", "publisher_id": "api.node-127-0-1-42", "payload": {"state_description": "", "display_name": "testserver", "memory_mb": 512, "disk_gb": 20, "audit_period_beginning": "2012-03-12 06:00:00", "audit_period_ending":  "2012-03-13 06:00:00", "tenant_id": "12345", "created_at": "2012-03-12 16:55:17", "instance_type_id": 2, "bandwidth": {"public": {"bw_in": 12342000, "bw_out": 987654321}, "private": {"bw_in": 0, "bw_out": 0}}, "instance_id": "8888eeee-f1d0-4fd7-96ac-d70639a042c1", "instance_type": "512MB instance", "state": "active", "user_id": "67890", "launched_at": "2012-03-12 16:57:29", "image_ref_url": "http://127.0.0.1:9292/images/a3a2a1a0-575f-4381-9c6d-fcd3b7d07d17"}}

Detailed explanation of example:

This is a compute.instance.exists event (currently the only periodic event we have).

These are generated periodically, one event for each instance active during the most recently completed audit period.

These can be used to synchronize an external system's picture of what instances a nova installation has running. This info can be obtained from the compute.instance.(create|delete).end events, but exists allows you to do instance accounting without looking at notification data more than 1 audit period old. This event also contains bandwidth usage data.

Some of the data in this specific event:


 * timestamp:    This specific event was generated at 17:01 utc on March 13th (presumably when the cronjob ran)
 * audit_period_(beginning|ending): It covers the audit period from 06:00 utc on March 12th, thru the same time on March 13th. (our example system is set for an audit period of "day@6")
 * created_at:    Our example instance was requested to be created at 16:55:17 on March 12th
 * launched_at:    It actually booted up at 16:57:29 on March 12th
 * bandwidth:      Our example instance has two virtual network interfaces. In this audit period, the interface plugged into the network named "public" received 12.3MB of traffic. It transmitted 987.6MB. The interface plugged into the network named "private" did not receive or transmit any data.