This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
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

Release History

Release History


This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
aioriemann-1.0.0a1-py2.py3-none-any.whl (13.2 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Nov 3, 2016
aioriemann-1.0.0a1.tar.gz (24.4 kB) Copy SHA256 Checksum SHA256 Source Nov 3, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting