Skip to main content

A Riemann client and command line tool

Project description


.. image::

.. image::

.. image::


A `Riemann <>`_ client library and command line tool for
Python. It supports UDP and TCP transports, queries, and all metric types.
The client library aims to provide a simple, minimal API, and does not
require direct interaction with protocol buffers. There is also a queued
client that can queue or batch events and then send them in a single message.

* `Source on GitHub <>`_
* `Documentation on Read the Docs <>`_
* `Packages on PyPI <>`_


As a command line tool::

riemann-client [--host HOST] [--port PORT] send [-s SERVICE] [-S STATE] [-m METRIC] [...]
riemann-client [--host HOST] [--port PORT] query QUERY

The host and port used by the command line tool can also be set with the
``RIEMANN_HOST`` and ``RIEMANN_PORT`` environment variables. By default,
``localhost:5555`` will be used.

As a library::

import riemann_client.client

with riemann_client.client.Client() as client:
client.event(service="riemann-client", state="awesome")
client.query("service = 'riemann-client'")

A more detailed example, using both a non-default transport and a queued

from riemann_client.transport import TCPTransport
from riemann_client.client import QueuedClient

with QueuedClient(TCPTransport("localhost", 5555)) as client:
client.event(service="one", metric_f=0.1)
client.event(service="two", metric_f=0.2)

The ``QueuedClient`` class modifies the ``event()`` method to add events to a
queue instead of immediately sending them, and adds the ``flush()`` method to
send the current event queue as a single message.


``riemann-client`` requires Python 2.6 or above, and can be installed with
``pip install riemann-client``. It will use Google's `protobuf`_ library when
running under Python 2, and `GreatFruitOmsk`_'s `protobuf-py3`_ fork when
running under Python 3. Python 3 support is experimental and is likley to use
Google's `protobuf` once it supports Python 3 fully.

.. _protobuf:
.. _GreatFruitOmsk:
.. _protobuf-py3:


* `click <>`_
* `protobuf`_ (when using Python 2)
* `protobuf-py3`_ (when using Python 3)

Testing (Linux/OSX)

Testing is done with `tox`_::


.. _tox:

Version 6.1.3

* Added ``--echo/--no-echo`` option to the CLI.

Version 6.1.2

* Fixed tests inclusion in tarball.

Version 6.1.1

* Fixed socket error handling in ``riemann_client.client.AutoFlushingQueuedClient``.

Version 6.1.0

* ``riemann_client.client.AutoFlushingQueuedClient`` added.

Version 6.0.0

* ``riemann_client.client.Client.create_dict`` only returns event fields that
are set on the Protocol Buffers ``Event`` object
* ``riemann-client send ...`` only outputs fields that were set on the message

Version 5.1.0

* Added Python 3 support
* Changed ``riemann_client.riemann_pb2`` to wrap ``_py2`` and ``_py3`` modules
* Changed ```` to dynamically select a ``protobuf`` dependency

Version 5.0.x

* Added API documentation (
* Replaced ``argparse`` with ``click`` for an improved CLI
* Various command line parameters changed
* ``--event-host`` became ``--host``
* ``--print`` was removed, ``send`` always prints the sent event
* Minor fixes to ``QueuedClient`` API
* ``UDPTransport.send`` returns ``None`` instead of ``NotImplemented``

Version 4.2.x

* Added ``events()`` and ``send_events()`` methods to the client
* Added ``clear_queue()`` method to the queued client
* Add ``--timeout`` option for TCP based transports

Version 4.1.x

* Full Riemann protocol support (TLS transport, event attributes)
* Fixes for multiple broken features (``--tags``, ``--print``)
* Raise errors when clients are used incorrectly
* Client displays errors from Riemann nicely
* Relaxed version requirements to fit CentOS 6 packages

Version 3.0.x

* Renamed module from ``riemann`` to ``riemann_client``
* Command line interface was rewritten, and is now the only part of the library
that respects the ``RIEMANN_HOST`` and ``RIEMANN_PORT`` environment variables
* Support for querying the Riemann index was added
* Internally, transports now define ``send`` instead of ``write``, and
``TCPTransport.send`` returns Riemann's response message


``riemann-client`` is licensed under the `MIT Licence`_. The protocol buffer
definition is sourced from the `Riemann Java client`_, which is licensed under
the `Apache Licence`_.

.. _MIT Licence:
.. _Riemann Java client:
.. _Apache Licence:


``riemann-client`` was written by `Sam Clements
<>`_, while working at `DataSift

.. image::
.. image::

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for riemann-client, version 6.5.0
Filename, size File type Python version Upload date Hashes
Filename, size riemann_client-6.5.0-py3-none-any.whl (19.4 kB) File type Wheel Python version 3.5 Upload date Hashes View
Filename, size riemann-client-6.5.0.tar.gz (81.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page