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

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

  1. Sign up for a free Honeycomb account
  2. Instrument an application to send telemetry data to Honeycomb
  3. View your telemetry data from the Honeycomb UI

After you’ve 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.

To get the most out of Honeycomb’s features, we recommend that you instrument your code using auto-instrumentation.

If you don’t have an application to instrument and deploy, but would like to see what Honeycomb can do for you, you can learn what’s possible from the guided tutorials at Honeycomb Play.

Step 1: Sign Up for Honeycomb  🔗

Honeycomb has a free usage tier. If you don’t already have an account, sign up for a free Honeycomb account.

During the sign-up process, you will:

  1. Create a team. We recommend using a name that represents your organization.
  2. Receive a unique API key that allows you to send data to Honeycomb. Keep this key handy as you will need it in the next step.

Sign up here.

Step 2: Instrument Your Application to Send Telemetry Data to Honeycomb  🔗

Pick a single application or service that will send telemetry data to Honeycomb.

In order to complete this step, you must be able to run your application or service in a development environment to test the instrumentation you’ve added.

Later, you can deploy those changes to production according to your team’s deployment processes. Deploying to production is not a hard requirement of getting started with Honeycomb, but you will get a much better understanding of how Honeycomb works when you start analyzing real traffic.

Add Auto-Instrumentation to Your Application  🔗

There are several ways to send telemetry data to Honeycomb. The instructions below show you how to use 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.

Each language’s instructions include the same general steps:

  1. Configure the Honeycomb dataset name where your application will send data.
  2. Configure the Honeycomb API key used for authentication.
  3. Invoke the instrumentation package during initialization. This step automatically adds a basic amount of instrumentation to incoming and outgoing service requests.

Before you can instrument your Go application with OpenTelemetry, you first have to fetch the appropriate packages and add them to your go.mod file. Run the following command from the directory with your go.mod file:

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/otlptracegrpc

Next, we’ll need to configure an exporter that will send spans to Honeycomb.

Open or create a file called main.go:

package main

import (
	"context"
	"log"
	"os"

	"google.golang.org/grpc/credentials"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	"go.opentelemetry.io/otel/propagation"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.7.0"
)

func newExporter(ctx context.Context) (*otlptrace.Exporter, error) {
	opts := []otlptracegrpc.Option{
		otlptracegrpc.WithEndpoint("api.honeycomb.io:443"),
		otlptracegrpc.WithHeaders(map[string]string{
			"x-honeycomb-team":    os.Getenv("HONEYCOMB_API_KEY"),
			"x-honeycomb-dataset": os.Getenv("HONEYCOMB_DATASET"),
		}),
		otlptracegrpc.WithTLSCredentials(credentials.NewClientTLSFromCert(nil, "")),
	}

	client := otlptracegrpc.NewClient(opts...)
	return otlptrace.New(ctx, client)
}

func newTraceProvider(exp *otlptrace.Exporter) *sdktrace.TracerProvider {
    // The service.name attribute is required.
	resource :=
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceNameKey.String("ExampleService"),
		)

	return sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exp),
		sdktrace.WithResource(resource),
	)
}

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{},
		),
	)
}

Adding Auto-Instrumentation  🔗

The OpenTelemetry-Go Contrib repo contains extensions that provide automatic instrumentation for many popular libraries.

If you are writing a web application in Go, you can use the extensions in this repository to automatically generate and export spans from your application to Honeycomb.

In this example, we’ll focus on auto-instrumentation for servers that use the net/http package, but other popular muxers are supported.

From the directory containing your go.mod file, run the following command:

go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

We can now wrap our http handler functions in the net/http auto-instrumentation middleware:

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

// ...

// Have some http handler function to instrument
func httpHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello, World")
}

// Wrap the httpHandler function above with OTel instrumentation
handler := http.HandlerFunc(httpHandler)
wrappedHandler := otelhttp.NewHandler(handler, "hello")
http.Handle("/hello", wrappedHandler)

// And start the HTTP server
log.Fatal(http.ListenAndServe(":3030", nil))

Spans will now be auto-generated whenever requests are served from the handler.

To auto-instrument your Node.js Express application, you need to add the following packages:

npm install --save @grpc/grpc-js
npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-node
npm install --save @opentelemetry/exporter-trace-otlp-grpc
npm install --save @opentelemetry/auto-instrumentations-node

auto-instrumentations-node is a meta package that provides a simple way to initialize multiple Node.js instrumentations. Alternatively, you can install individual instrumentations.

JavaScript OpenTelemetry Initialization  🔗

The OpenTelemetry initialization needs to happen first in your application lifecycle. You can accomplish this by creating an initialization file. You can then import the file as the first step in you application initialization, or include it with the -r, --require Node.js CLI option.

OpenTelemetry initialization:

// tracing.js

const process = require('process');
const { Metadata, credentials } = require("@grpc/grpc-js");

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");

