Quick Start

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.

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:

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

To install the Go Beeline for your application:

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

git clone https://github.com/honeycombio/beeline-go
cd beeline-go; go build

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()
  ...
}

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.

Install the Node.js Beeline package using npm:
```
npm install --save honeycomb-beeline
```

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:

Make sure your version of setuptools is up to date:
```
pip install -U setuptools
```
Install the Beeline package:
```
pip install honeycomb-beeline
```

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:

Add honeycomb-beeline to your Gemfile:
```
gem 'honeycomb-beeline'
```

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:

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

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.

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:

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?

Prerequisites 🔗

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

Choose an Instrumentation Approach for Your Application’s Language 🔗

Java Agent Configuration 🔗

Send Your Telemetry Data to Honeycomb 🔗

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

What’s Next? 🔗