slogobserver

Documentation

Overview

Package slogobserver adapts Clientkit observer events to synchronous structured log/slog records. It does not configure a slog handler or own its lifecycle, and it creates no spans or metrics.

Routine successful operations, attempts, and healthy checks use Debug by default. Retries and degraded, unhealthy, or unknown checks use Warn, while final operation failures use Error. Raw Go errors are omitted unless WithErrorDetails is selected.

Clientkit-controlled records never include URLs, paths, headers, bodies, propagated identifiers, or certificate details from Clientkit events. The observer remains independently composable with the OpenTelemetry observer by using clientkit.MultiObserver.

The example below uses these imports:

import (
	"log/slog"
	"net/http"
	"os"

	clientkit "github.com/jaredjakacky/clientkit"
	httpclient "github.com/jaredjakacky/clientkit/httpclient"
	httpclientotel "github.com/jaredjakacky/clientkit/httpclient/otel"
	clientkitotel "github.com/jaredjakacky/clientkit/otel"
	slogobserver "github.com/jaredjakacky/clientkit/slogobserver"
)

Typical wiring looks like:

logger := slog.New(
	slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelDebug,
	}),
)

logs := slogobserver.New(
	logger,
	slogobserver.WithAttributes(
		slog.String("component", "outbound-clients"),
	),
)

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: clientkit.MultiObserver(
			logs,
			telemetry,
		),
	},
	BaseURL:   "https://payments.internal",
	HTTPClient: &http.Client{Transport: attemptTransport},
})

Index

• type LevelConfig
  • func DefaultLevelConfig() LevelConfig
• type Observer
  • func New(logger *slog.Logger, options ...Option) *Observer
  • 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 WithAttributes(attributes ...slog.Attr) Option
  • func WithErrorDetails() Option
  • func WithLevels(levels LevelConfig) Option

Types

type LevelConfig

type LevelConfig struct {
	// OperationSuccess is used for successfully completed operations.
	OperationSuccess slog.Level
	// OperationFailure is used for operations that did not complete successfully.
	OperationFailure slog.Level
	// Attempt is used for every completed execution attempt.
	Attempt slog.Level
	// Retry is used when another attempt has been scheduled.
	Retry slog.Level
	// HealthHealthy is used for healthy check results.
	HealthHealthy slog.Level
	// HealthUnhealthy is used for degraded, unhealthy, and unknown check results.
	HealthUnhealthy slog.Level
}

LevelConfig defines the immutable level used for each Clientkit record type.

func DefaultLevelConfig

func DefaultLevelConfig() LevelConfig

DefaultLevelConfig returns production-safe logging levels. Successful operations, attempts, and healthy checks use Debug; retries and degraded, unhealthy, or unknown checks use Warn; final operation failures use Error.

type Observer

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

Observer adapts protocol-neutral Clientkit lifecycle events to synchronous structured log/slog records. It is immutable and safe for concurrent use.

func New

func New(logger *slog.Logger, options ...Option) *Observer

New constructs an Observer without logging. A nil logger uses slog.Default. Nil options are ignored, and configured common attributes are cloned.

func (*Observer) ObserveAttempt

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

ObserveAttempt emits one completed-attempt record at the configured Attempt level. Raw errors are included only when WithErrorDetails was selected.

func (*Observer) ObserveHealth

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

ObserveHealth emits one completed health-check record. Healthy results use HealthHealthy; degraded, unhealthy, and unknown results use HealthUnhealthy.

func (*Observer) ObserveRetry

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

ObserveRetry emits one retry-scheduling record at the configured Retry level.

func (*Observer) StartOperation

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

StartOperation captures immutable start metadata without emitting a record. Completion is logged when the returned observation is ended.

type Option

type Option func(*config)

Option configures an Observer during construction.

func WithAttributes

func WithAttributes(attributes ...slog.Attr) Option

WithAttributes appends application-controlled attributes to every record. Values should be stable and low-cardinality and must not contain secrets. Service identity may instead be configured on the logger with Logger.With. The supplied slice is cloned and LogValuer values are not resolved during construction.

func WithErrorDetails

func WithErrorDetails() Option

WithErrorDetails opts into adding raw Go errors to operation and attempt records when the event carries an error. Errors may contain URLs, hosts, ports, certificate details, transport text, or other infrastructure and application data. Applications remain responsible for logger redaction and access policy.

func WithLevels

func WithLevels(levels LevelConfig) Option

WithLevels completely replaces the default record-level configuration. Zero fields are used as slog.LevelInfo rather than inheriting individual defaults.