Events
======

LXD provides an `/events` endpoint that is upgraded to a streaming websocket
for getting LXD events in real-time. The :class:`~pylxd.Client`'s `events`
method will return a websocket client that can interact with the
web socket messages.

.. code-block:: python

    >>> ws_client = client.events()
    >>> ws_client.connect()
    >>> ws_client.run()

A default client class is provided, which will block indefinitely, and
collect all json messages in a `messages` attribute. An optional 
`websocket_client` parameter can be provided when more functionality is
needed. The `ws4py` library is used to establish the connection; please
see the `ws4py` documentation for more information.

The stream of events can be filtered to include only specific types of
events, as defined in the LXD /endpoint `documentation <https://github.com/lxc/lxd/blob/master/doc/rest-api.md#10events>`_.

To receive all events of type 'operation' or 'logging', generated by the
LXD server:

.. code-block:: python

   >>> filter = set([EventType.Operation, EventType.Logging])
   >>> ws_client = client.events(event_filter=filter)

To receive only events pertaining to the lifecycle of the containers:

.. code-block:: python
		
   >>> filter = set([EventType.Lifecycle])
   >>> ws_client = client.events(event_filter=filter)
