1. Docs
2. Quick Start

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.

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.

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.

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.

npm install --save \
    @opentelemetry/sdk-node@0.27.0 \
    @opentelemetry/exporter-trace-otlp-proto@0.27.0 \
    @opentelemetry/auto-instrumentations-node@0.28.0

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

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"

node -r ./tracing.js APPLICATION_MAIN_FILE.js

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

# 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()

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

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

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

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

HONEYCOMB_CONFIG_FILE=/path/to/properties/file

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

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

dotnet add package Honeycomb.OpenTelemetry --prerelease

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

using Honeycomb.OpenTelemetry;

// ...

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // configure OpenTelemetry SDK to send data to Honeycomb
    services.AddHoneycomb(Configuration);
}

dotnet run

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/trace \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
  go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

package main

import (
    "context"
    "fmt"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/propagation"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"

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

func newExporter(ctx context.Context) (*otlptrace.Exporter, error) {
    client := otlptracehttp.NewClient()
    return otlptrace.New(ctx, client)
}

func newTraceProvider(exp *otlptrace.Exporter) *sdktrace.TracerProvider {
    return sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),
    )
}

// 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() {
    ctx := context.Background()

    // Configure a new exporter using environment variables for sending data to Honeycomb over gRPC.
    exp, err := newExporter(ctx)
    if err != nil {
        log.Fatalf("failed to initialize exporter: %v", err)
    }

    // Create a new tracer provider with a batch span processor and the otlp exporter.
    tp := newTraceProvider(exp)

    // Handle this error in a sensible manner where possible
    defer func() { _ = tp.Shutdown(ctx) }()

    // Set the Tracer Provider and the W3C Trace Context propagator as globals
    otel.SetTracerProvider(tp)

    // Register the trace context and baggage propagators so data is propagated across services/processes.
    otel.SetTextMapPropagator(
        propagation.NewCompositeTextMapPropagator(
            propagation.TraceContext{},
            propagation.Baggage{},
        ),
    )

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

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"

go run main.go

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

# 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

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"

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.

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.

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.

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.

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)

3. Select Run Query.

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.

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:

• Add attributes to spans: Add high-cardinality data for better insights. Choose from JavaScript, Go, Python, Ruby, Java, or .NET.
• Explore common scenarios with real data in Honeycomb’s sandbox.
• DevRel Office Hours: Join in on observability talk with world-class experts.
• Check out other types of data you can use with Honeycomb.

Did you find what you were looking for?

Yes No

Additional Feedback (Optional)

---

Submit