We use cookies or similar technologies to personalize your online experience and tailor marketing to you. Many of our product features require cookies to function properly. Your use of this site and online product constitutes your consent to these personalization technologies. Read our Privacy Policy to find out more.

X

Java SDK

Installation

The SDK is available from Maven Central Repository. To get started, add this to your Maven build’s pom.xml:

<dependency>
    <groupId>io.honeycomb.libhoney</groupId>
    <artifactId>libhoney-java</artifactId>
    <version>1.0.2</version>
</dependency>

For Gradle builds, add the following to your build.gradle dependencies:

compile group: 'io.honeycomb.libhoney', name: 'libhoney-java', version: '1.0.2'

Initialization

The LibHoney class is the entry point to the Honeycomb client library, and is used to create a HoneyClient.

The HoneyClient class provides functionality to construct and send events. The typical application will only have one HoneyClient instance.

Use LibHoney’s static methods to construct and configure an instance of HoneyClient, passing in your Team API key and the default dataset name to which it should send events.

public class Initialization {
    private HoneyClient honeyClient;

    public Initialization() {
        honeyClient = create(
            options()
                .setWriteKey("myTeamWriteKey")
                .setDataset("Cluster Dataset")
                .setSampleRate(2)
                .build()
        );
    }
}

Important notes on Libhoney:

  1. Use of one HoneyClient instance across threads is thread safe.
  2. Libhoney sends will not block your code - event sends are batched up and sent in a queue running in its own thread as the queue either fills to its limit or the default batch send interval is reached.
  3. Pending writes to Honeycomb will be flushed automatically when the JVM shuts down. You do not need to worry about flushing them yourself.

You are currently logged in to the team, so we have populated the write key here to the first write key for that team.

Further configuration options are described in the API reference.

Building and sending events

Once initialized, HoneyClient is ready to send events. In many cases, an event should be first customized with relevant data from its runtime context. For example, try putting a timer around a section of code, adding per-user information, or details about what it took to craft a response. You can add fields when and where you need to, or for some events but not others. (Error handlers are a good example of this.)

createEvent() creates such a customizable Event. You can add fields to the event with .addField() and then submit to the Honeycomb server via Event.send().

Sending an event is an asynchronous action and will avoid blocking by default.

    public static void main(String... args) {
        try (HoneyClient honeyClient = initializeClient()) {
            honeyClient
                .createEvent()
                .addField("userName", "Bob")
                .addField("userId", UUID.randomUUID().toString())
                .setTimestamp(System.currentTimeMillis())
                .send();
        }
    }
}

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

You can use an EventFactory to create many similar events as follows:

static class UserService {
        private final EventFactory localBuilder;

        UserService(HoneyClient libHoney) {
            int serviceLevelSampleRate = 2;
            localBuilder = libHoney.buildEventFactory()
                .addField("serviceName", "userService")
                .setSampleRate(serviceLevelSampleRate)
                .build();
        }

        void sendEvent(String username) {
            localBuilder
                .createEvent()
                .addField("userName", username)
                .addField("userId", UUID.randomUUID().toString())
                .setTimestamp(System.currentTimeMillis())
                .send();
        }
    }

All libraries set defaults that will allow your application to function as smoothly as possible during error conditions. When creating events faster than they can be sent, overflowed events will be dropped instead of backing up and slowing down your application. If you add the same key multiple times, only the last value added will be kept.

Handling responses

Sending an event is an asynchronous action and will avoid blocking by default. .send() will enqueue the event to be sent as soon as possible, meaning the return value of that method doesn’t indicate that the event was successfully sent.

To see whether events are being successfully received by Honeycomb’s servers, register a ResponseObserver interface with HoneyClient. The ResponseObserver interface has four methods which are notified in different circumstances depending on the outcome of the sending of the event.

All responses have methods to extract the original event metadata, metrics collected during the event, and a message explaining the response from Honeycomb:

For responses to events either accepted by or rejected by the server, it is also possible to extract the event status code and raw HTTP response body.

In the case of responses to events rejected by the client, the exception and rejection reason are accessible.

Before sending an event, you have the option to attach metadata to that event. This metadata is not sent to Honeycomb; instead, it’s used to help you match individual responses with sent events. When sending an event, HoneyClient will take the metadata from the event and attach it to the response for you to consume. Add metadata by calling .addMetadata(k, v) or addMetadata(Map<String,?> metadata) on an event.

You don’t have to process responses if you’re not interested in them—simply ignoring them is perfectly safe. Unread responses will be dropped.

Contributions

Features, bug fixes and other changes to libhoney are gladly accepted. Please open issues or a pull request with your change. Remember to add your name to the CONTRIBUTORS file!

All contributions will be released under the Apache License 2.0.