Nathan LeClaire [Sales Engineer|Honeycomb]:
Welcome to another episode of Honeycomb Training. Nathan LeClaire here and we’re going to talk today about getting data in with the NodeJS line. To begin using the Beeline, npm install the honeycomb-beeline module into your NodeJS app. Usually, when you require the Beeline, you want to have it before you require anything else as you see here. Your right key you can get from your team settings in Honeycomb to authenticate with our API. And if you have some of these known patterns, like an express app, the Beeline will instrument your code for you automatically. So there’s also an API for generating traces and we’re going to talk about that a little bit later. Now, when we have added this beeline auto instrumentation into our code an important setting is we want to export the debug environment variable to honeycomb-beeline:*.
So that will turn on all debug logging, which you can see an example of as the app is run here. And as we access endpoints in our app, we’ll notice that events are generated, which we can see logged locally here from that debug setting. And those are sent along to the Honeycomb API. So once we access the events in Honeycomb, we can query over our data and then zoom in to go look at a particular trace. Like here’s the most recent one that we just sent in and these spans in the trace will show us what’s going on in our app through various different things. So you can see, for instance, that orange span is a Mongo DB call.
Now on top of this first layer of automatic instrumentation, it’s very important that we want to add additional context and spans. So you can use the beeline.addContext method to add additional metadata to query later on. So this might be things like the total quantity of items that you’re getting from some data store, or it might be a user ID or a team ID. Anything you can imagine you can add on to the spans that the beeline is generating, and you can also create new spans.
I’d also want to create traces from scratch. So when we want to create a trace from scratch in say a background job or some process that isn’t modeled very easily in this call and response relationship, first we want to call beeline.startTrace to kick off the Beeline’s trace. And you can see an example here where I’m using a library puppeteer. So this is a chromium wrapper for node. And in this async function here, we’re doing stuff for puppeteer and we’re waiting. So after we started the trace, we will call beeline.startSpan for each little chunk of work, and then we’ll call beeline.finishSpan when we’re finished with that span.
So we’re creating three spans here. And then at the end, we call await beeline.finishTrace that we’ll make sure we wait for the beeline to send to Honeycomb before we exit the program. So we’ll see some response output and you want to make sure to manage your async context correctly. So one thing I do encourage you to take a look at is the API reference for the Beeline. That’s available at our GitHub repository, which you can see the link for here. You could probably just Google that.
Occasionally you might want to know about these two functions. So one is called beeline.bindFunctionToTrace. That will ensure that the trace context is propagated through to these Beeline calls correctly when some other library might be doing something funny with async hooks, which is how the Beeline manages its state internally. So bind function to trace might be a little bit of glue to get you out of a bind if the context isn’t being propagated correctly. If you still have problems, check out our GitHub repository and open an issue, and then you also might need to await beeline.flush if you’re using the NodeJS Beeline in AWS Lambda. So in some of these serverless providers, you have to await for things to send in the background before the Lambda returns and your program can continue its life cycle. So that’s a little bit on the NodeJS Beeline, I hope you guys enjoy the Beeline and let us know how it goes.
If you see any typos in this text or have any questions, reach out to firstname.lastname@example.org.