pungi/doc/messaging.rst

.. _messaging:

Progress notification
=====================

*Pungi* has the ability to emit notification messages about progress and
general status of the compose. These can be used to e.g. send messages to
*fedmsg*. This is implemented by actually calling a separate script.

The script will be called with one argument describing action that just
happened. A JSON-encoded object will be passed to standard input to provide
more information about the event. At the very least, the object will contain a
``compose_id`` key.

The script is invoked in compose directory and can read other information
there.

Currently these messages are sent:

 * ``status-change`` -- when composing starts, finishes or fails; a ``status``
   key is provided to indicate details
 * ``phase-start`` -- on start of a phase
 * ``phase-stop`` -- when phase is finished
 * ``createiso-targets`` -- with a list of images to be created
 * ``createiso-imagedone`` -- when any single image is finished
 * ``createiso-imagefail`` -- when any single image fails to create
 * ``fail-to-start`` -- when there are incorrect CLI options or errors in
   configuration file; this message does not contain ``compose_id`` nor is it
   started in the compose directory (which does not exist yet)
 * ``ostree`` -- when a new commit is created, this message will announce its
   hash and the name of ref it is meant for.

For phase related messages ``phase_name`` key is provided as well.

A ``pungi-fedmsg-notification`` script is provided and understands this
interface.

Setting it up
-------------

The script should be provided as a command line argument
``--notification-script``. ::

    --notification-script=pungi-fedmsg-notification
Move messaging into cli options The messaging is not really part of compose settings. It is an infrastructure part. As such, it should really be set up as part of pungi invocation, not compose configuration. The documentation is updated to reflect this. Some updates to the documentation are done as well: listing messages about ISOs and minor formatting updates. The test_compose.sh script can now accept additional command line options and pass them on to pungi-koji to simplify testing. Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2015-11-26 07:45:33 +00:00			`.. _messaging:`

			`Progress notification`
			`=====================`

			`Pungi has the ability to emit notification messages about progress and`
			`general status of the compose. These can be used to e.g. send messages to`
			`fedmsg. This is implemented by actually calling a separate script.`

			`The script will be called with one argument describing action that just`
			`happened. A JSON-encoded object will be passed to standard input to provide`
			`more information about the event. At the very least, the object will contain a`
			``compose_id`` key.

Send notification when compose fails to start This is tricky as this early in the process we don't know the compose ID. The new message gives the full command line that was called. Relates: #439 Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2016-10-20 07:23:10 +00:00			`The script is invoked in compose directory and can read other information`
			`there.`

Move messaging into cli options The messaging is not really part of compose settings. It is an infrastructure part. As such, it should really be set up as part of pungi invocation, not compose configuration. The documentation is updated to reflect this. Some updates to the documentation are done as well: listing messages about ISOs and minor formatting updates. The test_compose.sh script can now accept additional command line options and pass them on to pungi-koji to simplify testing. Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2015-11-26 07:45:33 +00:00			`Currently these messages are sent:`

			* ``status-change`` -- when composing starts, finishes or fails; a ``status``
			`key is provided to indicate details`
			* ``phase-start`` -- on start of a phase
			* ``phase-stop`` -- when phase is finished
			* ``createiso-targets`` -- with a list of images to be created
			* ``createiso-imagedone`` -- when any single image is finished
			* ``createiso-imagefail`` -- when any single image fails to create
Send notification when compose fails to start This is tricky as this early in the process we don't know the compose ID. The new message gives the full command line that was called. Relates: #439 Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2016-10-20 07:23:10 +00:00			* ``fail-to-start`` -- when there are incorrect CLI options or errors in
			configuration file; this message does not contain ``compose_id`` nor is it
			`started in the compose directory (which does not exist yet)`
Update ostree phase documentation The message and the new option were not documented. Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2016-10-27 07:23:58 +00:00			* ``ostree`` -- when a new commit is created, this message will announce its
			`hash and the name of ref it is meant for.`
Move messaging into cli options The messaging is not really part of compose settings. It is an infrastructure part. As such, it should really be set up as part of pungi invocation, not compose configuration. The documentation is updated to reflect this. Some updates to the documentation are done as well: listing messages about ISOs and minor formatting updates. The test_compose.sh script can now accept additional command line options and pass them on to pungi-koji to simplify testing. Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2015-11-26 07:45:33 +00:00
			For phase related messages ``phase_name`` key is provided as well.

			A ``pungi-fedmsg-notification`` script is provided and understands this
			`interface.`

			`Setting it up`
			`-------------`

			`The script should be provided as a command line argument`
			``--notification-script``. ::

doc: Fix a typo in progress notification example Fixes: #435 Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com> 2016-10-19 13:04:02 +00:00			`--notification-script=pungi-fedmsg-notification`