Quick Start | Honeycomb

Quick Start

Honeycomb is a fast analysis tool that reveals how your code is experienced in complex and unpredictable environments. Troubleshoot complex relationships within your distributed services and solve problems faster.

Tip: Check out this interactive demo to see what Honeycomb can do for you with no set-up required.

These instructions walk you through sending data from your local development environment. Follow these steps to start your observability journey with Honeycomb.

  1. Create a free Honeycomb account
  2. Name your team
  3. Send data to Honeycomb
  4. Explore your data

After you have completed these steps, deploy to production to start gaining new insights on real traffic!

Prerequisites 

To successfully complete this Quick Start, you should have access to modify and run source code for at least one application or service. The instructions below show you how to auto-instrument the application for fast validation and ease.

Don’t have access to an application? Here are a few example applications that you can use.

If you do not want to instrument and deploy an application, but would like to see what Honeycomb can do for you, learn what is possible from the guided tutorials at our Honeycomb sandbox.

Step 1: Sign Up for Honeycomb 

Honeycomb has a free usage tier. If you do not already have an account, sign up for a free Honeycomb account.

Sign up here.

Step 2: Name Your Team 

In order to complete your account creation, give us a “team” name.

A team organizes a group of users' access to data and creates a shared work history in Honeycomb. We recommend using your company or organization name.

Step 3: Instrument Your Application to Send Telemetry Data to Honeycomb 

Pick a single application or service that will send telemetry data to Honeycomb. You must be able to run your application or service in a development environment to test the instrumentation you have added.

If you would like to try Honeycomb using example data, use one of our example applications.

Add Auto-Instrumentation to Your Application 

There are several ways to send telemetry data to Honeycomb. The instructions below show you how to add instrumentation to your applications using OpenTelemetry. Use the tabs below to see which option is recommended based on the language you will be using.

This Quick Start uses the npm dependency manager. For instructions with yarn, refer to our OpenTelemetry Node.js documentation.

If using TypeScript, refer to our OpenTelemetry Node.js documentation for instructions.

Install Modules 

Install the Honeycomb OpenTelemetry Node.js Distribution package:

npm install --save \
    @honeycombio/opentelemetry-node \
    @opentelemetry/auto-instrumentations-node

auto-instrumentations-node is a meta package that provides a way to initialize multiple Node.js instrumentations like express, dns, http, and more. Alternatively, you can install individual instrumentation packages.

Initialize 

Create an initialization file, commonly known as the tracing.js file, and import it as the first step in your application lifecycle. Alternatively, include this initialization file with the -r or --require Node.js CLI option.

// tracing.js
'use strict';

const { HoneycombSDK } = require('@honeycombio/opentelemetry-node');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');

