Announcing New CircleCI + Honeycomb Integration Guide

If you’re writing software today, then you likely use a CI/CD pipeline to build and test your code before deploying it to production. Having a fast and efficient build pipeline saves you development time, shortens feedback loops, and helps you ship features faster. Conversely, slow and unreliable build pipelines are full of lost productivity and sadness.

This post shows you how to identify and fix build pipeline performance issues using CircleCI and Honeycomb with a new hands-on quickstart guide that will show you the inner workings of CircleCI build pipelines, the Honeycomb CircleCI Buildevents Orb, and the Honeycomb UI.

If you’ve been wanting to get started with CircleCI or Honeycomb (or you’d like to), this is the post you’ve been waiting for!

What is the CircleCI Buildevents orb?

Honeycomb’s CircleCI Buildevents orb is a lightweight and immensely helpful way to generate traces from your CircleCI build pipelines so that you can quickly visualize performance, identify bottlenecks, and discover why they’re happening so that you can fix them. No one likes a slow build. Well… mostly no one.

The CircleCI Buildevents orb is based on Honeycomb's buildevents tool. CircleCI orbs are reusable snippets of configuration packaged up and condensed so that repeated processes can fit into a single line of code. They speed up using third party tools (you can find thousands of them) in your projects. They generally make the experience of using those tools in your builds pretty delightful—and that’s exactly what it does with Honeycomb buildevents.

Why should you create a distributed trace for your builds?

Honeycomb buildevents is a tool used to generate distributed traces from work that happens in a build pipeline. The simplest way to think of a distributed trace is as a series of interconnected logs. Each item in a trace is called a trace span, or just a span for short.

The parent span contains the entire record (or log) of everything that happened while completing one unit of work—in the case of buildevents, the unit of work is typically one build. That build might contain one or more subsequent steps, or child spans. Each span records (or logs) what happened throughout that step, including its duration.

To illustrate how this is organized, it may be easier to think of everyday activities that can be summarized as one task, yet also broken down into many individual parts. Let’s say you made dinner. The entire unit of work is “making dinner,” and that can be broken down into several individual parts: you cooked pasta and served it in a bowl. Perhaps more granularly, you can continue to decompose that into even more steps: cooking pasta includes boiling the water, opening the pasta box, and draining the pasta.

There are three main use cases for this data representation: visualizing the duration of each step in your build, accessing output details, and surfacing patterns across a number of builds (such as identifying why some builds are slower than others, or why some tests fail more than others) using Honeycomb tools like BubbleUp.

How can you start using the Honeycomb CircleCI orb in your builds?

If you’re already familiar with using Honeycomb to set up instrumentation, you can find the documentation you need in both the Honeycomb CircleCI orb repo and the Honeycomb Buildevents repo.

If these concepts are new to you, you can use our new guide, Using Honeycomb to Optimize CI/CD Delivery Pipeline Performance with CircleCI to quickly get started. It shows you how to put observability concepts into action by instrumenting a sample app and troubleshooting a few basic scenarios with Honeycomb.

What’s in the guide?

The guide is a hands-on walkthrough that shows you how to use and configure the CircleCI Buildevents orb against a sample app with a predefined build pipeline. It shows you how to:

• Use the CircleCI Buildevents orb within your CircleCI builds.
• Iteratively construct a trace by adding more incremental visibility to each step.
• Use the Honeycomb UI to visualize and debug your build pipeline.
• Avoid common pitfalls when working with both CircleCI and Honeycomb’s orb.

The sample app is a fork of the microservices-testing-examples repo, generously bequeathed to Honeycomb by André Schaffer and Dan Eidmark. It is a simple, but effective, example of many common scenarios you might encounter when using buildevents.

In order to complete the guide, you’ll need:

• A free Honeycomb account—this includes 20 million events per month, which is ample event volume to support very large and complex production build pipelines. Go nuts! It should accommodate almost all possible buildevents use cases with ease.
• A free CircleCI account to run the CI/CD pipeline.
• A copy of the guide to work from and about 30 minutes to complete the exercises.

Where to go from here

If you’ve ever wanted an easy way to get started with Honeycomb or CircleCI, this is the guide for you! The instructional content will help you navigate through useful concepts when getting started with Honeycomb, CircleCI, and buildevents.

For those already familiar, check out the Honeycomb CircleCI orb repo and the Honeycomb Buildevents repo to get started.

Check it out and let us know what you think. As always, you can pop into Pollinators to let me know what you think. Alternatively, you can find me on Twitter and I’ll be happy to answer any of your questions.