Training Video

libhoney SDKS: Sending events to Honeycomb



Pierre Tessier [Sales Engineer|Honeycomb]:

Pierre Tessier here with another Honeycomb training video. In this one, we’re going to talk about the libhoney SDKs and how we could use them to send events into Honeycomb itself. Let’s get started. Now, when we think about SDKs for Honeycomb, we think Beelines, and Beelines are amazing. They provide auto instrumentation, distributor tracing, event creation, even batching and parsing of that data in transit. They provide a lot of the easy buttons to get started with instrumenting your applications, for observability with Honeycomb.

We have videos that cover our Beelines in greater detail and you’re encouraged to watch those videos. What we’re going to talk about here is what’s inside of every Beeline and what they depend on, and that’s a libhoney SDK. This lower level SDK is what’s responsible for the event creation and transmission. In some situations, you just need the raw data event creation capabilities and nothing else. This is what we’re going to talk about here.

Now, libhoney SDKs are provided and supported by Honeycomb in five popular languages, Go, Ruby, Python, Java, and node.js or JavaScript. There are also numerous community-supported libhoney SDKs that are in active use today. You can find them for Elixir, Rust, C#, Colon, and more. Today we’re going to focus on just a couple languages, but the concepts are the same regardless of what other language or platform you’re using with a few minor variances. We’re going to take a deeper look into Go and Python.

Before we dive into code, let’s examine what our sample event is going to look like going into Honeycomb. We have four fields here, a flow, an integer, and couple of strings. The language field will vary based on what language we’re emitting the event from itself. So let’s start with Golang. Inside your Go code, when you bring in libhoney, the first thing you’re going to need to do is to initialize the actual libhoney SDK itself, and to do so you just need to tell us two different parameters for initialization, which is your API key and the dataset we want to insert the data into.

Because the data’s being sent to Honeycomb asynchronously, we also recommend that you close the SDK to ensure any data left in transmission is sent off before your application kills off. This should be part of your main routine. Now, to send the data itself, your entire code stack will look like this. So your import statement at the top, that same initialize statement which you’ve seen and then create the event. The first thing you want to do is libhoney.newevent and then we’re going to add data or fields into it.

Really easy to do for all libhoney SDKs, you just call add and pass in a map of those fields that you want to add in and we’re going to pass them all in right here. And finally, we’re going to send that event off to Honeycomb. Pretty simple stuff. Let’s see the same thing inside of Python.

Before you need to use this in Python, you do need to add the libhoney library into your Python installation, depending on what flavor or environment of Python you have, this will be PIP or PIP3, install libhoney. Once that’s in you can actually go ahead and start using it. You’re going to import libhoney into your project or into your code and then libhoney emit should be part of the main startup of your application itself. Again, passing those same two parameters, API key and the actual name of the data set. Make sure the API key matches whatever your sample is, these environment variables that you need in your world.

To send the event, again, we’re just going to use libhoney to do a new event here using the Python syntax inserter and we’re going to add a map or a dict, again describing what that event is and send it off into Honeycomb. So really whether you’re using Go or Python, it’s very similar at this point. But right now what we’ve looked at is all these events are going to be sent off with the current timestamp of now. That’s not always the case, sometimes you want to send your events where they were in the back pass, or maybe you’re backloading some data or you’re just trying to process something that happened beforehand and you might want to modify that timestamp.

Let’s dive into that a little bit more. Now, every language and SDK you use, you’re going to be using the date or date-time constructs of that language and they’re all slightly different. So please be mindful of what you’re using here to create that data object. But the only difference instead in here is you’re going to call the timestamp property on the event object itself. This is not another field, but it’s the actual property of the event object and we’re going to give it, in Golang’s world, just a time object.

In the world of Python, this property is called created_at. This is unique to Python only. All the other SDKs seems to follow the timestamp form, and here we’re going to pass in a date, date-time. So again, when it comes to passing that timestamp, you’re going to use the date object specific to that language. Now, this is changing the time.

Another really popular use case of the libhoney SDKs is setting a few global fields that you’re going to use for all the events you’re going to send and maybe you might want to override one or many of them when you send the actual event itself. Let’s look at what that will be.

Many of the SDKs will use a builder approach. So instead of creating an event directly, you’re going to create a builder first. This builder will contain those fields that you want to have those definitions on. So in Golang, we’re going to have one called language Go and payload’s going to have a value of negative one. We’ll override that later. Now, when you create the event, instead of creating an event from libhoney, we’re going to create an event from the builder. Everything else is the same, we’re going to add those same fields, method.get, we’re going to override payload.

Now we’re also introducing something else here. Previously we showed you how you could add fields as a map. You could also add fields individually and all the SDKs support this. Typically what you want to do is create the initial event, get it ready, and add data to it as you go along and process it. Sometimes that data can be based on how long you took spending time processing something like a duration and this is what we add right here, and finally, we send it.

The same stuff can be done in Python, though it’s a little different how we get it set up. Python and Ruby both share this flavor here, where we add the global fields as part of libhoney SDK itself. So there’s not a builder pattern here, we’re not building a builder. We’re going to make it part of the SDK. Everything else is pretty much the same, we’re going to create a new event, pass in the same parameters and do some work and then pass in a duration. This is how you really use these Libhoney SDKs. Easy stuff to do and it provides you a lot of value. I hope you enjoyed this video and thanks for watching.

If you see any typos in this text or have any questions, reach out to