Class OpenTelemetryMetricsCollector

java.lang.Object

com.soklet.otel.OpenTelemetryMetricsCollector

All Implemented Interfaces:

MetricsCollector

@ThreadSafe
public final class OpenTelemetryMetricsCollector
extends Object
implements MetricsCollector

OpenTelemetry-backed MetricsCollector for Soklet HTTP and SSE telemetry.

This implementation records counters/histograms via OpenTelemetry's metrics API and is designed to be lightweight, thread-safe, and non-blocking in request hot paths.

By default, standard HTTP metrics use OpenTelemetry Semantic Convention names. Soklet-specific concepts (for example SSE queue/drop/broadcast details) are emitted with soklet.* names.

If inbound requests include W3C trace context, Soklet exposes it via Request.getTraceContext() to custom metrics collectors and application code. This metrics-only implementation intentionally does not emit trace IDs, parent IDs, or tracestate values as metric attributes because those values are high-cardinality and belong in logs, spans, or exemplar-aware tracing integrations instead.

See https://soklet.com/docs/metrics-collection for Soklet's metrics/telemetry documentation.

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	OpenTelemetryMetricsCollector.Builder	Builder used to construct instances of OpenTelemetryMetricsCollector.
static enum	OpenTelemetryMetricsCollector.MetricNamingStrategy	Naming strategy for HTTP metric instrument names.

Nested classes/interfaces inherited from interface MetricsCollector

MetricsCollector.Histogram, MetricsCollector.HistogramSnapshot, MetricsCollector.HttpServerRouteKey, MetricsCollector.HttpServerRouteStatusKey, MetricsCollector.McpEndpointRequestOutcomeKey, MetricsCollector.McpEndpointSessionTerminationKey, MetricsCollector.McpEndpointSseStreamTerminationKey, MetricsCollector.MetricsFormat, MetricsCollector.RequestReadFailureKey, MetricsCollector.RequestRejectionKey, MetricsCollector.RouteType, MetricsCollector.Snapshot, MetricsCollector.SnapshotTextOptions, MetricsCollector.SseCommentRouteDropKey, MetricsCollector.SseCommentRouteEnqueueOutcomeKey, MetricsCollector.SseCommentRouteKey, MetricsCollector.SseEventDropReason, MetricsCollector.SseEventEnqueueOutcome, MetricsCollector.SseEventRouteDropKey, MetricsCollector.SseEventRouteEnqueueOutcomeKey, MetricsCollector.SseEventRouteHandshakeFailureKey, MetricsCollector.SseEventRouteKey, MetricsCollector.SseStreamRouteTerminationKey

Method Summary

