From 3abe3e830d64a6bd4bf3804b1b35cca7c9447204 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Fri, 28 Apr 2017 20:51:46 -0400 Subject: [PATCH] Add firehose docs for ansible events This commit adds documentation for the ansible events we're now publishing into the firehose. This includes full schema documentation explaining the topics and payloads. Change-Id: I85e27f1c27895c8c25bb34072481f4f75911d815 --- doc/source/firehose.rst | 3 + doc/source/firehose_schema.rst | 246 +++++++++++++++++++++++++++++++++ 2 files changed, 249 insertions(+) diff --git a/doc/source/firehose.rst b/doc/source/firehose.rst index 4234c86db1..888085babd 100644 --- a/doc/source/firehose.rst +++ b/doc/source/firehose.rst @@ -76,6 +76,8 @@ As of right now the following services publish messages to the firehose: +----------------+-----------------+---------------------------+ | Service | Base Topic | Source of Messages | +================+=================+===========================+ +| ansible | ansible | `ansible_mqtt_plugin`_ | ++----------------+-----------------+---------------------------+ | gerrit | gerrit | `germqtt`_ | +----------------+-----------------+---------------------------+ | launchpad | launchpad | `lpmqtt`_ | @@ -86,6 +88,7 @@ As of right now the following services publish messages to the firehose: .. _germqtt: http://git.openstack.org/cgit/openstack-infra/germqtt/ .. _lpmqtt: http://git.openstack.org/cgit/openstack-infra/lpmqtt/ .. _subunit-gearman-worker: http://git.openstack.org/cgit/openstack-infra/puppet-subunit2sql/tree/files/subunit-gearman-worker.py +.. _ansible_mqtt_plugin: http://git.openstack.org/cgit/openstack-infra/system-config/tree/modules/openstack_project/files/puppetmaster/mqtt.py For a full schema description see :ref:`firehose_schema` diff --git a/doc/source/firehose_schema.rst b/doc/source/firehose_schema.rst index 9f64da77a5..bf3da9817c 100644 --- a/doc/source/firehose_schema.rst +++ b/doc/source/firehose_schema.rst @@ -149,3 +149,249 @@ An example is:: 'build_uuid': '45f7c1ddbfd74c6aba94662623bd61b8' 'source_url': 'A url', } + +Ansible +======= + +We have mqtt events emitted from ansible being run on +:ref:`puppetmaster.openstack.org`. These events are generated using a +`MQTT Ansible Callback Plugin`_. + +.. _MQTT Ansible Callback Plugin: http://git.openstack.org/cgit/openstack-infra/system-config/tree/modules/openstack_project/files/puppetmaster/mqtt.py + +Topics +------ + +The topics for ansible are a bit more involved than some of the other services +publishing to firehose. It depends on the type of event that ansible just +finished. There are 3 categories of events which have slightly different topic +formulas (and payloads). + +Playbook Events +''''''''''''''' +Whenever a playbook action occurs the callback plugin will emit an event for +it. The topics for playbook events fall into this pattern:: + + ansible/playbook//action// + +``playbook uuid`` is pretty self explanatory here, it's the uuid ansible uses +to uniquely identify the playbook being run. ``playbook action`` is the action +that the event is for, this is either going to be ``start`` or ``finish``. +``status`` is only set on ``finish`` and will be one of the following: + + * ``OK`` + * ``FAILED`` + +to indicate whether the playbook succesfully executed or not. + +Playbook Stats Events +''''''''''''''''''''' + +At the end of a playbook these events are emitted for each host that tasks were +run on. The topics for these events fall into the following pattern:: + + ansible/playbook//stats/ + +In this case ``playbook uuid`` is the same as above and the internal ansible +unique playbook identifier. ``hostname`` here is the host that ansible was +running tasks on as part of the playbook. + +Task Events +''''''''''' + +At the end of each individual task the callback plugin will emit an event. Those +events' topics fall into the following pattern:: + + ansible/playbook//task// + +``playbook uuid`` is the same as in the previous 2 event types. ``hostname`` is +the hostname the task was executed on. ``status`` is the result of the task +and will be one of the following: + + * ``OK`` + * ``FAILED`` + * ``UNREACHABLE`` + +Payload +------- + +Just as with the topics the message payloads depend on the event type. Each +event uses a JSON payload with slightly different fields. + +Playbook Events +''''''''''''''' + +For playbook events the payload falls into this schema on playbook starts:: + + { + "status": "OK", + "host": + "session": , + "playbook_name": , + "playbook_id": , + "ansible_type": "start", + } + +When a playbook finishes the payload is slightly smaller and the schema is:: + + { + "playbook_id": , + "playbook_name": , + "status": , + } + +In both cases ``playbook uuid`` is the same field from the topic. +``playbook name`` is the human readable name for the playbook. If one is +set in the playbook this will be that. ``status`` will be whether the +playbook was successfully executed or not. It will always be ``OK`` on starts +(otherwise the event isn't emitted) but on failures, just like in the topic, +this will be one of the following: + + * ``OK`` + * ``FAILED`` + +``session id`` is a UUID generated by the callback plugin to uniquely identify +the execution of the playbook. ``hostname`` is the hostname where the ansible +playbook was launched. (which is not necessarily where tasks are being run) + + +An example of this from the system is for a start event:: + + { + "status": "OK", + "playbook_name": "localhost:!disabled", + "ansible_type": "start", + "host": "puppetmaster.openstack.org", + "session": "14d6e568-2c75-11e7-bd24-bc764e048db9", + "playbook_id": "5a95e9da-8d33-4dbb-a8b3-a77affc065d0" + } + +and for a finish:: + + { + "status": "FAILED", + "playbook_name": "compute*.ic.openstack.org:!disabled", + "playbook_id": "b259ac6d-6cb5-4403-bb8d-0ff2131c3d7a" + } + + +Playbook Stats Events +''''''''''''''''''''' + +The schema for stats events is:: + + { + "host": , + "ansible_host": , + "playbook_id": , + "playbook_name": , + "stats": { + "unreachable": int, + "skipped": int, + "ok": int, + "changed": int, + "failures": int, + } + } + +``playbook uuid`` is the same field from the topic. ``playbook name`` is the +human readable name for the playbook. If one is set in the playbook this will be +that. ``execute hostname`` is the hostname where the tasks were being executed, +while ``hostname`` is the hostname where ansible launched the playbook. The +``stats`` subdict contains the task status counts where the key is the tasks +statuses. + +An example from the running system is:: + + { + "playbook_name": "compute*.ic.openstack.org:!disabled", + "host": "puppetmaster.openstack.org", + "stats": { + "unreachable": 0, + "skipped": 5, + "ok": 13, + "changed": 1, + "failures": 0 + }, + "playbook_id": "b259ac6d-6cb5-4403-bb8d-0ff2131c3d7a", + "ansible_host": "controller00.vanilla.ic.openstack.org" + } + + +Task Events +''''''''''' + +The schema for tasks events is:: + + { + "status": , + "host": , + "ansible_host": , + "session": , + "ansible_type": "task", + "playbook_name": , + "playbook_id": , + "ansible_task": , + "ansible_result": + } + +``playbook uuid`` is the same field from the topic. ``playbook name`` is the +human readable name for the playbook. If one is set in the playbook this will be +that. ``execute hostname`` is the hostname where the tasks were being executed, +while ``hostname`` is the hostname where ansible launched the playbook. ``task +name``, like the name implies, is the human readable name of the task executed. +If one was specified in the playbook that will be the value. ``status`` is the +result of the task and will be one of the following: + + * ``OK`` + * ``FAILED`` + * ``UNREACHABLE`` + +``session id`` is a UUID generated by the callback plugin to uniquely identify +the execution of the playbook. + +``ansible result`` is a free form subdict that comes directly from ansible to +completely describe the task that just finished. The structure here is fully +dependent on ansible internals and the way that the task was invoked in the +playbook. Note, that sometimes this can be quite large in size depending on the +task and whether facts were enabled or not. + +An example of a task event from the running system is:: + + { + "status": "OK", + "host": "puppetmaster.openstack.org", + "session": "092aa3fa-2c73-11e7-bd24-bc764e048db9", + "playbook_name": "compute*.ic.openstack.org:!disabled", + "ansible_result": { + "_ansible_parsed": true, + "_ansible_no_log": false, + "stdout": "", + "changed": false, + "stderr": "", + "rc": 0, + "invocation": { + "module_name": "puppet", + "module_args": { + "logdest": "syslog", + "execute": null, + "facter_basename": "ansible", + "tags": null, + "puppetmaster": null, + "show_diff": false, + "certname": null, + "manifest": "/opt/system-config/production/manifests/site.pp", + "environment": "production", + "debug": false, + "noop": false, + "timeout": "30m", + "facts": null + } + }, + "stdout_lines": [] + }, + "ansible_type": "task", + "ansible_task": "TASK: puppet : run puppet", + "playbook_id": "b259ac6d-6cb5-4403-bb8d-0ff2131c3d7a", + "ansible_host": "compute014.chocolate.ic.openstack.org" + }