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  🔗

Import the OTLP exporter in your main module:

import (
  "log" // optional
  "os"
  "go.opentelemetry.io/otel"
  "go.opentelemetry.io/otel/exporters/otlp"
  "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() {
  // Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
  apikey, _ := os.LookupEnv("HONEYCOMB_API_KEY")
  dataset, _ := os.LookupEnv("HONEYCOMB_DATASET")
  exporter, err := otlp.NewExporter(
    ctx,
    otlp.WithTLSCredentials(credentials.NewClientTLSFromCert(nil, "")),
    otlp.WithAddress("api.honeycomb.io:443"),
    otlp.WithHeaders(map[string]string{
      "x-honeycomb-team":    apikey,
      "x-honeycomb-dataset": dataset,
    }),
  )
  if err != nil {
    log.Fatal(err)
  }
  otel.SetTracerProvider(
    trace.NewTracerProvider(
      trace.WithConfig(trace.Config{DefaultSampler: trace.AlwaysSample()}),
      trace.WithSpanProcessor(trace.NewBatchSpanProcessor(exporter)),
    ),
  )
  return exporter.Shutdown
}

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

func main() {
  cleanup := initTracer()
  defer cleanup()
  // your own initialization code...
}

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 Python.

Install  🔗

pip install opentelemetry-exporter-otlp

Initialize  🔗

from grpc import ssl_channel_credentials
from opentelemetry import trace
from opentelemetry.exporter.otlp.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleExportSpanProcessor

exporter = HoneycombSpanExporter(
  service_name='myapp', # replace with your app's name
  # Get this via https://ui.honeycomb.io/account after signing up for Honeycomb
  writekey=OS.environ['HONEYCOMB_API_KEY'],
  dataset=OS.environ['HONEYCOMB_DATASET'],
)
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(
    SimpleExportSpanProcessor(otlp_exporter)
)

And then activate the appropriate virtualenv.

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 .NET.

Install the required packages:

dotnet add package OpenTelemetry --version 1.0.0-rc1.1
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol --version 1.0.0-rc1.1
dotnet add package OpenTelemetry.Instrumentation.AspNetCore --version 1.0.0-rc1.1
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.0.0-rc1.1
dotnet add package OpenTelemetry.Instrumentation.Http --version 1.0.0-rc1.1

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 = this.Configuration.GetValue<string>("Otlp:Endpoint");
        otlpOptions.Credentials = new Grpc.Core.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>0.13.1</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
  <version>0.13.1</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
  <version>0.13.1</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-extension-annotations</artifactId>
  <version>0.13.1</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:0.13.1')
  compile('io.opentelemetry:opentelemetry-sdk:0.13.1')
  compile('io.opentelemetry:opentelemetry-exporter-otlp:0.13.1')
  compile('io.opentelemetry:opentelemetry-extension-annotations:0.13.1')
  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.

System.setProperty("otel.resource.attributes", "service.name=myapp");

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

  // Configure the OpenTelemetry SDK with the exporter
  OpenTelemetrySdk.getGlobalTracerManagement()
    .addSpanProcessor(BatchSpanProcessor.builder(exporter).build());
);

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/core
npm install @opentelemetry/exporter-collector-grpc
npm install @opentelemetry/node
npm install @opentelemetry/tracing
npm install @opentelemetry/plugin-grpc

Configuration  🔗

Setup the trace provider and exporter.

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

const provider = new NodeTracerProvider({ logLevel: LogLevel.ERROR });

const metadata = new grpc.Metadata();
metadata.set("x-honeycomb-team", "");
metadata.set("x-honeycomb-dataset", "");

const collectorOptions = {
  serviceName: 'node-otlp',
  url: 'api.honeycomb.io:443',
  credentials: grpc.credentials.createSsl(),
  metadata
  };

provider.addSpanProcessor(
  new SimpleSpanProcessor(
    new CollectorTraceExporter(collectorOptions)
  )
);

provider.register();

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-sdk
gem install opentelemetry-exporter-otlp

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

Configuration  🔗

require 'sinatra/base'
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'


# configure SDK with OTLP exporter
OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      exporter: OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'http://localhost:55681', # send to local collector
      )
    )
  )
end

class OpenTelemetryMiddleware
  def initialize(app)
    @app = app
    @tracer = OpenTelemetry.tracer_provider.tracer('sinatra', '1.0')
  end

  def call(env)
    # Extract context from request headers
    context = OpenTelemetry.propagation.http.extract(env)

    status, headers, response_body = 200, {}, ''

    # Span name SHOULD be set to route:
    span_name = env['PATH_INFO']

    # For attribute naming, see
    # https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md#http-server

    # Span kind MUST be `:server` for a HTTP server span
    @tracer.in_span(
      span_name,
      attributes: {
        'component' => 'http',
        'http.method' => env['REQUEST_METHOD'],
        'http.route' => env['PATH_INFO'],
        'http.url' => env['REQUEST_URI'],
      },
      kind: :server,
      with_parent: context
    ) do |span|
      # Run application stack
      status, headers, response_body = @app.call(env)

      span.set_attribute('http.status_code', status)
    end

    [status, headers, response_body]
  end
end

class App < Sinatra::Base
  set :bind, '0.0.0.0'
  use OpenTelemetryMiddleware

  get '/' do
    'Hello world!'
  end

  run! if app_file == $0
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.

Set up the Honeycomb Collector-Exporter  🔗

Once you’ve added the API and SDK packages, you’ll need to set up the language-agnostic Honeycomb Collector-Exporter.

Docker image  🔗

Get the latest version of the otel/opentelemetry-collector-contrib Docker image:

docker pull otel/opentelemetry-collector-contrib

Create a configuration file called otel-local-config.yaml according to the instructions below. Then run the following Docker command:

docker run --rm -p 13133:13133 -p 14250:14250 -p 14268:14268 \
      -p 55678-55680:55678-55680 -p 6060:6060 -p 7276:7276 -p 8888:8888 \
      -p 9411:9411 -p 9943:9943 \
      -v "${PWD}/otel-local-config.yaml":/otel-local-config.yaml \
      --name otelcol otel/opentelemetry-collector-contrib \
      --config otel-local-config.yaml

RPM, Debian, and other Packages  🔗

Visit GitHub to get the latest release of the OpenTelemetry Collector Contrib package.

Configure the Honeycomb Collector-Exporter  🔗

Add the following configuration to your otel-local-config.yaml file:

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  honeycomb:
    api_key: <HONEYCOMB_API_KEY>
    dataset: <HONEYCOMB_DATASET>
  otlp:
    endpoint: otelcol:55680

extensions:
  health_check:
  pprof:
  zpages:

service:
  extensions: [health_check,pprof,zpages]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp, honeycomb]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

Now you can start the collector.

From here you can build and run your application. Hit an HTTP endpoint and you’ll see data arrive in Honeycomb in seconds!

Go to the Honeycomb UI

Resources  🔗