Automatically Trace HTTP Requests
This guide walks you through setting up automatic HTTP tracing for your applications using OpenTelemetry. By following these steps, you'll be able to capture and analyze HTTP requests across your distributed systems without modifying your application code.
Prerequisites
Before you begin, ensure you have:
- A Beakpoint Insights account
- A Beakpoint Insights API key
- An application you want to monitor. (This quick start is focused on.NET, Ruby, TypeScript/Node.js, but Beakpoint Insights supports any language or framework that OpenTelemetry supports.)
.NET Implementation
The OpenTelemetry .NET Automatic Instrumentation provides zero-code instrumentation for .NET applications, automatically capturing HTTP requests and other telemetry data.
Automatic Instrumentation
For the fastest setup with no code changes required:
- Download and install the automatic instrumentation
- Windows (PowerShell)
- Linux/Mac
# Download and import the module
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path
# Install core files
Install-OpenTelemetryCore
# Download the installation script
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O
# Install core files
sh ./otel-dotnet-auto-install.sh
# Enable execution for the instrumentation script
chmod +x $HOME/.otel-dotnet-auto/instrument.sh
- Configure environment variables
Set these environment variables before running your application:
- Windows (PowerShell)
- Linux/Mac
$env:OTEL_SERVICE_NAME = "your-service-name"
$env:OTEL_TRACES_EXPORTER = "otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://otel.beakpointinsights.com"
$env:OTEL_EXPORTER_OTLP_HEADERS = "x-bkpt-key=YOUR_API_KEY_HERE"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
export OTEL_SERVICE_NAME="your-service-name"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.beakpointinsights.com"
export OTEL_EXPORTER_OTLP_HEADERS="x-bkpt-key=YOUR_API_KEY_HERE"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
- Run your application with instrumentation
- Windows (PowerShell)
- Linux/Mac
Register-OpenTelemetryForCurrentSession -OTelServiceName "your-service-name"
dotnet run
$HOME/.otel-dotnet-auto/instrument.sh dotnet run
Package-based setup
For more control or when using self-contained applications, you can use the NuGet packages approach:
-
Add the NuGet package to your project
dotnet add package OpenTelemetry.AutoInstrumentation
-
Configure instrumentation in your application
using OpenTelemetry;
using OpenTelemetry.Trace;
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("YourApplicationName")
.AddAspNetCoreInstrumentation(options => {
options.RecordException = true;
})
.AddHttpClientInstrumentation()
.AddOtlpExporter(options => {
options.Endpoint = new Uri("https://otel.beakpointinsights.com/api/traces");
options.Headers = "x-bkpt-key=YOUR_API_KEY_HERE";
options.Protocol = OtlpExportProtocol.HttpProtobuf;
})
.Build();
Ruby Implementation
OpenTelemetry Ruby provides automatic instrumentation for popular web frameworks and HTTP libraries.
Gem Installation
-
Add OpenTelemetry gems to your Gemfile
# Core OpenTelemetry gems
gem 'opentelemetry-api'
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
# Auto-instrumentation for all supported libraries
gem 'opentelemetry-instrumentation-all' -
Install the gems
bundle install
Zero-Code Setup
Configure OpenTelemetry in your application's initialization code:
-
For Rails applications, create
config/initializers/opentelemetry.rb
:require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
c.service_name = 'your-service-name'
c.use_all() # enables all instrumentation
end -
Set environment variables to configure the exporter:
- Windows (PowerShell)
- Linux/Mac
$env:OTEL_TRACES_EXPORTER = "otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://otel.beakpointinsights.com"
$env:OTEL_EXPORTER_OTLP_HEADERS = "x-bkpt-key=YOUR_API_KEY_HERE"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.beakpointinsights.com
export OTEL_EXPORTER_OTLP_HEADERS="x-bkpt-key=YOUR_API_KEY_HERE"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf -
For Sinatra or other frameworks:
require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
c.service_name = 'your-service-name'
c.use_all()
end
# Your application code follows...
For selective instrumentation, you can enable specific libraries instead of using use_all()
:
c.use 'OpenTelemetry::Instrumentation::Sinatra'
c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
TypeScript/Node.js Implementation
OpenTelemetry JavaScript provides comprehensive auto-instrumentation for Node.js applications.
Auto-Instrumentation Package
-
Install the required packages
npm install --save @opentelemetry/api \
@opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http -
Create an instrumentation file (
instrumentation.ts
orinstrumentation.js
):import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const traceExporter = new OTLPTraceExporter({
url: 'https://otel.beakpointinsights.com/api/traces',
headers: {
'x-bkpt-key': 'YOUR_API_KEY_HERE'
}
});
const sdk = new NodeSDK({
serviceName: 'your-service-name',
traceExporter,
instrumentations: [getNodeAutoInstrumentations()]
});
sdk.start(); -
Run your application with instrumentation
node --require ./instrumentation.js your-app.js
Or for TypeScript:
node --require ts-node/register --require ./instrumentation.ts your-app.ts
Manual Setup
For more control over specific instrumentations:
-
Install specific instrumentation packages
npm install --save @opentelemetry/instrumentation-http \
@opentelemetry/instrumentation-express -
Configure specific instrumentations:
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
const sdk = new NodeSDK({
serviceName: 'your-service-name',
traceExporter,
instrumentations: [
new HttpInstrumentation(),
new ExpressInstrumentation()
]
});
Verification Steps
After setting up instrumentation, verify that traces are being sent correctly:
-
Generate test traffic
- Make several HTTP requests to your application
- Perform different operations that trigger various endpoints
-
Check for console output (if configured)
- Look for span information being printed to your application logs
- Verify that HTTP requests show appropriate attributes
-
Verify in Beakpoint Insights
- Log into your Beakpoint Insights dashboard
- Navigate to the traces section
- Confirm that your service name appears
- Check that HTTP spans include:
- Request method (GET, POST, etc.)
- URL path
- Response status code
- Request duration
-
Common attributes to verify:
http.method
: The HTTP request methodhttp.url
orhttp.target
: The requested URLhttp.status_code
: The response status codehttp.host
: The host being accessednet.peer.name
: The remote server name (for client requests)
-
Troubleshooting tips:
- Ensure your API key is correctly set
- Verify network connectivity to
otel.beakpointinsights.com
- Check application logs for any OpenTelemetry errors
- For .NET, enable debug logging with
OTEL_LOG_LEVEL=debug
- For Node.js, check for missing peer dependencies
- For Ruby, ensure all gems are properly loaded
Once you see traces appearing in Beakpoint Insights with the expected HTTP information, your automatic instrumentation is working correctly!