Monasca Specifications
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

monasca-events-listener.rst 24KB

Monasca Events Listener!/story/2003023

Monasca Events API1 was developed to store event data in Elasticsearch. A new application could use the Monasca Events API to post an event directly for processing and storage. However, a general collection service is needed to capture the existing OpenStack Notifications already generated by OpenStack Services and pass them to Monasca for storage and processing. This specification proposes creating a new Monasca Events Listener to capture events and pass them to Monasca services.

Problem description

All Openstack services generate a lot of notifications or events which contain large amounts of operational and state information about the service and its resources. Services such as Nova2 already publish to a RabbitMQ topic. This notification data is not currently available in Monasca.

Ceilometer data processing pipeline3 provides an extensible mechanism of publishing samples and events using a custom publisher. Ceilometer samples represent a quantity that can be measured (e.g. the size of a volume) and events represent an occurrence of an event and do not have any associated quantity (e.g. volume was created). The Telemetry project also has the Panko4 service for indexing and storing these events.

A previous spec was created to specify an enhancement to Ceilometer to allow collected events to be published to the Monasca Events API. However, with the recent deprecation of Ceilometer's Event functionality5, this is no longer a long-term option.

This spec is for creating a new Monasca service which would listen for OpenStack Event messages (often called notifications) and process them through Monasca by consuming the RabbitMQ message and producing a post to the Monasca Events API with that event.

This service could use Ceilometer, Vitrage, Watcher, or another service as an example of how to listen to notifications from OpenStack services such as Nova6.

It is being proposed to make the Monasca Events Listener service a part of the Monasca Agent code base and reuse code, including the existing monasca_setup script and config.

Use Cases

  1. Openstack notification data would be stored in Elasticsearch via the Monasca services

    Example sequence:

    1. Nova completes the creation of a VM
    2. Nova generates a Notification message to oslo.messaging
    3. oslo.messaging posts the message to RabbitMQ
    4. Monasca Event Listener receives the Notification message from RabbitMQ
    5. Monasca Event Listener validates and translates the Notification to a Monasca Events API format according to the configuration
    6. Monasca Event Listener publishes formatted Notification to Monasca Events API
    7. Monasca Events API receives and validates formatted Notification
    8. Monasca Events API stores event Notification in configured Elasticsearch instance

