Package io.honeycomb.libhoney

Class HoneyClient

java.lang.Object

io.honeycomb.libhoney.HoneyClient

All Implemented Interfaces:

AutoCloseable

public class HoneyClient
extends Object
implements AutoCloseable

The Honeycomb Client

This class provides functionality to construct and send events. An instance of the client is immutable and threadsafe. The typical application will only have one HoneyClient instance.

Configuration

Use LibHoney's static methods to construct and configure an instance of HoneyClient.

Usage

The quickest way to send an event is to use the send(Map) method, which will send it with the settings and fields of the HoneyClient instance.

However, in many cases an event should be first customised with relevant data from its runtime context. createEvent() creates such a customisable Event, which can then be submitted to the Honeycomb server via Event.send().

Alternatively, an EventFactory is useful when a grouping of events being sent shares common properties. This can be created through the buildEventFactory() method.

Inheriting properties

EventFactory inherits the properties from the instance of HoneyClient that creates it. An Event can be created through EventFactory and HoneyClient, and will similarly inherit properties from them.

Event Validation

An event being sent is subject to the following client-side validation rules, causing an IllegalArgumentException to be thrown when violated:

• apiHost must not be null
• writeKey must not be blank
• dataset must not be blank
• samplerate must be 1 or greater
• the event must have at least one key-value pair added to its fields

It's sufficient to configure these on any of the "scopes" (i.e. by setting them on HoneyClient, EventFactory, or Event), as long as as the event being sent ultimately contains them.

Shutdown

To ensure a graceful shutdown (flushing of queues, shutdown of threads), make sure to call close() once this instance is no longer needed. After close returns, it is not longer safe to use the instance, and this includes any EventFactory and Event instances that have been created with this instance.

The shutdown is best effort, and subject to a timeout, so it does not block indefinitely. This means, events may ultimately be dropped (e.g. if the honeycomb server cannot be reached in time).

Global Fields

Global fields are configured via Options. There are 2 types of fields:

• globalFields have fixed keys and values and remain static for the lifetime of the instance.
• globalDynamicFields also have fixed keys, but values are dynamic and resolved every time when Event.send() is invoked.

Fields will be inherited by EventFactorys and Events that are constructed from a given HoneyClient instance. Note that global fields have a lower precedence than fields added via EventFactory or Event, and thus will be overwritten if the keys equal. However, across the 2 ways to provide global fields, there is no explicit precedence/ordering.

Post Processor

Any global state that a user may want to observe, or any global manipulation of events, is encapsulated within the post processor that a HoneyClient instance can be configured with. See the interface documentation of EventPostProcessor for details.

Constructor Summary

Constructors

Constructor	Description
HoneyClient(Options options)	Constructor that assumes that the default transport is being used.
HoneyClient(Options options, Transport transport)	Constructor that allows the the transport to be overridden.
HoneyClient(Options options, Transport transport, ClockProvider clock)	Constructor that allows the the transport and clock to be overridden.
HoneyClient(Options options, TransportOptions transportOptions)	Constructor offering further configuration options of the transport layer.

Method Summary

Modifier and Type	Method	Description
void	addResponseObserver(ResponseObserver observer)	Add an observer that gets notified about the outcome of every event sent through this client.
EventFactory.Builder	buildEventFactory()	Returns a builder for constructing an EventFactory.
void	close()	Method to initiate shutdown of this client and of the transport.
void	closeOnShutdown()	Can be used to add a JVM shutdown hook that invokes close() on this client instance.
Event	createEvent()	Returns an Event with the configuration and fields populated as set during initialisation of this client instance.
void	removeResponseObserver(ResponseObserver observer)	Remove the given observer, if response notifications are no longer required, or the reference should be released.
void	send(Map<String,?> fields)	Provides a shortcut to sending an event by populating it with the settings and fields of this client instance and adding the provided map of fields.
void	setAsDefault()	Can be used to set this LibHoney instance as a global default.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HoneyClient

public HoneyClient(Options options)

Constructor that assumes that the default transport is being used.

Parameters:

options - Configuration options.

HoneyClient

public HoneyClient(Options options,
                   TransportOptions transportOptions)

Constructor offering further configuration options of the transport layer.

Parameters:

options - Configuration options.

transportOptions - Advanced configuration options for the transport.

HoneyClient

public HoneyClient(Options options,
                   Transport transport)

Constructor that allows the the transport to be overridden. Useful for testing.

Parameters:

options - Configuration options.

transport - used to provide alternative transports (including test/mock implementations).

HoneyClient

public HoneyClient(Options options,
                   Transport transport,
                   ClockProvider clock)

Constructor that allows the the transport and clock to be overridden. Useful for testing.

Parameters:

options - Configuration options.

transport - used to provide alternative transports (including test/mock implementations).

clock - used to override the clock for testing

Method Detail

createEvent

public Event createEvent()

Returns an Event with the configuration and fields populated as set during initialisation of this client instance.

Returns:

an event.

buildEventFactory

public EventFactory.Builder buildEventFactory()

Returns a builder for constructing an EventFactory. It is initially populated with the fields and configuration settings of this client instance, but can be further customised to create a more specialised factory of Events.

Returns:

a builder for EventFactory.

send

public void send(Map<String,?> fields)

Provides a shortcut to sending an event by populating it with the settings and fields of this client instance and adding the provided map of fields. It is also subject to the configured sampling rate.

Parameters:

fields - to provide to the event.

Throws:

IllegalArgumentException - if client-side validation fails, see HoneyClient's class documentation for the "Event Validation" rules.

addResponseObserver

public void addResponseObserver(ResponseObserver observer)

Add an observer that gets notified about the outcome of every event sent through this client.

Parameters:

observer - to register.

removeResponseObserver

public void removeResponseObserver(ResponseObserver observer)

Remove the given observer, if response notifications are no longer required, or the reference should be released. Note that when cleaning up calling close() will have the effect of clearing all observers.

Parameters:

observer - to remove.

setAsDefault

public void setAsDefault()

Can be used to set this LibHoney instance as a global default. Shortcut for LibHoney.getDefault().

closeOnShutdown

public void closeOnShutdown()

Can be used to add a JVM shutdown hook that invokes close() on this client instance. Shortcut for LibHoney.closeOnShutdown(HoneyClient).

close

public void close()

Method to initiate shutdown of this client and of the transport. For details see the class documentation above. After the initial call, further calls to this method have no effect.

Specified by:

close in interface AutoCloseable