otel

Documentation

Overview

Package otel provides Clientkit's OpenTelemetry HTTP propagation and per-RoundTrip transport instrumentation.

New constructs only a HeaderPropagator. NewTransport wraps an http.RoundTripper and creates one CLIENT span for each RoundTrip invocation, including redirects and Clientkit retries. It injects trace context from that attempt span and ends the span when response headers or a transport error are available; response-body reads and closes do not alter the span.

By default the transport omits server address, port, URL, and standard HTTP metrics. WithRequestTargetAttributes explicitly adds server identity and a url.full with user information, query, and fragment omitted. WithStandardClientMetrics explicitly enables http.client.request.duration and its required server.address and server.port dimensions. Metric attributes are configured independently from span attributes; Clientkit never adds URLs or raw errors to metrics automatically. Callers remain responsible for keeping explicitly supplied metric attributes safe and low-cardinality.

New captures the global TextMapPropagator. NewWithTextMapPropagator accepts an explicit propagation policy. NewTransport captures applicable global OpenTelemetry providers or the TextMapPropagator unless explicit transport options are supplied. Applications should configure globals first and remain responsible for SDK, exporter, provider, and propagator lifecycle.

Clientkit automatically installs the logical observer and physical transport instrumentation only when httpclient owns the default HTTP client and Config.Observer is nil. Explicit wiring for a caller-owned HTTP client or a custom observer looks like:

telemetry, err := clientkitotel.New()
if err != nil {
	// handle error
}

attemptTransport, err := httpclientotel.NewTransport(
	httpclient.DefaultTransport(),
)
if err != nil {
	// handle error
}

client, err := httpclient.New(httpclient.Config{
	Config: clientkit.Config{
		Name:     "payments",
		Observer: telemetry,
	},
	BaseURL:   "https://payments.internal",
	HTTPClient: &http.Client{Transport: attemptTransport},
})

Non-nil observers and caller-owned HTTP clients replace the automatic instrumentation boundary, so these explicit adapters are not duplicated. Use clientkit.MultiObserver or httpclient.MultiHeaderPropagator for explicit additive composition. Injected header values may be sensitive and must never be used as telemetry labels.

Index

• type Option
  • func WithInstrumentationVersion(version string) Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithMetricAttributes(attributes ...attribute.KeyValue) Option
  • func WithRequestTargetAttributes() Option
  • func WithSpanAttributes(attributes ...attribute.KeyValue) Option
  • func WithStandardClientMetrics() Option
  • func WithTextMapPropagator(propagator propagation.TextMapPropagator) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
• type Propagator
  • func New() *Propagator
  • func NewWithTextMapPropagator(propagator propagation.TextMapPropagator) *Propagator
  • func (p *Propagator) Inject(ctx context.Context, headers http.Header)
• type Transport
  • func NewTransport(base http.RoundTripper, options ...Option) (*Transport, error)
  • func (t *Transport) CloseIdleConnections()
  • func (t *Transport) RoundTrip(request *http.Request) (*http.Response, error)

Types

type Option

type Option func(*config)

Option configures a Transport during construction.

func WithInstrumentationVersion

func WithInstrumentationVersion(version string) Option

WithInstrumentationVersion sets the instrumentation scope version used by transports.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider uses provider for explicitly enabled standard HTTP client metrics. A nil provider falls back to the global provider during transport construction.

func WithMetricAttributes

func WithMetricAttributes(attributes ...attribute.KeyValue) Option

WithMetricAttributes adds bounded attributes to explicitly enabled standard HTTP client metrics. Values must be stable and low-cardinality.

func WithRequestTargetAttributes

func WithRequestTargetAttributes() Option

WithRequestTargetAttributes includes server.address, server.port, and a URL with user information, query, and fragment omitted on physical HTTP spans. It is disabled by default because paths and endpoint identity may be sensitive.

func WithSpanAttributes

func WithSpanAttributes(attributes ...attribute.KeyValue) Option

WithSpanAttributes adds attributes to each physical HTTP CLIENT span. Values may have trace-appropriate cardinality but must not contain secrets.

func WithStandardClientMetrics

func WithStandardClientMetrics() Option

WithStandardClientMetrics enables http.client.request.duration. Enabling it explicitly consents to server.address and server.port metric dimensions, which are required by the OpenTelemetry HTTP semantic conventions.

func WithTextMapPropagator

func WithTextMapPropagator(propagator propagation.TextMapPropagator) Option

WithTextMapPropagator uses propagator for Transport outbound injection. A nil value falls back to the global OpenTelemetry propagator during construction.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider uses provider for per-RoundTrip client spans. A nil provider falls back to the global provider during transport construction.

type Propagator

type Propagator struct {
	// contains filtered or unexported fields
}

Propagator injects OpenTelemetry context into outbound HTTP headers without creating spans or metrics. It may be called concurrently.

func New

func New() *Propagator

New constructs a Propagator and captures the global OpenTelemetry text-map propagator.

func NewWithTextMapPropagator

func NewWithTextMapPropagator(propagator propagation.TextMapPropagator) *Propagator

NewWithTextMapPropagator constructs a Propagator using propagator. A nil value captures the global OpenTelemetry text-map propagator.

func (*Propagator) Inject

func (p *Propagator) Inject(ctx context.Context, headers http.Header)

Inject writes the configured OpenTelemetry propagation fields into headers. It does not extract context, create telemetry, or retain the header map.

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport records one OpenTelemetry CLIENT span for each RoundTrip. Spans end after response headers or a transport error; response-body use does not extend their lifecycle.

func NewTransport

func NewTransport(base http.RoundTripper, options ...Option) (*Transport, error)

NewTransport wraps base with Clientkit's per-RoundTrip OpenTelemetry instrumentation. A nil base selects http.DefaultTransport. The global providers and text-map propagator are captured during construction unless explicit options are supplied.

func (*Transport) CloseIdleConnections

func (t *Transport) CloseIdleConnections()

CloseIdleConnections forwards idle-pool cleanup to the wrapped transport when it exposes the standard net/http optional capability.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(request *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.