clj-honeycomb.core
A thin wrapper over libhoney-java. Use this to send events to Honeycomb.
Require this namespace as honeycomb and then use it like this:
; Initialise this library
(honeycomb/init {:data-set "Your Honeycomb dataset"
:write-key "Your Honeycomb API key"})
; Send an event
(honeycomb/with-event {:initial :data} {}
... do your stuff ...
(honeycomb/add-to-event :more "event data")
... do more of your stuff ...)add-to-event
(add-to-event m)(add-to-event k v)
From within a with-event form, add further fields to the event which will
be sent at the end of the with-event.
This can be called either with a single map to be (shallow) merged onto the
event's current data or with a key and value which will be associated onto
the event map.
client
(client options)
Construct a HoneyClient from a map of options. It is your responsibility to
call .close on this object when you're finished with it. Failure to do so may
result in a loss of events. It is recommended that you create this client
using with-open or with a state management system like component or mount.
Valid options are:
:api-host The base of the URL for all API calls to Honeycomb.
(String. Optional. Default: "https://api.honeycomb.io/")
:data-set The name of your Honeycomb dataset. (String. Required.)
:event-post-processor An instance of the libhoney-java class
io.honeycomb.libhoney.EventPostProcessor which can be
used to post-process event data after sampling but before
sending the event to Honeycomb. (EventPostProcessor.
Optional.)
:global-fields A map of fields to include in every event. These fields
can have dynamic values either by using an
atom/delay/promise as its value or by supplying a
ValueSupplier object as the value. Fields added to a
given event will override these fields. (Map. Optional.)
:response-observer A map of functions which will be called during the
lifecycle of sending each event. (Map. Optional.)
Keys in this map are:
:on-client-rejected Called when the libhoney-java code
fails to send an event to
Honeycomb.
:on-server-accepted Called when the Honeycomb server
has accepted the event. Be very
wary of supplying a function for
this, since it can be called a lot.
:on-server-rejected Called when the Honeycomb server
rejects an event.
:on-unknown Called for all other errors in the
lifecycle of sending an event.
:sample-rate The global sample rate. This can be overridden on a
per-event basis. (Integer. Optional. Default: 1)
:transport-options A map of options which can be used to configure the
transport layer of libhoney-java. The defaults should
be good enough for most applications. You should read
and understand the documentation for
io.honeycomb.libhoney.TransportOptions before changing
any of these values. (Map. Optional.)
Valid keys in this map are as follows, see the
documentation for TransportOptions to understand their
exact meanings.
:additional-user-agent
:batch-size
:batch-timeout-millis
:buffer-size
:connection-request-timeout
:connect-timeout
:io-thread-count
:max-connections
:max-connections-per-api-host
:maximum-http-request-shutdown-wait
:maximum-pending-batch-requests
:queue-capacity
:socket-timeout
:write-key Your Honeycomb API key. (String. Required.)init
(init client-or-options)
Initialize this library. Can be given either a HoneyClient instance to use
for all send calls which don't specify a client or a map which will be
passed to client to create a client.
client-or-options Either an instance of HoneyClient or a map to pass to
client to create one.initialized?
(initialized?)
Report whether or not init has set up a client yet.
send
(send event-data)(send event-data options)(send honeycomb-client event-data)(send honeycomb-client event-data options)
Send an event to Honeycomb.io.
event-data The fields to send for this event. These will be merged on
top of the global fields configured in the HoneyClient.
honeycomb-client An optional HoneyClient instance to use as the API client.
This is required if you have not already called init.
options A map of event-specific options. Valid options are:
:api-host Override the :api-host set in the client.
(String. Optional.)
:data-set Override the :data-set set in the client.
(String. Optional.)
:metadata A map of metadata which you can set on each
event. This will not be sent to Honeycomb but
will be returned in every call to a function
in a ResponseObserver. This could allow you to
match a response to an originating event.
(Map. Optional.)
:pre-sampled Set this to true if you've already sampled the
data. Otherwise libhoney-java will sample it
for you. If you set this, you should ensure
that sample-rate is also supplied with a value
that reflects the sampling you did. (Boolean.
Optional. Default: false)
:sample-rate The sample rate for this event. If not
supplied, the sample rate configured for the
client library will be used. (Integer.
Optional.)
:timestamp Set an explicit timestamp for this event,
measured in milliseconds since the epoch.
(Integer. Optional. Default:
(System/currentTimeMillis))
:write-key Override the :write-key set in the client.
(String. Optional.)with-event
macro
(with-event event-data options & body)
Wrap some code and send an event when the code is done.
event-data The fields to send for this event. These will be merged on
top of the global fields configured in the HoneyClient. The
following additional keys will be added to the event data
just before sending:
:durationMs The number of milliseconds it took to execute
the body of this macro.
:exception If an exception was thrown, it will be added
to this field before being rethrown.
options A map of event-specific options. Valid options are:
:api-host Override the :api-host set in the client.
(String. Optional.)
:data-set Override the :data-set set in the client.
(String. Optional.)
:metadata A map of metadata which you can set on each
event. This will not be sent to Honeycomb but
will be returned in every call to a function
in a ResponseObserver. This could allow you to
match a response to an originating event.
(Map. Optional.)
:pre-sampled Set this to true if you've already sampled the
data. Otherwise libhoney-java will sample it
for you. If you set this, you should ensure
that sample-rate is also supplied with a value
that reflects the sampling you did. (Boolean.
Optional. Default: false)
:sample-rate The sample rate for this event. If not
supplied, the sample rate configured for the
client library will be used. (Integer.
Optional.)
:timestamp Set an explicit timestamp for this event,
measured in milliseconds since the epoch.
(Integer. Optional. Default:
(System/currentTimeMillis))
:write-key Override the :write-key set in the client.
(String. Optional.)with-trace-id
macro
(with-trace-id trace-id & body)
Wrap some code and associate it all with a single trace ID.
trace-id The ID to be associated as `:traceId` with every event within this
body (unless overridden).