otel

Documentation

Overview

Package otel adapts Clientkit observer events to OpenTelemetry traces and metrics.

The package does not initialize an OpenTelemetry SDK or exporter. New uses the global OpenTelemetry providers by default, and applications may supply explicit providers with options. The application owns provider shutdown.

This adapter does not inject trace context or create protocol-specific wire spans. It maps logical operations to INTERNAL spans and direct remote operations, such as TCP dialing, to CLIENT spans. HTTP RoundTrip spans and propagation are configured separately through httpclient/otel.

Span-wide and metric-wide attributes are configured independently. Default metric attributes are intentionally stable and low-cardinality. Raw operation errors are not recorded by default because they may contain sensitive endpoint or application data; WithErrorDetails opts into exception events explicitly.

Explicit HTTP wiring with 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},
})

A non-nil configured observer replaces the protocol client's automatic OpenTelemetry observer. Use clientkit.MultiObserver when logical observation should be additive. A nil HTTP Observer and the owned default HTTP client install both adapters automatically.

Index

• Constants
• type Observer
  • func New(options ...Option) (*Observer, error)
  • func (o *Observer) ObserveAttempt(ctx context.Context, event clientkit.AttemptEvent)
  • func (o *Observer) ObserveHealth(ctx context.Context, event clientkit.HealthEvent)
  • func (o *Observer) ObserveRetry(ctx context.Context, event clientkit.RetryEvent)
  • func (o *Observer) StartOperation(ctx context.Context, event clientkit.OperationStartEvent) (context.Context, clientkit.OperationObservation)
• type Option
  • func WithErrorDetails() Option
  • func WithInstrumentationVersion(version string) Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithMetricAttributes(attributes ...attribute.KeyValue) Option
  • func WithSpanAttributes(attributes ...attribute.KeyValue) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option

Constants

const (
	// AttributeClientName identifies the configured logical client.
	AttributeClientName = "clientkit.client.name"
	// AttributeProtocol identifies the bounded protocol implementation.
	AttributeProtocol = "clientkit.protocol"
	// AttributeOperation identifies the bounded logical operation.
	AttributeOperation = "clientkit.operation"
	// AttributeOutcome records the protocol-defined bounded outcome.
	AttributeOutcome = "clientkit.outcome"
	// AttributeSucceeded records the adapter-normalized success decision.
	AttributeSucceeded = "clientkit.succeeded"
	// AttributeOperationAttempts records Clientkit execution attempts in an operation.
	AttributeOperationAttempts = "clientkit.operation.attempts"
	// AttributeAttemptNumber records a one-based attempt number.
	AttributeAttemptNumber = "clientkit.attempt.number"
	// AttributeRetryAfterAttempt identifies the attempt that scheduled a retry.
	AttributeRetryAfterAttempt = "clientkit.retry.after_attempt"
	// AttributeRetryCause records the bounded retry cause.
	AttributeRetryCause = "clientkit.retry.cause"
	// AttributeRetryDelay records the selected retry delay in seconds.
	AttributeRetryDelay = "clientkit.retry.delay"
	// AttributeHealthState records the bounded dependency-health state.
	AttributeHealthState = "clientkit.health.state"
	// AttributeFailureClass identifies the stable Clientkit failure class.
	AttributeFailureClass = "clientkit.failure.class"
)

Clientkit-owned OpenTelemetry attribute names.

Types

type Observer

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

Observer adapts Clientkit observer events to OpenTelemetry traces and metrics. It is safe for concurrent use.

func New

func New(options ...Option) (*Observer, error)

New constructs an OpenTelemetry observer and creates its instruments without starting or owning an SDK. Global providers are captured during construction when explicit providers are not supplied; applications should configure globals first and remain responsible for provider shutdown.

func (*Observer) ObserveAttempt

func (o *Observer) ObserveAttempt(ctx context.Context, event clientkit.AttemptEvent)

ObserveAttempt records a completed attempt as a span event and metrics.

func (*Observer) ObserveHealth

func (o *Observer) ObserveHealth(ctx context.Context, event clientkit.HealthEvent)

ObserveHealth records health-check metrics and adds an event to an existing recording span without creating another span.

func (*Observer) ObserveRetry

func (o *Observer) ObserveRetry(ctx context.Context, event clientkit.RetryEvent)

ObserveRetry records a scheduled retry as a span event and metrics.

func (*Observer) StartOperation

func (o *Observer) StartOperation(ctx context.Context, event clientkit.OperationStartEvent) (context.Context, clientkit.OperationObservation)

StartOperation starts one span for the complete observed operation. Logical operations use SpanKindInternal; direct remote operations use SpanKindClient.

type Option

type Option func(*config)

Option configures an Observer.

func WithErrorDetails

func WithErrorDetails() Option

WithErrorDetails records the final raw operation error as an OpenTelemetry exception event. Raw errors may contain URLs, endpoint names, certificate details, or application-controlled text, so production callers should enable this only when their telemetry pipeline provides suitable redaction.

func WithInstrumentationVersion

func WithInstrumentationVersion(version string) Option

WithInstrumentationVersion sets the instrumentation scope version used by the observer's tracer and meter.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider uses provider for metrics. A nil provider falls back to the global OpenTelemetry meter provider during construction.

func WithMetricAttributes

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

WithMetricAttributes adds bounded attributes to every emitted Clientkit metric. Values must come from a stable, low-cardinality vocabulary. Request IDs, tenant IDs, URLs, endpoint names, and arbitrary errors must not be used. Clientkit-owned identity, outcome, success, and failure attributes take precedence over conflicting keys.

func WithSpanAttributes

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

WithSpanAttributes adds attributes to every emitted span. Values may have trace-appropriate cardinality but must not contain secrets. Service identity should normally be configured through the OpenTelemetry Resource instead. Clientkit-owned identity, outcome, success, and failure attributes take precedence over conflicting keys.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider uses provider for tracing. A nil provider falls back to the global OpenTelemetry tracer provider during construction.