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
This is a quick start guide for Python with Flask.
Install these packages to instrument a Flask app with OpenTelemetry:
pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp-proto-http
pip install opentelemetry-instrumentation-flask
pip install opentelemetry-instrumentation-requests
Initialize
Create a new file, tracing.py
.
This file will create and initialize a tracer and Flask instrumentation to send data to Honeycomb:
# tracing.py
from opentelemetry import trace
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
# Initialize tracing and an exporter that can send data to Honeycomb
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)
# Initialize automatic instrumentation with Flask
app = flask.Flask(__name__)
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()
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"
python app.py tracing.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.4.1/honeycomb-opentelemetry-javaagent-1.4.1.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.4.1.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.4.1.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 Honeycomb.OpenTelemetry.AutoInstrumentations --prerelease
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.0.0-rc.9.9
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.AddOpenTelemetryTracing(otelBuilder =>
{
otelBuilder
.AddHoneycomb(honeycombOptions)
.AddAutoInstrumentations()
});
// 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"
// NOTE: this import is super important as applies the Honeycomb
// configuration to the launcher
_ "github.com/honeycombio/honeycomb-opentelemetry-go"
"github.com/honeycombio/opentelemetry-go-contrib/launcher"
"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 := launcher.ConfigureOpenTelemetry(
launcher.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.