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)

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_dict(event)

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

static create_event(data)

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

event(**data)

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

events(*events)

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

query(query)

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

send_event(event)

Sends a single event to Riemann

Parameters:event – An Event protocol buffer object Returns:The response message from Riemann

send_events(events)

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_query(query)

Sends a query to the Riemann server

Returns:The response message from Riemann

class riemann_client.client.QueuedClient(transport=None)

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.

clear_queue()

Resets the message/queue to a blank Msg object

flush()

Sends the waiting message to Riemann

Returns:The response message from Riemann

send_event(event)

Adds a single event to the queued message

Returns:None - nothing has been sent to the Riemann server yet

send_events(events)

Adds multiple events to the queued message

Returns:None - nothing has been sent to the Riemann server yet