Proposed change

  1. Monasca Event Listener will be a new service which can be run in a Highly Available configuration by running an instance of Monasca Event Listener on each Controller node in a cloud. Each node will listen to OpenStack notifications in RabbitMQ and convert notifications to a post to the Monasca Events API. The Monasca Events API then passes the notification on as Kafka messages on the 'monevents' topic, where the Monasca Persister will receive and store them. By the nature of RabbitMQ clients, the load will be distributed between the Monasca Events Listener instances (only one listener will process each RabbitMQ message).
  2. Monasca Event Listener will filter messages from OpenStack services based on specification of event_types to be collected. This will reduce 'noise' and focus event collection on those events that are deemed valuable. This filtering specification can be from a configuration file, or optionally could be controlled through a new API implemented as part of the Monasca Events API service.
  3. OpenStack Notifications consist of envelope and payload fields. See7 and8 for examples.

    Example OpenStack Notification data format:

        "_context_auth_token": "42630b3ea13242fcad20e0a92d0207f1",
        "_context_domain": null,
        "_context_instance_lock_checked": false,
        "_context_is_admin": true,
        "_context_project_domain": null,
        "_context_project_id": "a4f77",
        "_context_project_name": "admin",
        "_context_quota_class": null,
        "_context_read_deleted": "no",
        "_context_read_only": false,
        "_context_remote_address": "",
        "_context_request_id": "req-5948338c-f223-4fd8-9249-8769f7a3e460",
        "_context_resource_uuid": null,
        "_context_roles": [
        "_context_service_catalog": [
                "endpoints": [
                        "adminURL": "",
                        "internalURL": "",
                        "publicURL": "",
                        "region": "region1"
                "name": "cinderv2",
                "type": "volumev2"
                "endpoints": [
                        "adminURL": "",
                        "internalURL": "",
                        "publicURL": "",
                        "region": "region1"
                "name": "cinder",
                "type": "volume"
        "_context_show_deleted": false,
        "_context_tenant": "a4f77",
        "_context_timestamp": "2015-09-18T20:54:23.468522",
        "_context_user": "be396488c7034811a200a3cb1d103a28",
        "_context_user_domain": null,
        "_context_user_id": "be396488c7034811a200a3cb1d103a28",
        "_context_user_identity": "be396488c7034811a200a3cb1d103a28 a4f77 - - -",
        "_context_user_name": "admin",
        "_unique_id": "ff9699d587bf4283a3c367ab88be1541",
        "event_type": "compute.instance.create.start",
        "message_id": "c6149ba1-34b3-4367-b8c2-b1d6f073742d",
        "payload": {
            "access_ip_v4": null,
            "access_ip_v6": null,
            "architecture": null,
            "availability_zone": null,
            "cell_name": "",
            "created_at": "2015-09-18 20:55:25+00:00",
            "deleted_at": "",
            "disk_gb": 1,
            "display_name": "testeee",
            "ephemeral_gb": 0,
            "host": null,
            "hostname": "testeee",
            "image_meta": {
                "base_image_ref": "df0c8",
                "container_format": "bare",
                "disk_format": "qcow2",
                "min_disk": "1",
                "min_ram": "0"
            "image_name": "glanceaaa3",
            "image_ref_url": "",
            "instance_flavor_id": "1",
            "instance_id": "abd2ef5c-0381-434a-8efc-d7b39b28a2b6",
            "instance_type": "m1.tiny",
            "instance_type_id": 4,
            "kernel_id": "",
            "launched_at": "",
            "memory_mb": 512,
            "metadata": {},
            "node": null,
            "os_type": null,
            "progress": "",
            "ramdisk_id": "",
            "reservation_id": "r-1ghilddw",
            "root_gb": 1,
            "state": "building",
            "state_description": "",
            "tenant_id": "a4f77",
            "terminated_at": "",
            "user_id": "be396488c7034811a200a3cb1d103a28",
            "vcpus": 1
        "priority": "INFO",
        "publisher_id": "compute.ccp-compute0001-mgmt",
        "timestamp": "2015-09-18 20:55:37.639023"
  4. All the fields with the prefix of '_context' are the envelope fields, the other interesting fields are
    1. 'message_id' - notification identifier
    2. 'payload' - contains most of the relevant and useful information in JSON format
    3. 'priority' - notification priority
    4. 'publisher_id' - notification publisher
    5. 'timestamp' - notification timestamp
  5. Monasca Event Listener converts the OpenStack notifications to Monasca events format. This format will be suitable for Kafka messaging and will match the expected data fields of the Monasca Persister. This conversion and validation should be common between the Monasca Event Listener and Monasca Event API.
  6. The Kafka client connection will handle communication issues such as reconnections and resending as needed.
  7. Monasca Events API allows a field called 'payload' which can be in an arbitrary nested JSON format. TODO: mappings

    Example Monasca Event Format:

  8. Following fields in Monasca Event data may not be available in the OpenStack notification data format:

    • "service"
    • "dimensions.topic"
    • "event.priority"

    We are proposing removing these fields from Monasca Event format (will be done as a separate spec/implementation process) for the following reasons:

    "service": Currently OpenStack notifications do not specify a service, that generated the notification in a consistent way. It might be possible to create an external mapping file which maps event name to a service but its hard to maintain such mapping over a period of time.

    "dimensions.topic": This field is not available in the source OpenStack notification. However, the Monasca Event Listener may be able to save the RabbitMQ topic that the notification was collected from. In that case, this field should be used.

    "event.priority": This field is not currently available in Ceilometer Event format. It is available in the source OpenStack notification. Note: If we think this field can be useful we can propose adding it to the Monasca Event Listener format.

  9. Following new fields will be added to Monasca Event data as dimensions:
    • "dimensions.publisher_id": Identifier for the publisher that generated the event.
    • "dimensions.user_id": Identifier for user that generated the event.
    • "dimensions.project_id": Identifier of the project that generated the event.
  10. 'hostname' is available in the event payload, but its location might differ from event to event.
  11. The proposed new Monasca Event Listener will have the ability to submit event data in a batch and at a configurable frequency (similar to current samples publisher). The event data will be published if the items in the current batch reach their maximum size (config setting) or if certain time interval has elapsed since the last publish (config setting). This will make sure that the batch does not get huge at the same time there is no significant delay in publishing of the events to Monasca Events API.
  12. Monasca Event Listener will have a configuration file to configure connection information for both RabbitMQ and Monasca Events API.
  13. The "tenant_id" and "user_id" that the notification relates to are available in "payload" section of the notification, and these notifications are generated by each service itself.

    There is no additional "OpenStack-operator-agent" like component or functionality required to fetch that data from the service and publish to monasca event api on behalf of the original tenant. (Ceilometer publishing pipeline simply extracts these "tenant_id" and "user_id" fields from the "payload" and makes those fields available as "tenant_id" and "user_id" traits, which would then be mapped to "dimensions.project_id" and "dimensions.user_id" fields in monasca events format.)

    In other words, original "tenant_id" and "user_id" values are available in the payload of the notification, and will make its way to "dimensions.tenant_id" and "dimensions.user_id" in Monasca Event.


    • Q: Do we need to do anything special to handle multi-tenancy in monasca-events api like being done for metrics9 ? Would original user_id and tenant_id in "dimensions.user_id" and "dimensions.tenant_id" fields in dimensions serve this purpose?
      • A: Monasca Events Listener can start with sending all events to a single "admin" tenant and if required in the future some other process could copy select metrics back to tenant projects.
    • Q: In Ceilometer V2 API (which has been deprecated and removed), when querying data the role "admin" could access data for all tenants, whereas a user with "ceilometer-admin" role could access only data for a particular tenant. Can we implement something like this for monasca-events api when querying for data?
      • A: In Monasca API every request is scoped to the project, so there is no equivalent of Ceilometer's "admin" role to query data for all projects. So placing all events in to an "admin" project may be the best approach.
    • Q: How should services which generate notifications but do not include a tenant_id be handled? For example Keystone10. How does Ceilometer handle such events?
      • A: If all events are in an "admin" project then admin metrics like shared ceph cluster load or provider network load can be copied back to tenants so they may understand how infrastructure is affecting their workload.
    • Note: Configuration of Elasticsearch cluster is out of scope for this spec. If needed could assign a separate Elasticsearch cluster to the events API to avoid overloads.

Alternative Solutions

  1. Reuse the Ceilometer functionality to collect and publish events to the Monasca Events API. While this may be less work initially, Ceilometer has deprecated the Events functionality as of Stein.11
  2. An alternate Events Listener was proposed that would listen for RabbitMQ events then publish them directly to the 'monevents' topic in Kafka. Discussion on this can be seen in the git history for this document and in IRC logs12.


    • A much simpler approach, more efficient that HTTP hop through another service.
    • No need for batching in service, as RabbitMQ and Kafka clients would handle fast throughput and short network interruptions.


    • Nova Cells v2 each have their own RabbitMQ instances. While most deployments would likely have a centralized RabbitMQ, it is not required in the documented architecture.
    • Regions may also cause separation of RabbitMQ instances that need to be monitored.
    • While it might be possible to have a service/agent in each Cell publish back to a centralized to Kafka directly, our authentication and networking for Kafka was not designed to support that.
  3. OpenStack Panko13 is a event storage and REST API for Ceilometer and could be used instead of a Monasca solution.


    • An 'official' subproject within Telemetry, so there is some community recognition.


    • Its primary storage is in a relational database which has problems with scale.
    • It is not maintained actively and not ready for production.14
    • It will be deprecated eventually.15

Data model impact


REST API impact

  1. We are proposing to tweak the Monasca Event data format by removing and adding following fields as mentioned in "Proposed change" section above.

    Remove fields or make them optional (JSON path notation): "service", "dimensions.topic", "dimensions.hostname" and "event.priority"

    Add fields (JSON path notation): "dimensions.publisher_id", "dimensions.user_id" and "dimensions.project_id"

    This change will have an impact on Monasca Events API.

Security impact

The proposed Monasca Event Listener will collect and publish OpenStack event (notification) data to Monasca Events API. OpenStack notification data does not have any sensitive data like 'tokens'. Notifications do contain 'user_id' and 'project_id' fields but do not contain any Personally Identifiable Information (PII) for the user or the project.

Other end user impact


Performance Impact

  1. The number of notifications(events) generated by different services will depend on the capacity of the cloud along with the number of resources being created by the users.

    For example, if there was a large number of compute VM's being created or destroyed it could lead to a surge in number of notifications (events) that would have to be published. Optimum configuration options related to say event batch size and event batch interval would have to be documented, to reduce any adverse affect on performance.

  2. The proposed Monasca Event Listener is a new service, so performance is unknown. However, the Monasca API has been shown to have a high performance throughput.

Other deployer impact

  1. The proposed Monasca Event Listener will introduce a few new configuration options like
    • RabbitMQ connection information
    • Monasca Events API endpoint URL
    • events batch interval
    • events batch size
    • events retry interval
    • Keystone credentials for obtaining a token
    • Conversion options for OpenStack notifications to the Monasca Event format. This may be stored in separate pipeline configuration files, similar to how transform specs are configured in Monasca Transform.
  2. As part of developing new Monasca Event Listener devstack plugin would be updated to add the above configuration changes.

Developer impact

  1. The proposed change to Monasca Event Format will have an impact on existing Monasca Event API, since Monasca Event Format will have to be tweaked. (See REST API Impact section above)



Primary assignee:

joadavis, aagate

Other contributors:

<launchpad-id or None>

Work Items

  1. Implement new Monasca Event Listener.
    • Connection to RabbitMQ for OpenStack Notifications
    • Add filtering of notifications for configured event_types
      • Specification in configuration file
      • (Optional) Creation of a new API to configure event_type subscriptions
    • Validation of OpenStack Notification data and format
    • Conversion of data format to meet Monasca Events requirements
    • Publishing to Monasca Events API
    • Configuration of conversion specifications per-event type
  2. Implement monasca devstack plugin changes to deploy new Events Listener service.
  3. Implement unit tests for Monasca Event Listener.




  1. New Monasca Event Listener unit tests will be added, which can test publishing with various config options events batch size, events batch interval, handling retry when Monasca Event API is not available.
  2. Adding tempest tests for Monasca Event Listener could be looked at as part of separate effort.

Documentation Impact

  1. New Monasca Event Listener config options will be documented
  2. Recommended values for each of the config options will also be documented based on the size of the cloud and resources for Cloud Operators.


[2] Monasca Ceilometer project:

[4] Ceilometer Events:

[6] Monasca Event Format:

[7] Ceilometer System Architecture Diagram:

[8] Monasca Events POST v1.0 API:

[10] Ceilometer pipeline yaml documentation:

[17] Monasca Events API publisher to Kafka:

  1. Monasca Events API 1.0:

  2. Nova notification version update lists services effected (see "Deprecating legacy notifications"):

  3. Ceilometer Data processing and pipelines:

  4. Openstack Panko:

  5. Ceilometer Events marked as deprecated in Stein:

  6. Nova notification version update lists services effected (see "Deprecating legacy notifications"):

  7. Nova notification reference:

  8. Keystone notification reference:

  9. Cross-Tenant Metric Submission:

  10. Keystone notification reference:

  11. Ceilometer Events marked as deprecated in Stein:

  12. Monasca IRC meeting Dec 15, 2018:

  13. Openstack Panko:

  14. No future for Panko or Aodh:

  15. Ceilometer Events deprecated means Panko also deprecated: