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

Instrumenting with OpenTelemetry

Quickstart Instructions  🔗

Follow these instructions to set up the OpenTelemetry OTLP Exporter for Go and automatically create traces/spans on HTTP requests in your Go application.

1. Choose the mux that’s right for your framework  🔗

Add a line to your import() stanza depending upon your request router:

  • If you are using gin/gonic:

    middleware "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin"
    
  • If you are using gorillamux:

    middleware "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux"
    
  • If you are using echo:

    middleware "go.opentelemetry.io/contrib/instrumentation/github.com/labstack/echo"
    

2. Inject OpenTelemetry middleware  🔗

In your main() function, right after you create your primary router, inject the OpenTelemetry middleware:

router.Use(middleware.Middleware("service-name"))

At this point you can build and run your app and hit an HTTP endpoint to ensure that traces are being generated. You should see trace data in your terminal output.

3. Configure exporter to send to Honeycomb  🔗

OpenTelemetry for Go is still under active development. The following example was written using v0.19.0, but subsequent minor version releases may not be backwards compatible.

Import the OTLP exporter in your main module:

import (
  "context"
  "log"
  "os"

  "go.opentelemetry.io/otel"
  "go.opentelemetry.io/otel/exporters/otlp"
  "go.opentelemetry.io/otel/exporters/otlp/otlpgrpc"
  "go.opentelemetry.io/otel/sdk/trace"
  "google.golang.org/grpc/credentials"
)

Configure the exporter to send to Honeycomb and initialize the OpenTelemetry tracer. This example handles both in a separate initTracer() function:

func initTracer() func() {
  // Fetch the necessary settings (from environment variables, in this example).
  // You can find the API key via https://ui.honeycomb.io/account after signing up for Honeycomb.
  apikey, _ := os.LookupEnv("HONEYCOMB_API_KEY")
  dataset, _ := os.LookupEnv("HONEYCOMB_DATASET")

  // Initialize an OTLP exporter over gRPC and point it to Honeycomb.
  ctx := context.Background()
  exporter, err := otlp.NewExporter(
    ctx,
    otlpgrpc.NewDriver(
      otlpgrpc.WithTLSCredentials(credentials.NewClientTLSFromCert(nil, "")),
      otlpgrpc.WithEndpoint("api.honeycomb.io:443"),
      otlpgrpc.WithHeaders(map[string]string{
        "x-honeycomb-team":    apikey,
        "x-honeycomb-dataset": dataset,
      }),
    ),
  )
  if err != nil {
    log.Fatal(err)
  }

  // Configure the OTel tracer provider.
  provider := trace.NewTracerProvider(
    trace.WithSampler(trace.AlwaysSample()),
    trace.WithBatcher(exporter),
  )
  otel.SetTracerProvider(provider)

  // This callback will ensure all spans get flushed before the program exits.
  return func() {
    ctx := context.Background()
    err := provider.Shutdown(ctx)
    if err != nil {
      log.Fatal(err)
    }
  }
}

Then place the initialization code first in your main() function:

func main() {
  cleanup := initTracer()
  defer cleanup()
  // the rest of your initialization...
}

A complete example that demonstrates how to send trace data to Honeycomb using the OTLP Exporter can be viewed here.

Migrating from Honeycomb Exporter to OTLP exporter  🔗

Honeycomb now supports ingesting trace data in the OpenTelemetry OTLP format. If you previously configured the OpenTelemetry SDK to export span data to Honeycomb using the Honeycomb OpenTelemetry Exporter for Go, you can migrate to the official OpenTelemetry OTLP exporter. Below is an example of the Honeycomb span exporter configuration and what to change in order to use the OTLP exporter.

Within your existing Honeycomb span exporter configuration, find these two sections:

// create exporter
exporter, _ := honeycomb.NewExporter(
  honeycomb.Config{
    APIKey: "<YOUR-API-KEY>",
  },
  honeycomb.TargetingDataset("<YOUR-DATASET>"),
  honeycomb.WithServiceName("example-server"),
)

// register exporter with OTel SDK
otel.SetTracerProvider(
  trace.NewTracerProvider(
    trace.WithSampler(trace.AlwaysSample()),
    trace.WithBatcher(exporter),
  )
)

Replace your existing configuration with the OTLP span exporter configuration below:

// create exporter
exporter, _ := otlp.NewExporter(
  ctx,
  otlpgrpc.NewDriver(
    otlpgrpc.WithTLSCredentials(credentials.NewClientTLSFromCert(nil, "")),
    otlpgrpc.WithEndpoint("api.honeycomb.io:443"),
    otlpgrpc.WithHeaders(map[string]string{
      "x-honeycomb-team":    "<YOUR-API-KEY>",
      "x-honeycomb-dataset": "<YOUR-DATASET>",
    }),
  ),
)

// register exporter with OTel SDK
otel.SetTracerProvider(
  trace.NewTracerProvider(
    trace.WithSampler(trace.AlwaysSample()),
    trace.WithBatcher(exporter),
    trace.WithResource(resource.NewWithAttributes(
      semconv.ServiceNameKey.String("example-server"),
    )),
  )
)

Follow these instructions to set up v1.0.0 of the OpenTelemetry OTLP Exporter for Python.

Install  🔗

pip install opentelemetry-exporter-otlp==1.0.0

Initialize  🔗

import os # for environment variables

from grpc import ssl_channel_credentials
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

otlp_exporter = OTLPSpanExporter(
    endpoint="api.honeycomb.io:443",
    credentials=ssl_channel_credentials(),
    headers=(
        ("x-honeycomb-team", os.environ['HONEYCOMB_API_KEY']),
        ("x-honeycomb-dataset", os.environ['HONEYCOMB_DATASET'])
    )
)
trace.set_tracer_provider(TracerProvider(
    resource=Resource({"service.name": "myapp"})))
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)

Then, run your code.

Visit Honeycomb’s examples repo on GitHub to see a complete example that demonstrates how to send trace data to Honeycomb using the OTLP Exporter.

Check out this tutorial that walks through instrumenting a Flask application with OpenTelemetry.

Follow these instructions to set up the OpenTelemetry OTLP Exporter for .NET.

Install the required packages:

dotnet add package OpenTelemetry --version 1.0.1
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol --version 1.0.0-rc2
dotnet add package OpenTelemetry.Instrumentation.AspNetCore --version 1.0.0-rc2
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.0.0-rc2
dotnet add package OpenTelemetry.Instrumentation.Http --version 1.0.0-rc2

Add the following to your Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddOpenTelemetryTracing((builder) => builder
      .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(this.Configuration.GetValue<string>("Otlp:ServiceName")))
      .AddAspNetCoreInstrumentation()
      .AddHttpClientInstrumentation()
      .AddOtlpExporter(otlpOptions =>
      {
        otlpOptions.Endpoint = new Uri(this.Configuration.GetValue<string>("Otlp:Endpoint"));
        otlpOptions.GrpcChannelOptions = new GrpcChannelOptions {
          Credentials = new SslCredentials()
        };

        var headers = new Grpc.Core.Metadata();
        headers.Add("x-honeycomb-team", this.Configuration.GetValue<string>("Otlp:ApiKey"));
        headers.Add("x-honeycomb-dataset", this.Configuration.GetValue<string>("Otlp:Dataset"));
        otlpOptions.Headers = headers;
      }));
    ...
}

Add the following to your appsettings.json:

{
  ...
  "Otlp": {
    "ServiceName": "dotnet-otlp",
    "Endpoint": "api.honeycomb.io",
    "ApiKey": "<your-apikey>",
    "Dataset": "<your-dataset>"
  }
  ...
}

A complete example that demonstrates how to send trace data to Honeycomb using the OTLP Exporter can be viewed here.

Follow these instructions to set up the OpenTelemetry OTLP Exporter for Java.

Installation  🔗

Maven

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-extension-annotations</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-netty-shaded</artifactId>
  <version>1.34.1</version>
</dependency>

Gradle

dependencies {
  compile('io.opentelemetry:opentelemetry-api:1.0.0')
  compile('io.opentelemetry:opentelemetry-sdk:1.0.0')
  compile('io.opentelemetry:opentelemetry-exporter-otlp:1.0.0')
  compile('io.opentelemetry:opentelemetry-extension-annotations:1.0.0')
  compile("io.grpc:grpc-netty-shaded:1.34.1")
}

Configuration  🔗

You will need to name your service and provide your Honeycomb API Key. You can optionally set a dataset which is strongly recommended.

// Create OTLP exporter that sends trace data to Honeycomb
OtlpGrpcSpanExporter exporter = OtlpGrpcSpanExporter.builder()
  .setEndpoint("https://api.honeycomb.io:443")
  .addHeader("x-honeycomb-team", "<your-apikey>")
  .addHeader("x-honeycomb-dataset", "<your-dataset>")
  .build();

// Configure the OpenTelemetry SDK with the exporter
OpenTelemetrySdk.builder()
  .setTracerProvider(
    SdkTracerProvider.builder()
      .setResource(Resource.create(Attributes.of(AttributeKey.stringKey("service.name"), "java-otlp")))
      .addSpanProcessor(BatchSpanProcessor.builder(exporter).build())
      .build())
  .buildAndRegisterGlobal();

A complete example that demonstrates how to send trace data to Honeycomb using the OTLP Exporter can be viewed here.

Follow these instructions to set up the OpenTelemetry OTLP Exporter for JavaScript.

Installation  🔗

Install these packages:

npm install @opentelemetry/api
npm install @opentelemetry/node
npm install @opentelemetry/tracing
npm install @opentelemetry/exporter-collector-grpc
npm install @opentelemetry/instrumentation
npm install @opentelemetry/plugin-express
npm install @opentelemetry/plugin-grpc

Configuration  🔗

Setup the trace provider and exporter.

const grpc = require('grpc');
const { NodeTracerProvider } = require("@opentelemetry/node");
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { SimpleSpanProcessor } = require("@opentelemetry/tracing");
const { CollectorTraceExporter } = require("@opentelemetry/exporter-collector-grpc");

const metadata = new grpc.Metadata();
metadata.set('x-honeycomb-team', '<YOUR-APIKEY>');
metadata.set('x-honeycomb-dataset', '<YOUR-DATASET>');

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new SimpleSpanProcessor(
    new CollectorTraceExporter({
      serviceName: 'node-otlp',
      url: 'api.honeycomb.io:443',
      credentials: grpc.credentials.createSsl(),
      metadata
    })
  )
);
provider.register();

registerInstrumentations({
  tracerProvider: provider,
});

A complete example that demonstrates how to send trace data to Honeycomb using the OTLP Exporter can be viewed here.

Note: Currently, the OpenTelemetry OTLP Exporter for Ruby supports sending OTLP data only as JSON over HTTP. Honeycomb’s OpenTelemetry ingestion API supports OTLP only over gRPC. To send OpenTelemetry data to Honeycomb, you must run an OpenTelemetry Collector to receive the OTLP/http data and then export OTLP/grpc to Honeycomb.

Follow the instructions below to set up the OpenTelemetry OTLP Exporter for Ruby.

Installation  🔗

Install the OpenTelemetry gems using:

gem install opentelemetry-api
gem install opentelemetry-sdk
gem install opentelemetry-exporter-otlp

Or, if you use bundler, include opentelemetry-api. opentelemetry-sdk and opentelemetry-exporter-otlp in your Gemfile.

Configuration  🔗

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'rubygems'
require 'bundler/setup'

Bundler.require

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'ruby-otlp'
  c.use 'OpenTelemetry::Instrumentation::Sinatra'
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'http://localhost:55681/v1/traces'
      )
    )
  )
end

get '/' do
  'Hello world!'
end

A complete example can be viewed here, including how to run a local OpenTelemetry Collector that receives trace data in JSON format and forwards onto Honeycomb in gRPC format.

Choose the API and SDK for your language, or search the OpenTelemetry Registry for instrumentation .

Follow the instructions to install the required packages. Configure OpenTelemetry in your service as documented in the language’s OpenTelemetry SDK for an otlp GRPC exporter.

  • Set the OTLP/GRPC endpoint to: api.honeycomb.io:443
  • Add two headers to the exporter configuration:
    • x-honeycomb-team, set the value to your Honeycomb write key
    • x-honeycomb-dataset, set to the name of the target dataset

Or gather data from multiple services and control data egress, by exporting to an OpenTelemetry Collector on your network configured to forward on to Honeycomb.

Resources  🔗