This Quick Start uses the npm
dependency manager.
For instructions with yarn
, refer to our OpenTelemetry Node.js documentation.
If using TypeScript, refer to our OpenTelemetry Node.js documentation for instructions.
Install Modules
Install the Honeycomb OpenTelemetry Node.js Distribution package:
npm install --save \
@honeycombio/opentelemetry-node \
@opentelemetry/auto-instrumentations-node
auto-instrumentations-node
is a meta package that provides a way to initialize multiple Node.js instrumentations like express
, dns
, http
, and more.
Alternatively, you can install individual instrumentation packages.
Initialize
Create an initialization file, commonly known as the tracing.js
file, and import it as the first step in your application lifecycle.
Alternatively, include this initialization file with the -r
or --require
Node.js CLI option.
// tracing.js
'use strict';
const { HoneycombSDK } = require('@honeycombio/opentelemetry-node');
const {
getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');
// uses HONEYCOMB_API_KEY and OTEL_SERVICE_NAME environment variables
const sdk = new HoneycombSDK({
instrumentations: [getNodeAutoInstrumentations()]
});
sdk.start()
Configure and Run
Configure the Honeycomb Distribution for Node.js using environment variables.
Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored.
The service name is specified by OTEL_SERVICE_NAME
.
export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"
Run the Node.js app with the OpenTelemetry initialization file to generate data:
node -r ./tracing.js APPLICATION_MAIN_FILE.js
This Quick Start uses the pip
package manager.
For instructions with poetry
, refer to the OpenTelemetry Python documentation.
Install Packages
First, install the honeycomb-opentelemetry package.
python -m pip install honeycomb-opentelemetry --pre
Second, install instrumentation libraries for the packages used by your application.
The recommended way is to use the opentelemetry-bootstrap
tool that comes with the OpenTelemetry SDK to scan your application packages to get the list of available libraries.
By default, the tool prints out the instrumentation libraries that are available, but it can also install them directly for you too.
opentelemetry-bootstrap --action=install
Configure and Run
Configure the Honeycomb Distribution for Python using environment variables.
Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored.
The service name is specified by OTEL_SERVICE_NAME
.
export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"
Now you can run your application using the OpenTelemetry Python automatic instrumentation tool opentelemetry-instrument
, which configures the OpenTelemetry SDK, and see traces for your app:
opentelemetry-instrument python myapp.py
Acquire Dependencies
The auto-instrumentation agent for Honeycomb OpenTelemetry Java will automatically generate trace data from your application. The agent is packaged as a JAR file and is run alongside your app.
In order to use the auto-instrumentation agent, you must first download it:
curl -LO https://github.com/honeycombio/honeycomb-opentelemetry-java/releases/download/v1.5.0/honeycomb-opentelemetry-javaagent-1.5.0.jar
Configure
Choose from one of the following configuration options:
Use environment variables:
SERVICE_NAME=my-favorite-service
HONEYCOMB_API_KEY=my-api-key
HONEYCOMB_METRICS_DATASET=my-metrics
Or, use system properties:
sample.rate=2
service.name=my-favorite-service
honeycomb.api.key=my-api-key
honeycomb.metrics.dataset=my-metrics
and set an environment variable with a path to your properties file:
HONEYCOMB_CONFIG_FILE=/path/to/properties/file
Run
Run your app with the auto-instrumentation agent as a sidecar:
java -javaagent:honeycomb-opentelemetry-javaagent-1.5.0.jar -jar /path/to/myapp.jar
You can also include configuration values with an invocation of your app, like so:
java \
-Dhoneycomb.config.file=/path/to/properties/file \
-javaagent:honeycomb-opentelemetry-javaagent-1.5.0.jar -jar /path/to/myapp.jar
Refer to our Java documentation for more configuration options.
This Quick Start uses ASP.NET Core. For other .NET configuration options, refer to the OpenTelemetry .NET documentation on programmatic and ASP.NET (.NET Framework) configuration.
Acquire Dependencies
Install the Honeycomb.OpenTelemetry NuGet package.
For example, with the .NET CLI, use:
dotnet add package Honeycomb.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package Honeycomb.OpenTelemetry.CommonInstrumentations --prerelease
Initialize
Initialize your ASP.NET
Core app to use the Honeycomb OpenTelemetry Distribution for .NET:
In your appsettings.json
file, add a Honeycomb section like so:
{
"Honeycomb": {
"ServiceName": "my-app",
"ApiKey": "{apikey}"
}
}
Then get HoneycombOptions
from configuration and use them to configure the OpenTelemetry SDK in your application startup code:
using OpenTelemetry.Trace;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var honeycombOptions = builder.Configuration.GetHoneycombOptions();
// Setup OpenTelemetry Tracing
builder.Services.AddOpenTelemetry().WithTracing(otelBuilder =>
{
otelBuilder
.AddHoneycomb(honeycombOptions)
.AddCommonInstrumentations();
});
// Register Tracer so it can be injected into other components (for example, Controllers)
builder.Services.AddSingleton(TracerProvider.Default.GetTracer(honeycombOptions.ServiceName));
var app = builder.Build();
app.MapGet("/", (Tracer tracer) =>
{
using var span = tracer.StartActiveSpan("app.manual-span");
span.SetAttribute("app.manual-span.message", "Adding custom spans is also super easy!");
});
await app.RunAsync();
Run
You can now run your app, and you will see the incoming requests and outgoing HTTP calls generate traces.
dotnet run
Refer to our .NET documentation for all configuration options and ways to run your application.
Acquire Dependencies
Install the Honeycomb OpenTelemetry Go Distribution package:
go get github.com/honeycombio/honeycomb-opentelemetry-go \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
Initialize
Configure 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 func to be instrumented
func httpHandler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, World")
}
// Wrap the HTTP handler func 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 honeycomb distro to setup 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))
}
Configure and Run
Configure the Honeycomb Distribution for Go using environment variables.
Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored.
The service name is specified by OTEL_SERVICE_NAME
.
export OTEL_SERVICE_NAME="your-service-name"
export HONEYCOMB_API_KEY="your-api-key"
Now you can run your application and see traces created for each incoming HTTP request:
go run main.go
Acquire Dependencies
Add these gems to your Gemfile:
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'
The inclusion of opentelemetry-instrumentation-all
above provides instrumentation for Rails, Sinatra, several HTTP libraries, and more.
Initialize
OpenTelemetry initialization must occur early in your application lifecycle. For Rails applications, the usual way to initialize OpenTelemetry is in a Rails initializer. For other Ruby services, perform this initialization as early as possible in the start-up process.
# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
c.use_all() # enables all instrumentation!
end
Configure and Run
Configure OpenTelemetry to send events to Honeycomb using environment variables.
The header x-honeycomb-team
is your API key.
Your service name will be used as the Service Dataset in Honeycomb, which is where data is stored.
The service name is specified by OTEL_SERVICE_NAME
.
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
export OTEL_SERVICE_NAME="your-service-name"
You can now run your Ruby app to automatically generate traces.
If your preferred language is not covered here, use the OpenTelemetry community documentation to find relevant instrumentation details.
For Rust, we recommend to use the opentelemetry and opentelemetry-otlp crates to send data over OTLP to Honeycomb.
Refer to the Using the Honeycomb OpenTelemetry Endpoint for the required configuration values.