nameko-eventlog-dispatcher 0.4.2
Nameko dependency provider that dispatches log data using Events (Pub-Sub).
License: MIT License
Requires Python: >=3.6

Nameko eventlog dispatcher
==========================

.. pull-quote::

    Nameko_ dependency provider that dispatches log data using ``Events``
    (Pub-Sub).


.. image:: https://img.shields.io/pypi/v/nameko-eventlog-dispatcher.svg
    :target: https://pypi.org/project/nameko-eventlog-dispatcher/

.. image:: https://img.shields.io/pypi/pyversions/nameko-eventlog-dispatcher.svg
    :target: https://pypi.org/project/nameko-eventlog-dispatcher/

.. image:: https://img.shields.io/pypi/format/nameko-eventlog-dispatcher.svg
    :target: https://pypi.org/project/nameko-eventlog-dispatcher/

.. image:: https://travis-ci.org/sohonetlabs/nameko-eventlog-dispatcher.png?branch=master
    :target: https://travis-ci.org/sohonetlabs/nameko-eventlog-dispatcher


Usage
-----

Dispatching event log data
``````````````````````````

Include the ``EventLogDispatcher`` dependency in your service class:

.. code-block:: python

    from nameko.rpc import rpc
    from nameko_eventlog_dispatcher import EventLogDispatcher


    class FooService:

        name = 'foo'

        eventlog_dispatcher = EventLogDispatcher()

        @rpc
        def foo_method(self):
            self.eventlog_dispatcher(
              'foo_event_type', {'value': 1}, metadata={'meta': 2}
            )

Calling ``foo_method`` will dispatch an event from the ``foo`` service
with ``log_event`` as the event type. However ``foo_event_type`` will be
the event type stored as part of the event metadata.

``event_type``, ``event_data`` (optional) and ``metadata`` (optional)
can be provided as arguments. Both ``event_data`` and ``metadata`` must
be dictionaries and contain JSON serializable data.

Then, any Nameko_ service will be able to handle this event.

.. code-block:: python

    from nameko.events import event_handler


    class BarService:

        name = 'bar'

        @event_handler('foo', 'log_event')
        def foo_log_event_handler(self, body):
            """`body` will contain the event log data."""


Capturing log data when entrypoints are fired
`````````````````````````````````````````````

Enable auto capture event logs in your Nameko_ configuration file:

.. code-block:: yaml

    # config.yaml

    EVENTLOG_DISPATCHER:
      auto_capture: true
      entrypoints_to_exclude: []
      event_type: log_event

All the attributes above are optional and only used to override their
default values.

With ``auto_capture`` set to ``true``, a Nameko_ event will be dispatched
every time an entrypoint is fired:

- They can also be handled by listening ``log_event`` events from the
  service dispatching them.
- ``entrypoint_fired`` will be the event type stored as part of the
  event metadata.
- Only entrypoints listed in the ``ENTRYPOINT_TYPES_TO_LOG`` class
  attribute will be logged.
- ``entrypoints_to_exclude`` can be used to provide a list of entrypoint
  method names to exclude when firing events automatically.

``event_type`` can be added to the config to override the default Nameko_
event type used to dispatch this kind of events.

Format of the event log data
----------------------------

This is the format of the event log data:

.. code-block:: python

    {
      "service_name": "foo",
      "entrypoint_protocol": "Rpc",
      "entrypoint_name": "foo_method",
      "call_id": "foo.foo_method.d7e907ee-9425-48a6-84e6-89db19e3ce50",
      "call_stack": [
        "standalone_rpc_proxy.call.3f349ea4-ed3e-4a3b-93d0-a36fbf928ecb",
        "bla.bla_method.21d623b4-edc4-4232-9957-4fad72533b75",
        "foo.foo_method.d7e907ee-9425-48a6-84e6-89db19e3ce50"
      ],

      "event_type": "foo_event_type",  # "entrypoint_fired", ...
      "timestamp": "2017-06-12T13:48:16+00:00",

      "meta": 2,  # extra information provided as "metadata"
      "data": {"value": 1}  # extra information provided as "event_data"
    }

The ``data`` attribute will contain the event data that was provided as
an argument for the ``event_data`` parameter when dispatching the event.

If ``metadata`` was provided, then its elements will be included as top
level attributes in the event log data.


Tests
-----

It is assumed that **RabbitMQ** is up and running on the default URI
``guest:guest@localhost`` and uses the default ports. There is a
Makefile target to run a RabbitMQ docker containers locally using the
default ports and configuration:

.. code-block:: shell

    $ make docker-rabbitmq-run

To run the tests locally:

.. code-block:: shell

    $ # Create/activate a virtual environment
    $ pip install tox
    $ tox

There are other Makefile targets to run the tests, but extra
dependencies will have to be installed:

.. code-block:: bash

    $ pip install -U --editable ".[dev]"
    $ make test
    $ make coverage

A different RabbitMQ URI can be provided overriding the following
environment variables: ``RABBIT_CTL_URI`` and ``AMQP_URI``.

Additional ``pytest`` parameters can be also provided using the ``ARGS``
variable:

.. code-block:: bash

    $ make test RABBIT_CTL_URI=http://guest:guest@dockermachine:15673 AMQP_URI=amqp://guest:guest@dockermachine:5673 ARGS='-x -vv --disable-pytest-warnings'
    $ make coverage RABBIT_CTL_URI=http://guest:guest@dockermachine:15673 AMQP_URI=amqp://guest:guest@dockermachine:5673 ARGS='-x -vv --disable-pytest-warnings'


Nameko support
--------------

The following Nameko_ versions are supported:

- ``2.x`` series: ``2.12``, ``2.13``, ``2.14``


Changelog
---------

Consult the `CHANGELOG <https://github.com/sohonetlabs/nameko-eventlog-dispatcher/blob/master/CHANGELOG.rst>`_
document for fixes and enhancements of each version.


License
-------

The MIT License. See `LICENSE <https://github.com/sohonetlabs/nameko-eventlog-dispatcher/blob/master/LICENSE>`_
for details.


.. _Nameko: http://nameko.readthedocs.org