Observability

The Go runtime exposes credential- and payload-free diagnostics, a bounded lifecycle observer, and an optional OpenTelemetry module. Observer and telemetry failures are isolated from send results.

Diagnostics#

Diagnostics returns one coherent snapshot of current resource use and saturating counters:

Copysnapshot := client.Diagnostics()
log.Printf(
    "in_flight=%d buffered_bytes=%d overloads=%d dropped_events=%d",
    snapshot.InFlightOperations,
    snapshot.BufferedBytes,
    snapshot.ConcurrencyOverloadRejections,
    snapshot.DroppedObserverEvents,
)

The snapshot contains no event payload, customer ID, idempotency key, URL, header value, or credential.

Lifecycle observers#

Pass an Observer when constructing the generated client:

Copyclient, err := repostclient.NewClient(repost.ClientOptions{
    Observer: func(event repost.ObserverEvent) {
        if event.Kind == repost.ObserverEventKindOperationEnd {
            recordOutcome(event.Outcome, event.ErrorCode, event.DeliveryState)
        }
    },
})

Events contain stable outcomes, error codes, delivery states, HTTP status classes, durations, attempt numbers, and bounded attempt summaries. They contain no request or response bodies, headers, credentials, customer IDs, idempotency keys, or URLs.

The queue holds at most 1,024 events. Callbacks run serially on a dedicated goroutine outside send and transport paths. When the queue is full, new events are dropped and counted instead of blocking a send. A callback panic increments ObserverFailures without changing the operation result.

Keep callbacks fast. Send events to your own bounded metrics or logging layer if processing needs more time.

OpenTelemetry#

The OpenTelemetry bridge is a separate Go module so applications that do not use OpenTelemetry do not inherit its dependencies. Install it with:

Copygo get github.com/repost-sh/repost-go/[email protected]

Use global providers:

Copyclient, err := repostclient.NewClient(repost.ClientOptions{
    Telemetry: otelrepost.Telemetry(),
    Observer:  otelrepost.MetricsObserver(),
})

Or pass providers owned by your application:

Copyclient, err := repostclient.NewClient(repost.ClientOptions{
    Telemetry: otelrepost.Telemetry(
        otelrepost.WithTracerProvider(tracerProvider),
    ),
    Observer: otelrepost.MetricsObserver(
        otelrepost.WithMeterProvider(meterProvider),
    ),
})

The bridge borrows providers. Closing the Repost client does not shut them down.

Traces#

The bridge creates one repost.send span and one repost.send.attempt child for each attempt. Passing an inbound request context to a generated send keeps the inbound span as the parent of repost.send.

Attempt spans use http.request.method, repost.retry.attempt, network.protocol.name, http.response.status_code, and error.type. The bridge propagates only W3C traceparent and tracestate headers supplied by the tracing context.

Metrics#

Metrics use only outcome, error.code, delivery.state, and http.status.class. The bridge does not accept arbitrary customer labels.

Continue#