// uses HONEYCOMB_API_KEY and OTEL_SERVICE_NAME environment variables
const sdk = new HoneycombSDK({
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()

Configure and Run 

Configure the Honeycomb Distribution for Node.js using environment variables.

Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored. The service name is specified by OTEL_SERVICE_NAME.

export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"

Run the Node.js app with the OpenTelemetry initialization file to generate data:

node -r ./tracing.js APPLICATION_MAIN_FILE.js

This Quick Start uses the pip package manager. For instructions with poetry, refer to the OpenTelemetry Python documentation.

Install Packages 

First, install the honeycomb-opentelemetry package.

python -m pip install honeycomb-opentelemetry --pre

Second, install instrumentation libraries for the packages used by your application. The recommended way is to use the opentelemetry-bootstrap tool that comes with the OpenTelemetry SDK to scan your application packages to get the list of available libraries. By default, the tool prints out the instrumentation libraries that are available, but it can also install them directly for you too.

opentelemetry-bootstrap --action=install

Configure and Run 

Configure the Honeycomb Distribution for Python using environment variables.

Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored. The service name is specified by OTEL_SERVICE_NAME.

export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"

Now you can run your application using the OpenTelemetry Python automatic instrumentation tool opentelemetry-instrument, which configures the OpenTelemetry SDK, and see traces for your app:

opentelemetry-instrument python myapp.py

Acquire Dependencies 

The auto-instrumentation agent for Honeycomb OpenTelemetry Java will automatically generate trace data from your application. The agent is packaged as a JAR file and is run alongside your app.

In order to use the auto-instrumentation agent, you must first download it:

curl -LO https://github.com/honeycombio/honeycomb-opentelemetry-java/releases/download/v1.5.0/honeycomb-opentelemetry-javaagent-1.5.0.jar

Configure 

Choose from one of the following configuration options:

Use environment variables:

SERVICE_NAME=my-favorite-service
HONEYCOMB_API_KEY=my-api-key
HONEYCOMB_METRICS_DATASET=my-metrics

Or, use system properties:

sample.rate=2
service.name=my-favorite-service
honeycomb.api.key=my-api-key
honeycomb.metrics.dataset=my-metrics

and set an environment variable with a path to your properties file:

HONEYCOMB_CONFIG_FILE=/path/to/properties/file

Run 

Run your app with the auto-instrumentation agent as a sidecar:

java -javaagent:honeycomb-opentelemetry-javaagent-1.5.0.jar -jar /path/to/myapp.jar

You can also include configuration values with an invocation of your app, like so:

java \
-Dhoneycomb.config.file=/path/to/properties/file \
-javaagent:honeycomb-opentelemetry-javaagent-1.5.0.jar -jar /path/to/myapp.jar

Refer to our Java documentation for more configuration options.

This Quick Start uses ASP.NET Core. For other .NET configuration options, refer to the OpenTelemetry .NET documentation on programmatic and ASP.NET (.NET Framework) configuration.

Acquire Dependencies 

Install the Honeycomb.OpenTelemetry NuGet package.

For example, with the .NET CLI, use:

dotnet add package Honeycomb.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package Honeycomb.OpenTelemetry.CommonInstrumentations --prerelease

Initialize 

Initialize your ASP.NET Core app to use the Honeycomb OpenTelemetry Distribution for .NET:

In your appsettings.json file, add a Honeycomb section like so:

{
  "Honeycomb": {
    "ServiceName": "my-app",
    "ApiKey": "{apikey}"
  }
}

Then get HoneycombOptions from configuration and use them to configure the OpenTelemetry SDK in your application startup code:

using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var honeycombOptions = builder.Configuration.GetHoneycombOptions();

// Setup OpenTelemetry Tracing
builder.Services.AddOpenTelemetry().WithTracing(otelBuilder =>
{
    otelBuilder
        .AddHoneycomb(honeycombOptions)
        .AddCommonInstrumentations();
});

// Register Tracer so it can be injected into other components (for example, Controllers)
builder.Services.AddSingleton(TracerProvider.Default.GetTracer(honeycombOptions.ServiceName));

var app = builder.Build();

app.MapGet("/", (Tracer tracer) =>
{
    using var span = tracer.StartActiveSpan("app.manual-span");
    span.SetAttribute("app.manual-span.message", "Adding custom spans is also super easy!");
});

await app.RunAsync();

Run 

You can now run your app, and you will see the incoming requests and outgoing HTTP calls generate traces.

dotnet run

Refer to our .NET documentation for all configuration options and ways to run your application.

Acquire Dependencies 

Install the Honeycomb OpenTelemetry Go Distribution package:

go get github.com/honeycombio/honeycomb-opentelemetry-go \
  go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

Initialize 

Configure your application to send spans to Honeycomb.

Open or create a file called main.go:

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/honeycombio/honeycomb-opentelemetry-go"
    "github.com/honeycombio/otel-config-go/otelconfig"

    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

// Implement an HTTP Handler func to be instrumented
func httpHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello, World")
}

// Wrap the HTTP handler func with OTel HTTP instrumentation
func wrapHandler() {
    handler := http.HandlerFunc(httpHandler)
    wrappedHandler := otelhttp.NewHandler(handler, "hello")
    http.Handle("/hello", wrappedHandler)
}

func main() {
    // enable multi-span attributes
    bsp := honeycomb.NewBaggageSpanProcessor()

    // use honeycomb distro to setup OpenTelemetry SDK
    otelShutdown, err := otelconfig.ConfigureOpenTelemetry(
        otelconfig.WithSpanProcessor(bsp),
    )
    if err != nil {
        log.Fatalf("error setting up OTel SDK - %e", err)
    }
    defer otelShutdown()

    // Initialize HTTP handler instrumentation
    wrapHandler()
    log.Fatal(http.ListenAndServe(":3030", nil))
}

Configure and Run 

Configure the Honeycomb Distribution for Go using environment variables.

Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored. The service name is specified by OTEL_SERVICE_NAME.

export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"

Now you can run your application and see traces created for each incoming HTTP request:

go run main.go

Acquire Dependencies 

Add these gems to your Gemfile:

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'

The inclusion of opentelemetry-instrumentation-all above provides instrumentation for Rails, Sinatra, several HTTP libraries, and more.

Initialize 

OpenTelemetry initialization must occur early in your application lifecycle. For Rails applications, the usual way to initialize OpenTelemetry is in a Rails initializer. For other Ruby services, perform this initialization as early as possible in the start-up process.

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
    c.use_all() # enables all instrumentation!
end

Configure and Run 

Configure OpenTelemetry to send events to Honeycomb using environment variables.

The header x-honeycomb-team is your API key. Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored. The service name is specified by OTEL_SERVICE_NAME.

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
export OTEL_SERVICE_NAME="your-service-name"

You can now run your Ruby app to automatically generate traces.

If your preferred language is not covered here, use the OpenTelemetry community documentation to find relevant instrumentation details.

For Rust, we recommend to use the opentelemetry and opentelemetry-otlp crates to send data over OTLP to Honeycomb.

Refer to the Using the Honeycomb OpenTelemetry Endpoint for the required configuration values.

Generate Data 

After running your application in your local development environment, interact with your application by making a few requests. By making requests to your service, you will generate the telemetry that will be sent to Honeycomb.

Telemetry data should now appear in the Honeycomb UI. Next, start querying your data.

You must complete the actions above or you will not see any data in the next step.

In the Honeycomb UI, you should see data appear within seconds of making your first request. If you have made several service requests in your development environment and you still do not see any data after several minutes, something may be wrong. Reach out for help in our Pollinators Community Slack.

Step 4: Explore with Honeycomb 

Honeycomb is designed to let you explore your systems in novel ways and find problems faster. Here is how to learn and explore your data.

View Raw Data 

Start by exploring yourself with the raw data from your applications in Honeycomb.

  1. From the left sidebar, navigate to New Query.
  2. Select Run Query to run an empty query.

An animated gif where after a blank new query is run, the user selects the Raw Data tab to show the rows of available raw data.

Raw events data from your application is displayed in a table. Take a moment to notice the fields that are included and how events are laid out.

Group By and Filter 

Choose a field and group by it to get a more granular view. We will use http.status_code in this example.

  1. In GROUP BY, enter http.status_code. Select Run Query. You will see events grouped by codes like 200 or 404, depending on your application.
  2. Next to one of the rows, select the ellipsis icon. In the menu, select Show only events in this group. You will see all events that contain that value, charted over time.

An animated gif where the user selects the ellipsis icon for the field and then selects the “Group By http.status_code” option, and the screen changes to display the results.

View, group by, and filter your raw data to highlight the basic shape of your data and the fields available for analysis. Later, you can add manual instrumentation for a richer view.

View a Sample Trace 

Traces are visual diagrams of all the events that occur in a single operation as it traverses an application. They are made up of the structured events (seen above) that you send, and tied together by a Trace ID. Traces help you find the source of errors in a system, identify the slowest processes, and break down the user experience in great detail.

  1. Select the Traces tab. Below the chart, you will see up to 10 of the slowest traces.
  2. Select the Trace ID to view that trace.

An animated gif where after selecting the Traces tab, the user selects an individual trace ID to see its Trace Detail View.

This view is called the trace waterfall. It shows the spans within the trace, how long each one took, which contain errors, and additional metadata. Tracing is a powerful way to find performance problems and understand how data flows through a large system. Learn more about traces.

Query and Visualize 

Now that you have taken a tour of your data, query it to answer a question about your system.

For example: How many events contain a certain error? What is the average latency and distribution of those events?

  1. From the left sidebar, navigate to New Query.
  2. In the VISUALIZE clause, add: COUNT AVG(duration_ms) HEATMAP(duration_ms)
  1. Select Run Query.

An animated gif where the user updates the Visualize clause to include Count, Avg(duration_ms), and Heatmap(duration_ms), selects Run Query, and views the results.

You will see a stack of charts: a count of events, an average latency for those events, and a heatmap of latency.

Zoom into the chart. Click and drag around an area you would like to see. Click the magnifying glass icon to zoom.

Look for patterns and outliers. As you add instrumentation, your charts get enriched with more data.

Querying and visualizing your data is a core practice for flexible exploration in Honeycomb. Many developers investigate using an iterative process called the core analysis loop.

Bonus: Explore Anomalies 

Using the heatmap of duration_ms, analyze outliers in your data with the BubbleUp feature.

  1. Navigate to the BubbleUp tab.
  2. Click and drag a box around some data that looks a little different from the rest. Choose data points that stand out.

An animated gif where the user selects the BubbleUp tab, selects a range within the visualized data to use the BubbleUp feature, and examines the Dimensions results that appear below the visualized data.

The small charts that appear below analyze your selected events by each available dimension and measure.

BubbleUp is a unique Honeycomb approach that intelligently surfaces useful signals in your data. Visually identify what stands out and deep dive into your data. BubbleUp enables you to quickly drill into high-cardinality data like userID, loan type, system request - any attribute that is important to your business.

Well done! You have completed the Honeycomb Quick Start and started on the path to modern observability.

Step 5: Enhance Your Trace Data with Custom Instrumentation 

Seeing traces with limited spans in Honeycomb.io? This isn’t a sign of missing data; it’s a cue to expand your application’s capacity with custom instrumentation. Don’t forget, it’s only after adding custom instrumentation that you can analyze fields like user.id and other business-specific data.

Initiate Custom Instrumentation 

To help you get started, we provide an array of code snippets including: JavaScript, Go, Python, Ruby, Java, or .NET. These snippets generate spans, produce events, and incorporate relevant metadata.

Why Custom Instrumentation? 

Custom instrumentation enables you to:

  • Extract business-specific metrics and user behavior data.
  • Improve error monitoring and troubleshooting.
  • Gain an overarching view of complex distributed systems.

What is Next? 

Now that you have done the basics, here are some places to go next:

Did you find what you were looking for?