While the Honeycomb distributions of the OpenTelemetry SDKs are not yet deprecated, they are in maintenance.
Honeycomb provides the Honeycomb OpenTelemetry Distribution for Go to help you instrument your applications and send telemetry data to Honeycomb as quickly and easily as possible. Under the hood, the Honeycomb Distribution uses OpenTelemetry for Go, so advanced users or those who have already instrumented their applications with OpenTelemetry do not need to use this Distribution.
The Honeycomb Distribution reads variables you provide and translates them to variables understood by the upstream OpenTelemetry SDK.
For example, the Honeycomb Distribution automatically configures exporters to send telemetry data to Honeycomb’s API (if you are using our US instance, api.honeycomb.io
, or if you are using our EU instance, api.eu1.honeycomb.io
).
If you want to send data to Honeycomb using OpenTelemetry without the Honeycomb Distribution, you will need to configure your implementation to match variables expected by OpenTelemetry.
In this guide, we explain how to set up automatic and custom, or manual, instrumentation for a service written in Go. If you prefer learning by example, we provide an example of an application configured to send OpenTelemetry data to Honeycomb using the Honeycomb OpenTelemetry Distribution for Go.
Before you can set up instrumentation for your Go application, you will need to do a few things.
To complete the required steps, you will need:
To send data to Honeycomb, you’ll need to sign up for a free Honeycomb account and create a Honeycomb Ingest API Key. To get started, you can create a key that you expect to swap out when you deploy to production. Name it something helpful, perhaps noting that it’s a getting started key. Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later!
If you want to use an API key you previously stored in a secure location, you can also look up details for Honeycomb API Keys any time in your Environment Settings, and use them to retrieve keys from your storage location.
This section describes adding automatic instrumentation using instrumentation libraries with the OpenTelemetry Go SDK. For automatic instrumentation using eBPF, visit Automatic Instrumentation using eBPF.
Install the Honeycomb OpenTelemetry Go Distribution package:
go get github.com/honeycombio/honeycomb-opentelemetry-go \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
Prepare your application to send spans to Honeycomb.
Open or create a file called main.go
:
package main
import (
"fmt"
"log"
"net/http"
"github.com/honeycombio/honeycomb-opentelemetry-go"
"github.com/honeycombio/otel-config-go/otelconfig"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
// Implement an HTTP Handler function to be instrumented
func httpHandler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, World")
}
// Wrap the HTTP handler function with OTel HTTP instrumentation
func wrapHandler() {
handler := http.HandlerFunc(httpHandler)
wrappedHandler := otelhttp.NewHandler(handler, "hello")
http.Handle("/hello", wrappedHandler)
}
func main() {
// Enable multi-span attributes
bsp := honeycomb.NewBaggageSpanProcessor()
// Use the Honeycomb distro to set up the OpenTelemetry SDK
otelShutdown, err := otelconfig.ConfigureOpenTelemetry(
otelconfig.WithSpanProcessor(bsp),
)
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))
}
Use environment variables to configure the Honeycomb OpenTelemetry Go distribution package:
export HONEYCOMB_API_ENDPOINT="https://api.honeycomb.io:443" # US instance
#export HONEYCOMB_API_ENDPOINT="https://api.eu1.honeycomb.io:443" # EU instance
export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"
Variable | Description |
---|---|
HONEYCOMB_API_ENDPOINT |
Honeycomb endpoint to which you want to send your data. |
OTEL_SERVICE_NAME |
Service name. When you send data, Honeycomb creates a dataset in which to store your data and uses this as the name. Can be any string. |
HONEYCOMB_API_KEY |
Your API Key generated in Honeycomb. Learn how to find your Honeycomb API Key. |
If you use Honeycomb Classic, you must also specify the Dataset using the HONEYCOMB_DATASET
environment variable.
export HONEYCOMB_DATASET="your-dataset"
Explore all configuration options for the Honeycomb Distribution:
Environment Variable | Default Value | Description |
---|---|---|
HONEYCOMB_API_KEY |
None | [required – see note below] Your Honeycomb API key |
OTEL_SERVICE_NAME |
unknown_service |
[required – see note below] service.name attribute, where all trace data is sent |
HONEYCOMB_TRACES_APIKEY |
Value of HONEYCOMB_API_KEY |
Your Honeycomb API key for sending traces |
HONEYCOMB_METRICS_APIKEY |
Value of HONEYCOMB_API_KEY |
Your Honeycomb API key for sending metrics |
HONEYCOMB_METRICS_DATASET |
None | Honeycomb dataset where metrics will be sent |
HONEYCOMB_API_ENDPOINT |
https://api.honeycomb.io:443 (US instance)https://api.eu1.honeycomb.io:443 (EU instance) |
Honeycomb ingest endpoint. |
HONEYCOMB_TRACES_API_ENDPOINT |
Value of HONEYCOMB_API_ENDPOINT |
Honeycomb ingest endpoint for traces (defaults to the value of HONEYCOMB_API_ENDPOINT ). |
HONEYCOMB_METRICS_API_ENDPOINT |
Value of HONEYCOMB_API_ENDPOINT |
Honeycomb ingest endpoint for metrics (defaults to the value of HONEYCOMB_API_ENDPOINT ). |
SAMPLE_RATE |
1 (retain all data) |
Sample rate for the deterministic sampler. Must be a positive integer. |
OTEL_METRICS_ENABLED |
false |
Enable metrics export (metrics dataset must be configured as well) |
HONEYCOMB_ENABLE_LOCAL_VISUALIZATIONS |
false |
Enable local visualizations |
DEBUG |
false |
Enable debug mode |
Run your application:
go run YOUR_APPLICATION_NAME.go
Be sure to replace YOUR_APPLICATION_NAME
with the name of your application’s main file.
In Honeycomb’s UI, you should now see your application’s incoming requests and outgoing HTTP calls generate traces.
Automatic instrumentation is the easiest way to get started with instrumenting your code. To get additional insight into your system, you should also add custom, or manual, instrumentation where appropriate.
To learn more about custom, or manual, instrumentation, visit the comprehensive set of topics covered by Manual Instrumentation for Go in OpenTelemetry’s documentation.
To create spans, you need to acquire a Tracer
.
import (
// ...
"go.opentelemetry.io/otel"
// ...
)
// ...
tracer := otel.Tracer("tracer.name.here")
When you create a Tracer
, OpenTelemetry requires you to give it a name as a string.
This string is the only required parameter.
When traces are sent to Honeycomb, the name of the Tracer
is turned into the library.name
field, which can be used to show all spans created from a particular tracer.
In general, pick a name that matches the appropriate scope for your traces. If you have one tracer for each service, then use the service name. If you have multiple tracers that live in different “layers” of your application, then use the name that corresponds to that “layer”.
The library.name
field is also used with traces created from instrumentation libraries.
Adding context to a currently executing span in a trace can be useful.
For example, you may have an application or service that handles users, and you want to associate the user with the span when querying your dataset in Honeycomb.
To do this, get the current span from the context and set an attribute with the user ID.
This example assumes you are writing a web application with the net/http
package:
import (
// ...
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/trace"
// ...
)
// ...
handler := func(w http.ResponseWriter, r *http.Request) {
user := someServiceCall() // get the currently logged in user
ctx := r.Context()
span := trace.SpanFromContext(ctx)
span.SetAttributes(attribute.Int("user.id", user.getID()))
}
// ...
This will add a user.id
field to the current span, so you can use the field in WHERE
, GROUP BY
, or ORDER
clauses in the Honeycomb query builder.
Automatic instrumentation can show the shape of requests to your system, but only you know the really important parts. To get the full picture of what is happening, you must add custom, or manual, instrumentation and create some custom spans. To do this, grab the tracer from the OpenTelemetry API:
import (
// ...
"go.opentelemetry.io/otel"
// ...
)
// ...
tracer := otel.Tracer("my-app") // if not already in scope
ctx, span := tracer.Start(ctx, "expensive-operation")
defer span.End()
// ...
Sometimes you want to add the same attribute to many spans within the same trace. This attribute may include variables calculated during your program, or other useful values for correlation or debugging purposes.
To add this attribute, leverage the OpenTelemetry concept of baggage.
Baggage allows you to add a key
with a value
as an attribute to every subsequent child span of the current application context, as long as you configured a BaggageSpanProcessor
when you initialized OpenTelemetry.
import (
// ...
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/trace"
"go.opentelemetry.io/otel/baggage"
// ...
)
// ...
handler := func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
// add the user ID attribute to baggage and create new context
bag := baggage.FromContext(ctx)
multiSpanAttribute, _ := baggage.NewMember("key", "value")
bag, _ = bag.SetMember(multiSpanAttribute)
ctx = baggage.ContextWithBaggage(ctx, bag)
tracer := otel.Tracer("my-app") // if not already in scope
// every subsequent span created from this context, and any of its child spans,
// will have the user ID attribute from baggage
ctx, span := tracer.Start(ctx, "expensive-operation")
defer span.End()
}
// ...
The value assigned to your key in baggage.NewMember
must be a URL-decodable string that conforms to the W3C Baggage specification.
Note: Any Baggage attributes that you set in your application will be attached to outgoing network requests as a header. If your service communicates to a third party API, do NOT put sensitive information in the Baggage attributes.
The OpenTelemetry Go API includes a constant named Code
, which represents the status code for a span.
The values of the Code
constant are not the same as the emitted value for a span status.
The values in this enum are used internally in the Go SDK only.
When spans are exported, the values are converted to agree with the OpenTelemetry protobuf specification.
When spans are exported by the Go SDK, the value of Ok
is set to 1
and the value of Error
is set to 2
.
If you query this value in Honeycomb, 1
refers to Ok
and 2
refers to Error
.
This is the opposite of the in-code definition for the Go SDK.
Honeycomb’s OpenTelemetry Distribution for Go includes a sampler that can be configured to use a Honeycomb sample rate.
To configure the sampler, set the SAMPLE_RATE
environment variable:
export SAMPLE_RATE=2
If you have multiple services that communicate with each other, it is important that they have the same sampling configuration. Otherwise, each service might make a different sampling decision, resulting in incomplete or broken traces. You can sample using a standalone proxy as an alternative, like Honeycomb Refinery, or when you have more robust sampling needs.
When a service calls another service, you want to ensure that the relevant trace information is propagated from one service to the other. This allows Honeycomb to connect the two services in a trace.
Distributed tracing enables you to trace and visualize interactions between multiple instrumented services. For example, your users may interact with a front-end API service, which talks to two internal APIs to fulfill their request. In order to have traces connect spans for all these services, it is necessary to propagate trace context between these services, usually by using an HTTP header.
Both the sending and receiving service must use the same propagation format, and both services must be configured to send data to the same Honeycomb environment.
Trace context propagation is done by sending and parsing headers that conform to the W3C Trace Context specification.
By default, the Honeycomb’s OpenTelemetry Distribution for Go uses the W3C trace context format.
If you opt to use a different trace context specification than W3C, ensure that both the sending and receiving service are using the same propagation format, and that both services are configured to send data to the same Honeycomb environment.
Honeycomb’s OpenTelemetry Distribution for Go can create a link to a trace visualization in the Honeycomb UI for local traces. Local visualizations enables a faster feedback cycle when adding, modifying, or verifying instrumentation.
To enable local visualizations:
Set the HONEYCOMB_ENABLE_LOCAL_VISUALIZATIONS
environment variable to true
:
export HONEYCOMB_ENABLE_LOCAL_VISUALIZATIONS=true
Run your application:
go run main.go
The output displays the name of the root span and a link to Honeycomb that shows its trace. For example:
Trace for root-span-name
Honeycomb link: <link to Honeycomb trace>
Select the link to view the trace in detail within the Honeycomb UI.
To use HTTP instead of gRPC, set the OTEL_EXPORTER_OTLP_PROTOCOL
environment variable:
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT
environment variable, you must append the endpoint with the appropriate signal path.
For example, if sending traces, append the endpoint with v1/traces
.
If sending metrics, append the endpoint with v1/metrics
.To explore common issues when sending data, visit Common Issues with Sending Data in Honeycomb.