clj-honeycomb.core — conormcd/clj-honeycomb 1.0.6.536

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 clj

(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 clj

(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 clj

(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? clj

(initialized?)

Report whether or not init has set up a client yet.

send clj

(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 clj 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 clj 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).