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:

• send_event()
• send_events()
• send_query()

Extended API:

• event()
• events()
• query()

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