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

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

Prerequisites  🔗

The recommended way to get started with Honeycomb is to instrument and deploy an existing application. In order to do that, you should have access to run, modify, and deploy source code for at least one app or service.

If you don’t have an application to instrument and deploy, but would like to see what Honeycomb can do for you, try the guided tutorials at Honeycomb Play that use pre-built data to learn what’s possible.

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 an 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 select a service or application where you will be able to:

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.

Choose an Instrumentation Approach for Your Application’s Language  🔗

There are several ways to send telemetry data to Honeycomb. The instructions below show you how to use add instrumentation to your applications using either Honeycomb’s proprietary Beelines or the OpenTelemetry open-source project. Use the tabs below to see which option is recommended based on the language you’ll be using.

In general, you’ll notice that instrumentation for each language requires you to:

  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 is what adds a basic amount of instrumentation to incoming and outgoing service requests automatically)

The Go Beeline has rich auto-instrumentation for HTTP applications.

To install the Go Beeline for your application:

  1. From your $GOPATH directory, add the Beeline package and its dependencies:

    git clone https://github.com/honeycombio/beeline-go
    cd beeline-go; go build
    
  2. In your code, import the beeline-go package and initialize it with your API key and dataset name:

    import beeline "github.com/honeycombio/beeline-go"
    
    func main() {
      beeline.Init(beeline.Config{
        // Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
        WriteKey: "YOUR_API_KEY",
        // The name of your app is a good choice to start with
        Dataset: "MyGoApp",
      })
      defer beeline.Close()
      ...
    }
    
  3. Add a Beeline wrapper in your http.ListenAndServe call. This adds basic instrumentation for each request at the outermost layer of the call stack.

    import "github.com/honeycombio/beeline-go/wrappers/hnynethttp"
    ...
    http.ListenAndServe(":8080", hnynethttp.WrapHandler(muxer))
    

If you’ve got a NodeJS Express or Fastify app, you can get request-level instrumentation for those frameworks and other supported packages you use, automatically.

  1. Install the Node.js Beeline package using npm:

    npm install --save honeycomb-beeline
    
  2. Add the following code to the top of your app.js.

    Important: It must be before any require or import statements for other packages.

    require("honeycomb-beeline")({
      // Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
      writeKey: "YOUR_API_KEY",
      // The name of your app is a good choice to start with
      dataset: "my-node-distributed-app",
      serviceName: "my-node-service"
    });
    

The auto-instrumentation agent 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.3.0/honeycomb-opentelemetry-javaagent-0.3.0-all.jar

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

Java Agent Configuration  🔗

The Honeycomb Agent has the following configuration options, which can be specified as system properties or environment variables. System properties take precedence over environment variables if both are specified.

System Property Environment Variable Description
honeycomb.api.key HONEYCOMB_API_KEY [required] Your Honeycomb API key
honeycomb.dataset HONEYCOMB_DATASET [required] Honeycomb dataset where traces will be sent
honeycomb.api.endpoint HONEYCOMB_API_ENDPOINT [optional] Honeycomb ingest endpoint (defaults to https://api.honeycomb.io:443).
sample.rate SAMPLE_RATE [optional] Sample rate for the deterministic sampler (defaults to 1, always sample)
service.name SERVICE_NAME [optional] service.name attribute to be used for all spans (defaults to empty)

These configuration options are specified when invoking the JVM. The following examples assume that the JAR file is in the current working directory. Configure the auto-instrumentation agent using environment variables:

SAMPLE_RATE=2 \
SERVICE_NAME=my-favorite-service \
HONEYCOMB_API_KEY=my-api-key \
HONEYCOMB_DATASET=my-dataset \
java -javaagent:honeycomb-opentelemetry-javaagent-0.3.0-all.jar -jar /path/to/myapp.jar

Or, configure using system properties:

java \
-Dsample.rate=2 \
-Dservice.name=my-favorite-service \
-Dhoneycomb.api.key=my-api-key \
-Dhoneycomb.dataset=my-dataset \
-javaagent:honeycomb-opentelemetry-javaagent-0.3.0-all.jar -jar /path/to/myapp.jar

To install the Python Beeline for your application:

  1. Make sure your version of setuptools is up to date:

    pip install -U setuptools
    
  2. Install the Beeline package:

    pip install honeycomb-beeline
    
  3. Initialize the Beeline by including the following at the entry point to your application:

    import beeline
    beeline.init(
        # Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
        writekey='YOUR_API_KEY',
        # The name of your app is a good choice to start with
        dataset='my-python-app',
        service_name='my-python-app',
        # debug=True, # defaults to False. if True, data doesn't get sent to Honeycomb
    )
    

With debug set to True you’ll see events being generated in your terminal output, but they won’t be sent to Honeycomb. Set debug=False to start sending events to Honeycomb.

To install the Ruby Beeline for your application:

  1. Add honeycomb-beeline to your Gemfile:

    gem 'honeycomb-beeline'
    
  2. If you have a Rails application, you can run the generator to create your configuration file:

    bundle exec rails generate honeycomb YOUR_API_KEY --dataset your-dataset-name
    

    Otherwise in your code, initialize the Beeline with your API key and dataset name:

    Honeycomb.configure do |config|
      # Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
      config.write_key = 'YOUR_API_KEY'
      # The name of your app is a good choice to start with
      config.dataset = 'my-ruby-app'
    end
    

Don’t see your language listed in the tabs above? Do you have other types of telemetry you want to send to Honeycomb? Check out our list of other available integrations.

Send Your Telemetry Data to Honeycomb  🔗

So far, you’ve only configured your application to send telemetry for inbound and outbound requests to Honeycomb. Next, you need to make requests to your service in order to generate telemetry that is then sent to Honeycomb:

  1. Run your code in a development environment
  2. Interact with your service and make a few requests
  3. Telemetry data should now appear in the Honeycomb UI

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’ve made several service requests in your development environment and you still don’t see any data after several minutes, something may be wrong. Reach out to Honeycomb for help by clicking the chat icon on the bottom right hand corner of this page.

Step 3: View Your Telemetry Data from the Honeycomb UI  🔗

You have instrumented your code, run that code in a development environment, and made a few requests to that running service. Now, you should be able to see 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’ve 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’ve 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: