def send_presampled(self):
'''send_presampled queues this event for transmission to Honeycomb.
Caller is responsible for sampling logic - will not drop any events
for sampling. Defining a `sample_rate` will ensure that the Honeycomb
datastore correctly considers it as representing `sample_rate` number
of similar events.
Raises SendError if no fields are defined or critical attributes not
set (writekey, dataset, api_host).'''
if self._fields.is_empty():
self.client.log("No metrics added to event. Won't send empty event.")
return
if self.api_host == "":
self.client.log("No api_host for Honeycomb. Can't send to the Great Unknown.")
return
if self.writekey == "":
self.client.log("No writekey specified. Can't send event.")
return
if self.dataset == "":
self.client.log(
"No dataset for Honeycomb. Can't send event without knowing which dataset it belongs to.")
return
if self.client:
self.client.send(self)
else:
state.warn_uninitialized()
def add(data):
'''add takes a mappable object and adds each key/value pair to the global
scope'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
state.G_CLIENT.add(data)
def send_presampled(self):
'''send_presampled queues this event for transmission to Honeycomb.
Caller is responsible for sampling logic - will not drop any events
for sampling. Defining a `sample_rate` will ensure that the Honeycomb
datastore correctly considers it as representing `sample_rate` number
of similar events.
Raises SendError if no fields are defined or critical attributes not
set (writekey, dataset, api_host).'''
if self._fields.is_empty():
raise SendError(
"No metrics added to event. Won't send empty event.")
if self.api_host == "":
raise SendError(
"No api_host for Honeycomb. Can't send to the Great Unknown.")
if self.writekey == "":
raise SendError("No writekey specified. Can't send event.")
if self.dataset == "":
raise SendError(
"No dataset for Honeycomb. Can't send event without knowing which dataset it belongs to."
)
if self.client:
self.client.send(self)
else:
state.warn_uninitialized()
def add(data):
'''Add takes a mappable object and adds each key/value pair to the global client.
These key/value pairs will be sent with every event created by the global client.'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
state.G_CLIENT.add(data)
def add_dynamic_field(fn):
'''add a global dynamic field. This function will be executed every time an
event is created. The key/value pair of the function's name and its
return value will be sent with every event.'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
state.G_CLIENT.add_dynamic_field(fn)
def add_dynamic_field(fn):
'''Add a dynamic field to the global client. This function will be executed every time an
event is created. The key/value pair of the function's name and its
return value will be sent with every event.'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
state.G_CLIENT.add_dynamic_field(fn)
def send_now(data):
'''creates an event with the data passed in and sends it immediately.
Shorthand for:
ev = Event()
ev.add(data)
ev.send()
'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
ev = Event(client=state.G_CLIENT)
ev.add(data)
ev.send()
def send(self):
'''send queues this event for transmission to Honeycomb.
Will drop sampled events when sample_rate > 1,
and ensure that the Honeycomb datastore correctly considers it
as representing `sample_rate` number of similar events.'''
# warn if we're not using a client instance and global libhoney
# is not initialized. This will result in a noop, but is better
# than crashing the caller if they forget to initialize
if self.client is None:
state.warn_uninitialized()
return
if _should_drop(self.sample_rate):
self.client.send_dropped_response(self)
return
self.send_presampled()
def send(self):
'''send queues this event for transmission to Honeycomb.
Will drop sampled events when sample_rate > 1,
and ensure that the Honeycomb datastore correctly considers it
as representing `sample_rate` number of similar events.'''
# warn if we're not using a client instance and global libhoney
# is not initialized. This will result in a noop, but is better
# than crashing the caller if they forget to initialize
if self.client is None:
state.warn_uninitialized()
return
if _should_drop(self.sample_rate):
self.client.send_dropped_response(self)
return
self.send_presampled()
def responses():
'''Returns a queue from which you can read a record of response info from
each event sent. Responses will be dicts with the following keys:
- `status_code` - the HTTP response from the api (eg. 200 or 503)
- `duration` - how long it took to POST this event to the api, in ms
- `metadata` - pass through the metadata you added on the initial event
- `body` - the content returned by API (will be empty on success)
- `error` - in an error condition, this is filled with the error message
When a None object appears on the queue the reader should exit'''
if state.G_CLIENT is None:
state.warn_uninitialized()
# return an empty queue rather than None. While not ideal, it is
# better than returning None and introducing AttributeErrors into
# the caller's code
return Queue()
return state.G_CLIENT.responses()
def send_now(data):
'''
DEPRECATED - This will likely be removed in a future major version.
Creates an event with the data passed in and enqueues it to be sent.
Contrary to the name, it does not block the application when called.
Shorthand for:
ev = Event()
ev.add(data)
ev.send()
'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
ev = Event(client=state.G_CLIENT)
ev.add(data)
ev.send()
def send_now(data):
'''
DEPRECATED - This will likely be removed in a future major version.
Creates an event with the data passed in and enqueues it to be sent.
Contrary to the name, it does not block the application when called.
Shorthand for:
ev = libhoney.Event()
ev.add(data)
ev.send()
'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
ev = Event(client=state.G_CLIENT)
ev.add(data)
ev.send()
def responses():
'''Returns a queue from which you can read a record of response info from
each event sent by the global client. Responses will be dicts with the
following keys:
- `status_code` - the HTTP response from the api (eg. 200 or 503)
- `duration` - how long it took to POST this event to the api, in ms
- `metadata` - pass through the metadata you added on the initial event
- `body` - the content returned by API (will be empty on success)
- `error` - in an error condition, this is filled with the error message
When a None object appears on the queue the reader should exit'''
if state.G_CLIENT is None:
state.warn_uninitialized()
# return an empty queue rather than None. While not ideal, it is
# better than returning None and introducing AttributeErrors into
# the caller's code
return Queue()
return state.G_CLIENT.responses()
def add_field(name, val):
'''add a global field. This field will be sent with every event.'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
state.G_CLIENT.add_field(name, val)
def add_field(name, val):
'''Add a field to the global client. This field will be sent with every event.'''
if state.G_CLIENT is None:
state.warn_uninitialized()
return
state.G_CLIENT.add_field(name, val)