Quick Start | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

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 JavaScript documentation.

Install Modules 

In your terminal, run the commands below to install the packages required to auto-instrument a Node.js application:

npm install --save \
    @opentelemetry/sdk-node \
    @opentelemetry/exporter-trace-otlp-proto \
    @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, --require Node.js CLI option.

// tracing.js
'use strict';

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-proto");

// The Trace Exporter exports the data to Honeycomb and uses
// the environment variables for endpoint, service name, and API Key.
const traceExporter = new OTLPTraceExporter();

const sdk = new NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()

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"

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 

This is a quick start guide for Python with Flask.

Install these packages to instrument a Flask app with OpenTelemetry:

pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp-proto-http
pip install opentelemetry-instrumentation-flask
pip install opentelemetry-instrumentation-requests

Initialize 

Create a new file, tracing.py. This file will create and initialize a tracer and Flask instrumentation to send data to Honeycomb:

# tracing.py

from opentelemetry import trace
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Initialize tracing and an exporter that can send data to Honeycomb
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)

# Initialize automatic instrumentation with Flask
app = flask.Flask(__name__)
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

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"
python app.py tracing.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.3.0/honeycomb-opentelemetry-javaagent-1.3.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.3.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.3.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, ASP.NET (.NET Framework), and command line arguments.

Acquire Dependencies 

Install the Honeycomb.OpenTelemetry NuGet package.

For example, with the .NET CLI, use:

dotnet add package Honeycomb.OpenTelemetry
dotnet add package Honeycomb.OpenTelemetry.AutoInstrumentations --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.AddOpenTelemetryTracing(otelBuilder =>
    otelBuilder
        .AddHoneycomb(honeycombOptions)
        .AddAutoInstrumentations()
);

// 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();

You can find additional configuration options in our .NET documentation.

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"

    // NOTE: this import is super important as applies the Honeycomb
    // configuration to the launcher
    _ "github.com/honeycombio/honeycomb-opentelemetry-go"
    "github.com/honeycombio/opentelemetry-go-contrib/launcher"

    "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() {
    // use honeycomb distro to setup OpenTelemetry SDK
    otelShutdown, err := launcher.ConfigureOpenTelemetry()
    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. Follow the instructions in Using the OpenTelemetry Endpoint for the required configuration values.

In general, any OpenTelemetry integration should carry out these two steps:

  • Set the endpoint:
    • If using OTLP/gRPC, set OTEL_EXPORTER_OTLP_ENDPOINT to: api.honeycomb.io:443
    • If using OTLP/HTTPS, set OTEL_EXPORTER_OTLP_ENDPOINT to: https://api.honeycomb.io
  • Configure:
    • Set the x-honeycomb-team header with your API key
    • Set the name of your service specified as the service.name resource attribute

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 to Honeycomb for help via email at support@honeycomb.io.

Step 4: Explore with Honeycomb 

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

View Raw Data 

Start by familiarizing yourself with the raw data from your application in Honeycomb.

  1. In the left sidebar, select New Query.
  2. Select Run Query to run the 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 from your application are 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. In left sidebar, select 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.

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?