Getting Data in with Beelines: Golang

Nathan LeClaire [Sales Engineer|Honeycomb]:

Hey there. Nathan from Honeycomb here, and today we’re going to talk about getting data in with the Golang Beeline. Beelines are an excellent way to get started with Honeycomb because they allow you to quickly hook into popular frameworks, and they also have API for instrumenting traces that is quite useful.

To install the Beeline, run this Go Get command that you see here on your console. You’ll pass in our GitHub repository for the Beeline, which by the way if you want to go check out the source code you can there, and also these three dots at the end to indicate we’ll install the library recursively. And if you see an error message about no source files, don’t worry because that’s normal. It’s just because we’re not getting a binary from the Go Get command here.

So to generate the traces, first, we will kick off a start span call, and this is the end result that we’re going to go for here. We want to have several spans representing chunks of units of work, nested within each other, to define what’s happening at any given point in time in a program. So to do that, first we’ll initialize the Beeline, where you can see here at the top we must import it first, and then call the beeline.Init method. That will pass in a beeline.Config object that has the right key available in your team settings in Honeycomb, a dataset name like “Traces,” a service name, which is the name of the app you’re instrumenting right now. And then I also recommend you pass in this debug.true flag at the end to turn on the debug mode. That will output errors to the console if anything goes wrong. And then eventually before we exit the program, we want to make sure we call beeline.Close to flush any remaining events to the Honeycomb API.

Core usage of the Beeline often revolves around the beeline.StartSpan and beeline.AddField calls. So first we will call beeline.StartSpan to either start a new span or start a trace if one doesn’t exist yet. We’ll pass in a context object. We’ve just done that blank background context here. And we also want to give the span a name, like “Chunk”. Very generic name. And before we exit the method, we want to call span.Send when that chunk of work finishes. So oftentimes the span.Send will be deferred. And we want to call beeline.AddFields a lot of the time, because that will allow you to instrument your code and add more custom details to the things that you’re collecting. You probably also want to pass that context object in through your stack in your code so that you can add more things along the way.

You also can wrap common libraries with the Beeline, and that’s really the fastest way to get started a lot of the time. So here at the top is the first example of wrapping the builtin Golang HTTP server with this abstraction we provide called hnynethttp.WrapHandler. And in the second chunk of code, starting with ODB there, you can see that you can also wrap database calls. That’s very powerful for generating a span to query information over because the database is a source of problems in production a lot of the time.

Lastly, this third example here shows using an HTTP client where we have wrapped the round-tripper. And so in the hnynethttp Module, WrapRoundTripper will wrap any HTTP round-tripper you have on an HTTP client so that you can instrument calls like that client.Get there that will generate one span with all of those fields added with add field like endpoint.

In the end, we’re also going to probably want to pass traces around the network and have each service understand the context of the trace. So just like inside of the same program, we passed around that context object there on the network, we’ll pass around trace headers that define what’s happening. So go forth and instrument your code. That was a little introduction to the Go Beeline, but there’s more that you can check out and we always encourage contributions on our open source work. So go forth and enjoy the Go Beeline. And we’ll catch you on the flip side.

If you see any typos in this text or have any questions, reach out to marketing@honeycomb.io.

Transcript