http

Documentation

Overview

Package http provides OpenTelemetry instrumentation for HTTP clients and servers.

HTTP Server

Use middleware to instrument HTTP handlers:

// Standard net/http
http.Handle("/api", otxhttp.Middleware("api-server")(myHandler))

// Explicit verification of providers
http.Handle("/api", otxhttp.MiddlewareWithProviders(tp, mp, prop)(myHandler))

HTTP Client

Create an instrumented HTTP client:

client := otxhttp.NewClient(
    otxhttp.WithTimeout(30 * time.Second),
)

// Use the client
resp, err := client.Get("https://example.com")

Index

• func Handler(handler http.Handler, operation string, opts ...otelhttp.Option) http.Handler
• func HandlerWithProviders(handler http.Handler, operation string, tp trace.TracerProvider, ...) http.Handler
• func Middleware(opts ...otelhttp.Option) func(http.Handler) http.Handler
• func MiddlewareWithProviders(tp trace.TracerProvider, mp metric.MeterProvider, ...) func(http.Handler) http.Handler
• func NewClient(opts ...ClientOption) *http.Client
• func NewClientWithProviders(tp trace.TracerProvider, mp metric.MeterProvider, ...) *http.Client
• func Transport(base http.RoundTripper, opts ...otelhttp.Option) http.RoundTripper
• func TransportWithProviders(base http.RoundTripper, tp trace.TracerProvider, mp metric.MeterProvider, ...) http.RoundTripper
• type ClientOption
  • func WithDialTimeout(d time.Duration) ClientOption
  • func WithExpectContinueTimeout(d time.Duration) ClientOption
  • func WithIdleConnTimeout(d time.Duration) ClientOption
  • func WithMaxConnsPerHost(n int) ClientOption
  • func WithMaxIdleConns(n int) ClientOption
  • func WithMaxIdleConnsPerHost(n int) ClientOption
  • func WithResponseHeaderTimeout(d time.Duration) ClientOption
  • func WithTLSHandshakeTimeout(d time.Duration) ClientOption
  • func WithTimeout(d time.Duration) ClientOption
  • func WithTransport(rt http.RoundTripper) ClientOption

Functions

func Handler

func Handler(handler http.Handler, operation string, opts ...otelhttp.Option) http.Handler

Handler wraps an http.Handler with OTel tracing and metrics.

This handler uses the globally registered TracerProvider, MeterProvider, and TextMapPropagator. When using this with the otx package, ensure that global providers have been initialized.

For explicit provider injection, use HandlerWithProviders instead.

Usage:

http.Handle("/api", http.Handler(myHandler, "api.request"))

func HandlerWithProviders

func HandlerWithProviders(
	handler http.Handler,
	operation string,
	tp trace.TracerProvider,
	mp metric.MeterProvider,
	prop propagation.TextMapPropagator,
	opts ...otelhttp.Option,
) http.Handler

HandlerWithProviders wraps an http.Handler with OTel tracing and metrics using explicitly provided TracerProvider, MeterProvider, and TextMapPropagator.

This is useful when:

• You need to use a different provider than the global one
• You want explicit dependency injection for testing
• You have multiple HTTP handlers with different telemetry configurations

If any provider is nil, the corresponding global provider will be used as fallback.

Usage:

http.Handle("/api", http.HandlerWithProviders(
    myHandler,
    "api.request",
    tracerProvider,
    meterProvider,
    propagator,
))

func Middleware

func Middleware(opts ...otelhttp.Option) func(http.Handler) http.Handler

Middleware returns middleware that traces HTTP requests.

This middleware uses the globally registered TracerProvider, MeterProvider, and TextMapPropagator. When using this with the otx package, ensure that global providers have been initialized.

For explicit provider injection, use MiddlewareWithProviders instead.

Usage:

http.Handle("/api", http.Middleware()(myHandler))

func MiddlewareWithProviders

func MiddlewareWithProviders(
	tp trace.TracerProvider,
	mp metric.MeterProvider,
	prop propagation.TextMapPropagator,
	opts ...otelhttp.Option,
) func(http.Handler) http.Handler

MiddlewareWithProviders returns middleware that traces HTTP requests using explicitly provided TracerProvider, MeterProvider, and TextMapPropagator.

This is useful when:

• You need to use a different provider than the global one
• You want explicit dependency injection for testing
• You have multiple HTTP servers with different telemetry configurations