Modifier and Type	Method	Description
static @NonNull OpenTelemetryMetricsCollector.Builder	builder()	Acquires a builder for OpenTelemetryMetricsCollector instances, using GlobalOpenTelemetry by default.
void	didAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress)
void	didAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)
void	didBroadcastSseComment(@NonNull ResourcePathDeclaration route, @NonNull SseComment.CommentType commentType, int attempted, int enqueued, int dropped)
void	didBroadcastSseEvent(@NonNull ResourcePathDeclaration route, int attempted, int enqueued, int dropped)
void	didDropSseComment(@NonNull SseConnection sseConnection, @NonNull SseComment sseComment, @NonNull MetricsCollector.SseEventDropReason reason, @Nullable Integer payloadBytes, @Nullable Integer queueDepth)
void	didDropSseEvent(@NonNull SseConnection sseConnection, @NonNull SseEvent sseEvent, @NonNull MetricsCollector.SseEventDropReason reason, @Nullable Integer payloadBytes, @Nullable Integer queueDepth)
void	didEstablishSseConnection(@NonNull SseConnection sseConnection)
void	didFailToAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @NonNull ConnectionRejectionReason reason, @Nullable Throwable throwable)
void	didFailToAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget, @NonNull RequestRejectionReason reason, @Nullable Throwable throwable)
void	didFailToEstablishSseConnection(@NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull SseConnection.HandshakeFailureReason reason, @Nullable Throwable throwable)
void	didFailToReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget, @NonNull RequestReadFailureReason reason, @Nullable Throwable throwable)
void	didFailToWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration responseWriteDuration, @NonNull Throwable throwable)
void	didFailToWriteSseComment(@NonNull SseConnection sseConnection, @NonNull SseComment sseComment, @NonNull Duration writeDuration, @NonNull Throwable throwable, @Nullable Duration deliveryLag, @Nullable Integer payloadBytes, @Nullable Integer queueDepth)
void	didFailToWriteSseEvent(@NonNull SseConnection sseConnection, @NonNull SseEvent sseEvent, @NonNull Duration writeDuration, @NonNull Throwable throwable, @Nullable Duration deliveryLag, @Nullable Integer payloadBytes, @Nullable Integer queueDepth)
void	didFinishRequestHandling(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration duration, @NonNull List<@NonNull Throwable> throwables)
void	didStartRequestHandling(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod)
void	didTerminateSseConnection(@NonNull SseConnection sseConnection, @NonNull StreamTermination termination)
void	didWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration responseWriteDuration)
void	didWriteSseComment(@NonNull SseConnection sseConnection, @NonNull SseComment sseComment, @NonNull Duration writeDuration, @Nullable Duration deliveryLag, @Nullable Integer payloadBytes, @Nullable Integer queueDepth)
void	didWriteSseEvent(@NonNull SseConnection sseConnection, @NonNull SseEvent sseEvent, @NonNull Duration writeDuration, @Nullable Duration deliveryLag, @Nullable Integer payloadBytes, @Nullable Integer queueDepth)
static @NonNull OpenTelemetryMetricsCollector	fromMeter(@NonNull Meter meter)	Creates an instance from a required Meter without additional customization.
static @NonNull OpenTelemetryMetricsCollector	fromOpenTelemetry(@NonNull OpenTelemetry openTelemetry)	Creates an instance from a required OpenTelemetry without additional customization.
static @NonNull OpenTelemetryMetricsCollector.Builder	withMeter(@NonNull Meter meter)	Acquires a builder seeded with a required Meter.
static @NonNull OpenTelemetryMetricsCollector.Builder	withOpenTelemetry(@NonNull OpenTelemetry openTelemetry)	Acquires a builder seeded with a required OpenTelemetry instance.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface MetricsCollector

didCreateMcpSession, didEstablishMcpSseStream, didFinishMcpRequestHandling, didReadRequest, didStartMcpRequestHandling, didTerminateMcpSession, didTerminateMcpSseStream, reset, snapshot, snapshotText, willAcceptConnection, willAcceptRequest, willEstablishSseConnection, willReadRequest, willTerminateSseConnection, willWriteResponse, willWriteSseComment, willWriteSseEvent

Method Details

builder

public static @NonNull OpenTelemetryMetricsCollector.Builder builder()

Acquires a builder for OpenTelemetryMetricsCollector instances, using GlobalOpenTelemetry by default.

Returns:

the builder

withMeter

public static @NonNull OpenTelemetryMetricsCollector.Builder withMeter(@NonNull Meter meter)

Acquires a builder seeded with a required Meter.

Parameters:

meter - the meter used to build instruments

Returns:

the builder

withOpenTelemetry

public static @NonNull OpenTelemetryMetricsCollector.Builder withOpenTelemetry(@NonNull OpenTelemetry openTelemetry)

Acquires a builder seeded with a required OpenTelemetry instance.

Parameters:

openTelemetry - the OpenTelemetry instance used to build a meter

Returns:

the builder

fromMeter

public static @NonNull OpenTelemetryMetricsCollector fromMeter(@NonNull Meter meter)

Creates an instance from a required Meter without additional customization.

Parameters:

meter - the meter used to build instruments

Returns:

an OpenTelemetryMetricsCollector instance

fromOpenTelemetry

public static @NonNull OpenTelemetryMetricsCollector fromOpenTelemetry(@NonNull OpenTelemetry openTelemetry)

Creates an instance from a required OpenTelemetry without additional customization.

Parameters:

openTelemetry - the OpenTelemetry instance used to build a meter

Returns:

an OpenTelemetryMetricsCollector instance

didAcceptConnection

public void didAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress)

Specified by:

didAcceptConnection in interface MetricsCollector

didFailToAcceptConnection

public void didFailToAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @NonNull ConnectionRejectionReason reason,
 @Nullable Throwable throwable)

Specified by:

didFailToAcceptConnection in interface MetricsCollector

didAcceptRequest

public void didAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Specified by:

didAcceptRequest in interface MetricsCollector

didFailToAcceptRequest

public void didFailToAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget,
 @NonNull RequestRejectionReason reason,
 @Nullable Throwable throwable)

