# riemann-client

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.

- Source on GitHub
- Documentation on Read the Docs
- Packages on PyPI

## Usage

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.

## Installation

`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.

### Requirements

- click
- protobuf (when using Python 2)
- protobuf-py3 (when using Python 3)

## Testing (Linux/OSX)

Testing is done with tox:

    tox

## Changelog

### 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 `setup.py` to dynamically select a `protobuf` dependency

### Version 5.0.x

- Added API documentation (http://riemann-client.readthedocs.org/)
- 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

## Licence

`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.

## Authors

`riemann-client` was written by Sam Clements, while working at DataSift.