If any provider is nil, the corresponding global provider will be used as fallback.

Usage:

http.Handle("/api", http.MiddlewareWithProviders(
    tracerProvider,
    meterProvider,
    propagator,
)(myHandler))

func NewClient

func NewClient(opts ...ClientOption) *http.Client

NewClient creates an http.Client with OTel tracing enabled.

This client uses the globally registered TracerProvider, MeterProvider, and TextMapPropagator. Ensure global providers have been initialized.

If no transport options are provided, it defaults to using http.DefaultTransport settings adjusted with any provided timeout options.

Usage:

client := otxhttp.NewClient(
    otxhttp.WithTimeout(30 * time.Second),
    otxhttp.WithMaxIdleConnsPerHost(10),
)

func NewClientWithProviders

func NewClientWithProviders(
	tp trace.TracerProvider,
	mp metric.MeterProvider,
	prop propagation.TextMapPropagator,
	opts ...ClientOption,
) *http.Client

NewClientWithProviders creates an http.Client with OTel tracing enabled using explicitly provided TracerProvider, MeterProvider, and TextMapPropagator.

If any provider is nil, the corresponding global provider will be used as fallback.

Usage:

client := otxhttp.NewClientWithProviders(
    tracerProvider,
    meterProvider,
    propagator,
    otxhttp.WithTimeout(10 * time.Second),
)

func Transport

func Transport(base http.RoundTripper, opts ...otelhttp.Option) http.RoundTripper

Transport wraps an http.RoundTripper with OTel tracing for client calls.

This transport uses the globally registered TracerProvider, MeterProvider, and TextMapPropagator. When using this with the otx package, ensure that global providers have been initialized.

For explicit provider injection, use TransportWithProviders instead.

If base is nil, http.DefaultTransport is used.

Usage:

client := &http.Client{
    Transport: otxhttp.Transport(http.DefaultTransport),
}

func TransportWithProviders

func TransportWithProviders(
	base http.RoundTripper,
	tp trace.TracerProvider,
	mp metric.MeterProvider,
	prop propagation.TextMapPropagator,
	opts ...otelhttp.Option,
) http.RoundTripper

TransportWithProviders wraps an http.RoundTripper with OTel tracing using explicitly provided TracerProvider, MeterProvider, and TextMapPropagator.

This is useful when:

• You need to use a different provider than the global one
• You want explicit dependency injection for testing
• You have multiple HTTP clients with different telemetry configurations

If any provider is nil, the corresponding global provider will be used as fallback. If base is nil, http.DefaultTransport is used.

Usage:

client := &http.Client{
    Transport: otxhttp.TransportWithProviders(
        http.DefaultTransport,
        tracerProvider,
        meterProvider,
        propagator,
    ),
}

Types

type ClientOption

type ClientOption func(*clientConfig)

ClientOption configures an HTTP client.

func WithDialTimeout

func WithDialTimeout(d time.Duration) ClientOption

WithDialTimeout sets the timeout for dialing TCP connections.

func WithExpectContinueTimeout

func WithExpectContinueTimeout(d time.Duration) ClientOption

WithExpectContinueTimeout sets the max time to wait for a 100-continue response.

func WithIdleConnTimeout

func WithIdleConnTimeout(d time.Duration) ClientOption

WithIdleConnTimeout sets the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.

func WithMaxConnsPerHost

func WithMaxConnsPerHost(n int) ClientOption

WithMaxConnsPerHost sets the max total connections per host.

func WithMaxIdleConns

func WithMaxIdleConns(n int) ClientOption

WithMaxIdleConns sets the max idle connections across all hosts.

func WithMaxIdleConnsPerHost

func WithMaxIdleConnsPerHost(n int) ClientOption

WithMaxIdleConnsPerHost sets the max idle connections to keep per-host.

func WithResponseHeaderTimeout

func WithResponseHeaderTimeout(d time.Duration) ClientOption

WithResponseHeaderTimeout sets the time to wait for response headers after writing the request.

func WithTLSHandshakeTimeout

func WithTLSHandshakeTimeout(d time.Duration) ClientOption

WithTLSHandshakeTimeout sets the timeout for TLS handshakes.

func WithTimeout

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the request timeout for the client.

func WithTransport

func WithTransport(rt http.RoundTripper) ClientOption

WithTransport sets a custom base transport options. Note: Transport timeouts/settings configured here will override other options if set on this transport.