Client API

Clients manage the main user facing API, and provide functions for sending events and querying the Riemann server. UDP, TCP and TLS transports are provided by the riemann_client.transport module, and the protocol buffer objects are provided by the riemann_client.riemann_pb2 module.

class riemann_client.client.Client(transport=None)[source]

Bases: object

A client for sending events and querying a Riemann server.

Two sets of methods are provided - an API dealing directly with protocol buffer objects and an extended API that takes and returns dictionaries representing events.

Protocol buffer API:

Extended API:

Clients do not directly manage connections to a Riemann server - these are managed by riemann_client.transport.Transport instances, which provide methods to read and write messages to the server. Client instances can be used as a context manager, and will connect and disconnect the transport when entering and exiting the context.

>>> with Client(transport) as client:
...     # Calls transport.connect()
...     client.query('true')
...     # Calls transport.disconnect()
static create_event(data)[source]

Translates a dictionary of event attributes to an Event object

Parameters:data (dict) – The attributes to be set on the event
Returns:A protocol buffer Event object
send_events(events)[source]

Sends multiple events to Riemann in a single message

Parameters:events – A list or iterable of Event objects
Returns:The response message from Riemann
send_event(event)[source]

Sends a single event to Riemann

Parameters:event – An Event protocol buffer object
Returns:The response message from Riemann
events(*events)[source]

Sends multiple events in a single message

>>> client.events({'service': 'riemann-client', 'state': 'awesome'})
param *events:event dictionaries for create_event()
returns:The response message from Riemann
event(**data)[source]

Sends an event, using keyword arguments to create an Event

>>> client.event(service='riemann-client', state='awesome')
Parameters:**data – keyword arguments used for create_event()
Returns:The response message from Riemann
static create_dict(event)[source]

Translates an Event object to a dictionary of event attributes

All attributes are included, so create_dict(create_event(input)) may return more attributes than were present in the input.

Parameters:event – A protocol buffer Event object
Returns:A dictionary of event attributes
send_query(query)[source]

Sends a query to the Riemann server

Returns:The response message from Riemann
query(query)[source]

Sends a query to the Riemann server

>>> client.query('true')
Returns:A list of event dictionaries taken from the response
Raises Exception:
 if used with a UDPTransport
class riemann_client.client.QueuedClient(transport=None)[source]

Bases: riemann_client.client.Client

A Riemann client using a queue that can be used to batch send events.

A message object is used as a queue, with the send_event() and send_events() methods adding new events to the message and the flush() sending the message.

flush()[source]

Sends the waiting message to Riemann

Returns:The response message from Riemann
send_event(event)[source]

Adds a single event to the queued message

Returns:None - nothing has been sent to the Riemann server yet
send_events(events)[source]

Adds multiple events to the queued message

Returns:None - nothing has been sent to the Riemann server yet
clear_queue()[source]

Resets the message/queue to a blank Msg object

class riemann_client.client.AutoFlushingQueuedClient(transport, max_delay=0.5, max_batch_size=100, stay_connected=False, clear_on_fail=False)[source]

Bases: riemann_client.client.QueuedClient

A Riemann client using a queue and a timer that will automatically flush its contents if either:

  • the queue size exceeds :param max_batch_size: or
  • more than :param max_delay: has elapsed since the last flush and
the queue is non-empty.

if :param stay_connected: is False, then the transport will be disconnected after each flush and reconnected at the beginning of the next flush. if :param clear_on_fail: is True, then the client will discard its buffer after the second retry in the event of a socket error.

A message object is used as a queue, and the following methods are given:

  • send_event() - add a new event to the queue

  • send_events() add a tuple of new events to the queue

  • event() - add a new event to the queue from

    keyword arguments

  • events() - add new events to the queue from

    dictionaries

  • flush() - manually force flush the queue to the

    transport

connect()[source]

Connect the transport if it is not already connected.

is_connected()[source]

Check whether the transport is connected.

event(**data)[source]

Enqueues an event, using keyword arguments to create an Event

>>> client.event(service='riemann-client', state='awesome')
Parameters:**data – keyword arguments used for create_event()
events(*events)[source]

Enqueues multiple events in a single message

>>> client.events({'service': 'riemann-client',
>>>                'state': 'awesome'})
param *events:event dictionaries for create_event()
returns:The response message from Riemann
send_events(events)[source]

Enqueues multiple events

Parameters:events – A list or iterable of Event objects
Returns:The response message from Riemann
flush()[source]

Sends the events in the queue to Riemann in a single protobuf message

Returns:The response message from Riemann
check_for_flush()[source]

Checks the conditions for flushing the queue

start_timer()[source]

Cycle the timer responsible for periodically flushing the queue

stop_timer()[source]

Stops the current timer

a flush() event will reactviate the timer