Automatically Trace HTTP Requests

This guide walks you through setting up automatic HTTP tracing for your Python application 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.

Language

Examples use Python. Beakpoint works with any language that OpenTelemetry supports.

Prerequisites

Before you begin, ensure you have:

• A Beakpoint account
• A Beakpoint API key
• A Python application you want to monitor

Install Dependencies

Install the OpenTelemetry SDK, the OTLP exporter, and the auto-instrumentation packages for the frameworks your application uses:

pip install opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-otlp-proto-http \
  opentelemetry-instrumentation-requests \
  opentelemetry-instrumentation-flask \
  opentelemetry-instrumentation-django

You only need to install the instrumentation packages your application actually uses. For example, if you use Flask and requests but not Django, you can skip opentelemetry-instrumentation-django.

Zero-Code Setup

The fastest way to get started is OpenTelemetry's automatic instrumentation, which requires no code changes.

1. Install the auto-instrumentation package

   pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
   opentelemetry-bootstrap -a install

   The opentelemetry-bootstrap command detects your installed libraries and installs the matching instrumentation packages automatically.

2. Set environment variables

   export OTEL_SERVICE_NAME="your-service-name"
   export OTEL_TRACES_EXPORTER="otlp"
   export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.beakpoint.io/api/traces"
   export OTEL_EXPORTER_OTLP_HEADERS="x-bkpt-key=YOUR_API_KEY_HERE"
   export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

3. Run your application with instrumentation

   opentelemetry-instrument python your_app.py

   For frameworks with their own runners:

   # Flask
   opentelemetry-instrument flask run
   
   # Django
   opentelemetry-instrument python manage.py runserver
   
   # Gunicorn
   opentelemetry-instrument gunicorn myapp:app

Programmatic Setup

For more control over which libraries are instrumented, configure the tracer provider in code:

1. Create a tracer initialization module (e.g., tracer_setup.py):

   from opentelemetry import trace
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   from opentelemetry.instrumentation.flask import FlaskInstrumentor
   from opentelemetry.instrumentation.requests import RequestsInstrumentor
   from opentelemetry.sdk.resources import Resource
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   
   resource = Resource.create({"service.name": "your-service-name"})
   provider = TracerProvider(resource=resource)
   
   exporter = OTLPSpanExporter(
       endpoint="https://otel.beakpoint.io/api/traces",
       headers={"x-bkpt-key": "YOUR_API_KEY_HERE"},
   )
   provider.add_span_processor(BatchSpanProcessor(exporter))
   trace.set_tracer_provider(provider)
   
   # Instrument the libraries you use
   FlaskInstrumentor().instrument()
   RequestsInstrumentor().instrument()

2. Import the setup module at the top of your application before any Flask or requests usage:

   # app.py
   import tracer_setup  # Must be first
   from flask import Flask
   
   app = Flask(__name__)
   # ... rest of your application

For selective instrumentation, install and enable only the packages you need. Common options include:

Library	Package
requests	opentelemetry-instrumentation-requests
urllib3	opentelemetry-instrumentation-urllib3
httpx	opentelemetry-instrumentation-httpx
aiohttp	opentelemetry-instrumentation-aiohttp-client
Flask	opentelemetry-instrumentation-flask
Django	opentelemetry-instrumentation-django
FastAPI	opentelemetry-instrumentation-fastapi

Verification Steps

After setting up instrumentation, verify that traces are being sent correctly:

1. Generate test traffic

   • Make several HTTP requests to your application
   • Perform different operations that trigger various endpoints
   • Allow 5-10 seconds for batched spans to be exported to Beakpoint

2. Check application logs

   • Look for any OpenTelemetry initialization messages
   • Verify that span processing has begun (no error messages indicate success)

3. Verify in Beakpoint

   • Log into your Beakpoint dashboard
   • Navigate to the Traces section
   • Confirm that your service name appears in the service list
   • You should see HTTP spans with:
     • Request method (GET, POST, etc.)
     • URL path
     • Response status code
     • Request duration in milliseconds

4. Verify span attributes

   • Click on a span to inspect its attributes:
   • http.method: The HTTP request method
   • http.url or http.target: The requested URL
   • http.status_code: The response status code
   • http.host: The host being accessed
   • net.peer.name: The remote server name (for client requests)

5. Troubleshooting

   If traces aren't appearing after 30 seconds:

   • Verify API key: Ensure x-bkpt-key or OTEL_EXPORTER_OTLP_HEADERS is set correctly
   • Check network connectivity: Verify the application can reach otel.beakpoint.io
   • Enable debug logging: Set OTEL_LOG_LEVEL=debug to see detailed exporter logs
   • Verify instrumentation packages: Run opentelemetry-bootstrap -a requirements to list detected packages
   • Check application logs: Look for OpenTelemetry errors or warnings
   • Confirm endpoint: For zero-code setup, verify OTEL_EXPORTER_OTLP_ENDPOINT is set to https://otel.beakpoint.io/api/traces

Once you see traces appearing in Beakpoint with the expected HTTP information, your automatic instrumentation is working correctly!