const metadata = new Metadata()
metadata.set('x-honeycomb-team', '<YOUR_API_KEY>');
metadata.set('x-honeycomb-dataset', '<YOUR_DATASET>');
const traceExporter = new OTLPTraceExporter({
  url: 'grpc://api.honeycomb.io:443/',
  credentials: credentials.createSsl(),
  metadata
});

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: '<YOUR_SERVICE_NAME>',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()
  .then(() => console.log('Tracing initialized'))
  .catch((error) => console.log('Error initializing tracing', error));

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Running the Node.js app with OpenTelemetry initialization file:

node -r ./tracing.js app.js

You can see a complete example here.

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 specified as a command-line argument when invoking the Java Virtual Machine (JVM).

In order to use the auto-instrumentation agent, you must first download and distribute the JAR file.

The agent JAR file must be available when running the java process that starts your service. The file can be downloaded from the GitHub Releases page or you can download it with a CLI tool like curl:

curl -LO https://github.com/honeycombio/honeycomb-opentelemetry-java/releases/download/v0.7.0/honeycomb-opentelemetry-javaagent-0.7.0.jar

Once the JAR file is downloaded, you can configure the agent with Honeycomb credentials.

Java Agent Configuration  🔗

At a minimum, you need to configure the Honeycomb Agent with your API key and datasets. Choose from one of three configuration options.

  1. Configure using environment variables. For example:
SERVICE_NAME=my-favorite-service \
HONEYCOMB_API_KEY=my-api-key \
HONEYCOMB_TRACES_DATASET=my-traces \
HONEYCOMB_METRICS_DATASET=my-metrics \
java -javaagent:honeycomb-opentelemetry-javaagent-0.7.0.jar -jar /path/to/myapp.jar
  1. Configure using system properties. For example:
java \
-Dsample.rate=2 \
-Dservice.name=my-favorite-service \
-Dhoneycomb.api.key=my-api-key \
-Dhoneycomb.traces.dataset=my-traces \
-Dhoneycomb.metrics.dataset=my-metrics \
-javaagent:honeycomb-opentelemetry-javaagent-0.7.0.jar -jar /path/to/myapp.jar
  1. Configure using a properties file and either set an environment variable or system property. For example, in the myapp.properties file:
sample.rate=2
service.name=my-favorite-service
honeycomb.api.key=my-api-key
honeycomb.traces.dataset=my-traces
honeycomb.metrics.dataset=my-metrics

Use an environment variable:

HONEYCOMB_CONFIG_FILE=/path/to/file \
java -javaagent:honeycomb-opentelemetry-javaagent-0.7.0.jar -jar /path/to/myapp.jar

Or, use a system property:

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

The complete list of configuration options can be found at Advanced Configuration.

Install the Honeycomb.OpenTelemetry nuget package using a NuGet package manager or the dotnet CLI.

For example, with the dotnet CLI, use:

dotnet add package Honeycomb.OpenTelemetry --prerelease

Configure your app for Honeycomb OpenTelemetry Distribution for .NET with one of the following configuration methods:

Programmatically  🔗

You can provide an HoneycombOptions object to programmatically configure the OpenTelemetry SDK.

using OpenTelemetry;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddHoneycomb(new HoneycombOptions
    {
        ServiceName = "my-app",
        ApiKey = "{apikey}",
        Dataset = "{dataset}"
    })
    .Build();

ASP.NET Core  🔗

You can provide an appsettings.json file:

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

Then, pass the IConfiguration object to configure the OpenTelemetry SDK in your application startup code:

using Honeycomb.OpenTelemetry;

public IConfiguration Configuration { get; }

//...

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

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

NOTE: It is possible to leverage the AppSettings ability to read environment variables to populate values in the configuration object. For example, the following environment variables could be used to override the values in an AppSettings file:

export HONEYCOMB__SERVICENAME=my-app
export HONEYCOMB__APIKEY={apikey}
export HONEYCOMB__DATASET={dataset}

See the OpenTelemetry ASP.NET Core instrumentation for more advanced options.

ASP.NET (.NET Framework v4.6.1+)  🔗

Add the following to your Web.config:

<system.webServer>
    <modules>
    <add name="TelemetryCorrelationHttpModule"
         type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule,Microsoft.AspNet.TelemetryCorrelation"
         preCondition="integratedMode,managedHandler" />
    </modules>
</system.webServer>

Configure the OpenTelemetry SDK to use Honeycomb during application start:

using OpenTelemetry;
using OpenTelemetry.Trace;
using Honeycomb.OpenTelemetry;

public class WebApiApplication : HttpApplication
{
    private TracerProvider _tracerProvider;

    protected void Application_Start()
    {
        _tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddHoneycomb(new HoneycombOptions
            {
                ServiceName = "my-app",
                ApiKey = "{apikey}",
                Dataset = "{dataset}"
            })
            .Build();
    }