Specified by:

didFailToAcceptRequest in interface MetricsCollector

didFailToReadRequest

public void didFailToReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget,
 @NonNull RequestReadFailureReason reason,
 @Nullable Throwable throwable)

Specified by:

didFailToReadRequest in interface MetricsCollector

didStartRequestHandling

public void didStartRequestHandling(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod)

Specified by:

didStartRequestHandling in interface MetricsCollector

didFinishRequestHandling

public void didFinishRequestHandling(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration duration,
 @NonNull List<@NonNull Throwable> throwables)

Specified by:

didFinishRequestHandling in interface MetricsCollector

didWriteResponse

public void didWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration responseWriteDuration)

Specified by:

didWriteResponse in interface MetricsCollector

didFailToWriteResponse

public void didFailToWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration responseWriteDuration,
 @NonNull Throwable throwable)

Specified by:

didFailToWriteResponse in interface MetricsCollector

didEstablishSseConnection

public void didEstablishSseConnection(@NonNull SseConnection sseConnection)

Specified by:

didEstablishSseConnection in interface MetricsCollector

didFailToEstablishSseConnection

public void didFailToEstablishSseConnection(@NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull SseConnection.HandshakeFailureReason reason,
 @Nullable Throwable throwable)

Specified by:

didFailToEstablishSseConnection in interface MetricsCollector

didTerminateSseConnection

public void didTerminateSseConnection(@NonNull SseConnection sseConnection,
 @NonNull StreamTermination termination)

Specified by:

didTerminateSseConnection in interface MetricsCollector

didWriteSseEvent

public void didWriteSseEvent(@NonNull SseConnection sseConnection,
 @NonNull SseEvent sseEvent,
 @NonNull Duration writeDuration,
 @Nullable Duration deliveryLag,
 @Nullable Integer payloadBytes,
 @Nullable Integer queueDepth)

Specified by:

didWriteSseEvent in interface MetricsCollector

didFailToWriteSseEvent

public void didFailToWriteSseEvent(@NonNull SseConnection sseConnection,
 @NonNull SseEvent sseEvent,
 @NonNull Duration writeDuration,
 @NonNull Throwable throwable,
 @Nullable Duration deliveryLag,
 @Nullable Integer payloadBytes,
 @Nullable Integer queueDepth)

Specified by:

didFailToWriteSseEvent in interface MetricsCollector

didDropSseEvent

public void didDropSseEvent(@NonNull SseConnection sseConnection,
 @NonNull SseEvent sseEvent,
 @NonNull MetricsCollector.SseEventDropReason reason,
 @Nullable Integer payloadBytes,
 @Nullable Integer queueDepth)

Specified by:

didDropSseEvent in interface MetricsCollector

didWriteSseComment

public void didWriteSseComment(@NonNull SseConnection sseConnection,
 @NonNull SseComment sseComment,
 @NonNull Duration writeDuration,
 @Nullable Duration deliveryLag,
 @Nullable Integer payloadBytes,
 @Nullable Integer queueDepth)

Specified by:

didWriteSseComment in interface MetricsCollector

didFailToWriteSseComment

public void didFailToWriteSseComment(@NonNull SseConnection sseConnection,
 @NonNull SseComment sseComment,
 @NonNull Duration writeDuration,
 @NonNull Throwable throwable,
 @Nullable Duration deliveryLag,
 @Nullable Integer payloadBytes,
 @Nullable Integer queueDepth)

Specified by:

didFailToWriteSseComment in interface MetricsCollector

didDropSseComment

public void didDropSseComment(@NonNull SseConnection sseConnection,
 @NonNull SseComment sseComment,
 @NonNull MetricsCollector.SseEventDropReason reason,
 @Nullable Integer payloadBytes,
 @Nullable Integer queueDepth)

Specified by:

didDropSseComment in interface MetricsCollector

didBroadcastSseEvent

public void didBroadcastSseEvent(@NonNull ResourcePathDeclaration route,
 int attempted,
 int enqueued,
 int dropped)

Specified by:

didBroadcastSseEvent in interface MetricsCollector

didBroadcastSseComment

public void didBroadcastSseComment(@NonNull ResourcePathDeclaration route,
 @NonNull SseComment.CommentType commentType,
 int attempted,
 int enqueued,
 int dropped)

Specified by:

didBroadcastSseComment in interface MetricsCollector