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 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.
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 client:
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)
client.flush()
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 client API <riemann_client.client> riemann-client transport API <riemann_client.transport>
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 when running under Python 3. Python 3 support is experimental and is likley to use Google's protobuf once it supports Python 3 fully.
- Added Python 3 support
- Changed
riemann_client.riemann_pb2
to wrap_py2
and_py3
modules - Changed
setup.py
to dynamically select aprotobuf
dependency
- Added API documentation (riemann-client.readthedocs.org)
- Replaced
argparse
withclick
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
returnsNone
instead ofNotImplemented
- Added
events()
andsend_events()
methods to the client - Added
clear_queue()
method to the queued client - Add
--timeout
option for TCP based transports
- 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
- Renamed module from
riemann
toriemann_client
- Command line interface was rewritten, and is now the only part of the library that respects the
RIEMANN_HOST
andRIEMANN_PORT
environment variables - Support for querying the Riemann index was added
- Internally, transports now define
send
instead ofwrite
, andTCPTransport.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.
riemann-client
was written by Sam Clements, while working at DataSift.