    protected void Application_End()
    {
        _tracerProvider?.Dispose();
    }
}

See the OpenTelemetry ASP.NET instrumentation for more advanced options.

Command Line Arguments  🔗

You can provide command line arguments when starting your application:

dotnet run \
  --service-name=my-app \
  --honeycomb-apikey={apikey} \
  --honeycomb-dataset={dataset}

Then, pass the command line arguments to configure the OpenTelemetry SDK:

using OpenTelemetry;

//...

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddHoneycomb(args)
    .Build();

NOTE: AddHoneycomb sets the OpenTelemetry SDK ResourceBuilder, which is used to create the Resource that is associated to all spans created by the tracer. Please do not override the ResourceBuilder by calling SetResourceBuilder with another instance. Otherwise, some resource attributes may not be queryable in your Honeycomb data.

To instrument your Python app with OpenTelemetry, you will need to install these packages:

pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp-proto-grpc

Next, we need to create and configure a tracer instance. Here we’ll use some OpenTelemetry components to describe our app and set up an exporter that will send spans to Honeycomb.

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from grpc import ssl_channel_credentials

# resource describes app-level information that will be added to all spans
resource = Resource(attributes={
    "service.name": os.environ.get("SERVICE_NAME")
})

# create new trace provider with our resource
trace_provider = TracerProvider(resource=resource)

# create exporter to send spans to Honeycomb
otlp_exporter = OTLPSpanExporter(
    endpoint="api.honeycomb.io:443",
    insecure=False,
    credentials=ssl_channel_credentials(),
    headers=(
        ("x-honeycomb-team", os.environ.get("HONEYCOMB_API_KEY")),
        ("x-honeycomb-dataset", os.environ.get("HONEYCOMB_DATASET"))
    )
)

# register exporter with provider
trace_provider.add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)

# register trace provider
trace.set_tracer_provider(trace_provider)

Note that we’re setting a few configuration options using environment variables. You can set these as inline environment variables like this when starting your python app:

HONEYCOMB_API_KEY=my-api-key \
HONEYCOMB_DATASET=my-dataset \
SERVICE_NAME=my-favorite-service \
python app.py

To auto-instrument your Ruby application, add these gems to your Gemfile:

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

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

Ruby OpenTelemetry Initialization  🔗

The OpenTelemetry initialization needs to happen 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.

OpenTelemetry initialization:

# 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

Environment configuration:

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

A complete example can be viewed here.

If you don’t see your language listed in the tabs above, but you have other types of telemetry you want to send to Honeycomb, we suggest you use OpenTelemetry instrumentation for your language.

Send Your Telemetry Data to Honeycomb  🔗

So far, you have configured your application to send telemetry to Honeycomb for any inbound or outbound requests. Next, you will need to make requests to your service in order to generate the telemetry that will be sent to Honeycomb.

  1. Run your application in your local development environment
  2. Interact with your application by making a few requests

Telemetry data should now appear in the Honeycomb UI! Continue to the next step to 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 chat .

Step 3: Query Your Telemetry Data in the Honeycomb UI  🔗

Now that you have instrumented your code, run that code in a development environment, and made a few requests to that running service, you can start interacting with your telemetry data in the Honeycomb UI.

  1. Return to the Honeycomb UI
  2. If you have a new account, there should only be one existing dataset and you will see it by default. If you are completing these steps with a pre-existing account, ensure you are viewing the correct dataset. In the left navigation bar, select Datasets, then select the name of the dataset you configured in Step 2
  3. In the left nav bar, select New Query. You are now using Honeycomb’s Query Builder, an interface that allows you to visualize and retrieve data that you find interesting
  4. Select the VISUALIZE section. A text box now appears and you can enter a desired visualization for your data
  5. Enter COUNT into the text box in the VISUALIZE section
  6. Select RUN QUERY

Congratulations! You have retrieved your first bits of telemetry data using Honeycomb.

Right now, you are seeing the overall count of the events that have been sent to Honeycomb by your application. Try another query:

  1. Select GROUP BY, and in the text box that appears, type in name
  2. Select RUN QUERY

Now, you are seeing the different types of requests you submitted to your application, grouped by name. Below the visualization graph, you’ll see a table that lists each type of request you have sent to your service and a count of how many times it has been sent.

Try making new requests to the service you are running in your development environment. Then return to the Query Builder and run your queries again. What else do you notice Honeycomb showing you about how you interacted with your service?

What’s Next?  🔗

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

  • Deploy your instrumented application to start gaining new insights on real traffic!
  • Explore trace data: Select one of your requests in the graph to pull up Trace View
  • Add custom instrumentation: Start adding custom telemetry to better understand how your unique application behaves. Choose from Go, Python, JavaScript, Ruby, Java, or .NET.
  • Consider deploying your instrumented code to production: start analyzing real user requests with Honeycomb
  • Visit the other integrations section of our docs to learn about other data you can use with Honeycomb, such as structured logs