OpenTelemetry HTTP Utilities

Common errors

• ImportError: cannot import name '_ExtendedAttributes' from 'opentelemetry.util.types'

  cause This error typically occurs due to version incompatibility between different OpenTelemetry packages, where a newer version of the OpenTelemetry SDK or API has removed or renamed the '_ExtendedAttributes' symbol from 'opentelemetry.util.types', while dependent packages like `opentelemetry-util-http` (or other instrumentations) still expect it.
  fix Ensure all installed OpenTelemetry-related packages are compatible by either upgrading all of them to their latest versions or pinning them to a known compatible set, often by using `pip install opentelemetry-sdk==X.Y.Z opentelemetry-api==X.Y.Z opentelemetry-util-http==A.B.C` where versions are aligned. Check release notes for breaking changes and dependency requirements.

• ModuleNotFoundError: No module named 'opentelemetry.util._once'

  cause This error indicates that the `_once` module, which was an internal utility, is no longer available or has been refactored in newer versions of the OpenTelemetry Python SDK, leading to import failures if older code or instrumentation tries to access it.
  fix Upgrade all OpenTelemetry packages, including `opentelemetry-util-http` and any instrumentations, to their latest compatible versions. If using auto-instrumentation, ensure the `opentelemetry-distro` and other core packages are up-to-date.

• ModuleNotFoundError: No module named 'opentelemetry'

  cause This fundamental error means that the base `opentelemetry` package, which is required by `opentelemetry-util-http` and all other OpenTelemetry components, is not installed or not accessible in the current Python environment.
  fix Install the core OpenTelemetry packages using `pip install opentelemetry-api opentelemetry-sdk` (and `opentelemetry-util-http` if it's a direct dependency), and ensure your application is running in the correct Python environment where these packages are installed.

• ImportError: cannot import name 'OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE' from 'opentelemetry.sdk.environment_variables'

  cause This `ImportError` often arises from version mismatches between the `opentelemetry-sdk` and exporter packages, particularly `opentelemetry-exporter-otlp-proto-http`, where a specific environment variable or symbol expected by the exporter is missing or has changed in the installed SDK version.
  fix Ensure that `opentelemetry-sdk` and `opentelemetry-exporter-otlp-proto-http` (and other related `opentelemetry-*` packages including `opentelemetry-util-http`) are installed in compatible versions. Upgrading all OpenTelemetry packages to their latest versions, or explicitly pinning them to a known working set, usually resolves this.

Warnings

• breaking The 'http.target' attribute has been split into 'url.path' and 'url.query' as part of the stabilization of HTTP Semantic Conventions. Ensure your instrumentation and observability tools are updated accordingly.
  Fix: Update your instrumentation and observability tools to handle the new attribute names 'url.path' and 'url.query'.
• deprecated The 'http.client_ip' attribute has been replaced with 'client.address' in the latest semantic conventions. Update your code to use 'client.address' for client IP information.
  Fix: Replace instances of 'http.client_ip' with 'client.address' in your codebase.
• breaking The OpenTelemetry instrumentation module could not be found. This typically means the necessary OpenTelemetry packages (e.g., opentelemetry-api, opentelemetry-sdk, and specific instrumentation packages like opentelemetry-instrumentation-httpx) are not installed in the environment.
  Fix: Install the required OpenTelemetry packages using pip: `pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-httpx`.
• gotcha The 'opentelemetry.instrumentation' module was not found. This typically indicates that required OpenTelemetry packages, such as 'opentelemetry-sdk' or specific instrumentation packages like 'opentelemetry-instrumentation-httpx', are not installed in the environment.
  Fix: Ensure that the necessary OpenTelemetry packages are installed. For example, run 'pip install opentelemetry-sdk opentelemetry-instrumentation-httpx'.

Install

• pip install opentelemetry-util-http Install opentelemetry-util-http

Imports

• HttpInstrumentation

  from opentelemetry.instrumentation.httpx import HttpInstrumentation

  Ensure correct import path to avoid ImportError.

Quickstart

A basic example of using OpenTelemetry's HTTPX instrumentation to monitor HTTP requests.

import os
from opentelemetry.instrumentation.httpx import HttpInstrumentation

# Initialize the HTTPX instrumentation
httpx_instrumentor = HttpInstrumentation()
httpx_instrumentor.enable()

# Your application code here
# For example, making an HTTP request using httpx
import httpx

client = httpx.Client()
response = client.get('http://example.com')
print(response.status_code)

# Disable the instrumentation when done
httpx_instrumentor.disable()