Skip to main content

async/await client for Riemann

Project description

This is a client for Riemann build on top of async/await syntax. It supports TCP, UDP and TLS connections.


pip install aioriemann

Working with client

Now that AIORiemann is installed, let’s try sending some of our own states through the client:

>>> from aioriemann import Riemann
>>> client = Riemann()

We can send events with send(). For example, let’s log an HTTP request:

>>> await client.send({
...   "host": "www1",
...   "service": "http req",
...   "metric": 2.53,
...   "state": "critical",
...   "description": "Request took 2.53 seconds.",
...   "tags": ["http"]
... })

On the dashboard, critical events (like the one we just submitted) show up in red. All of these fields are optional, by the way. The client will assume your events come from the local host name unless you pass host=None.

Now let’s ask for all events that have a service beginning with “http”:

>>> await client.query('service =~ "http%"')
        "timestamp": 1330041937,
        "state": "critical",
        "service": "http req",
        "host": "www1",
        "description": "Request took 2.53 seconds.",
        "tags": ["http"],
        "ttl": 300.0,
        "metric": 2.5299999713897705

There’s the event we submitted.

query() and send() are wrapped in asyncio.Task. so it means that they are scheduled automatically event without await keyword:

>>> client.send({
...   "host": "www1",
...   "service": "http req",
...   "metric": 2.53,
...   "state": "critical",
...   "description": "Request took 2.53 seconds.",
...   "tags": ["http"]
... }).add_done_callback(func)
>>> client.query('service =~ "http%"').add_done_callback(func)

And later call join() to ensure that tasks have been done:

>>> await client.join()


A TCP connection to Riemann is a stream of messages. Each message is a 4 byte network-endian integer length, followed by a Protocol Buffer Message of length bytes. See the protocol buffer definition for the details.

Over UDP, the length header is omitted; just send the protobuf Message directly. UDP datagrams have a default maximum size of 16384 bytes by Riemann’s default; larger messages should go over TCP. This limit is configurable in both the client and server; client values must be smaller than the server’s.

The server will accept a repeated list of Events, and respond with a confirmation message with either an acknowledgement or an error. Check the ok boolean in the message; if false, message.error will be a descriptive string.

Because protocol buffers is a strongly typed protocol, the metric of an event is represented as one of metric_d (floating point 64-bit), metric_f (floating point 32-bit), or metric_sint64 (64-bit signed integer). Your client should emit and consume all of these types. For compatibility with older versions of Riemann, you may also emit a metric_f alongside the normal type; newer versions of Riemann will prefer the higher-resolution types.

Events are uniquely identified by host and service. Both allow null. Event.time is the time in unix epoch seconds and is optional. The server will generate a time for each event when received if you do not provide one. I don’t need time resolution finer than 1 second presently, but if you do, my plan is to add a nanosecond field as well.

You can also query events from the index using a basic query language. Just submit a Message with your query in message.query.string. Search queries will return a message with repeated Events matching that expression. A null expression will return no states. For some example queries, see The query test suite.

You might find it useful to read the Ruby client source as a guide to writing your own client.

Reading list

Project details

Download files

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

Files for aioriemann, version 1.0.0a1
Filename, size File type Python version Upload date Hashes
Filename, size aioriemann-1.0.0a1.tar.gz (24.4 kB) File type Source Python version None Upload date Hashes View
Filename, size aioriemann-1.0.0a1-py2.py3-none-any.whl (13.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View

Supported by

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