Interface MetricsCollector

@ThreadSafe
public interface MetricsCollector

Contract for collecting operational metrics from Pyranid.

The default collector is disabledInstance(), which performs no work. inMemoryInstance() returns a fresh counter-only collector useful for tests and ad-hoc inspection through snapshot().

Implementations must be thread-safe, non-blocking, and failure-tolerant. Pyranid catches and discards collector exceptions so metrics collection cannot affect database behavior.

Since:

4.2.0

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	MetricsCollector.NotificationSessionOutcome	Terminal outcome for an opened notification session.
static final class	MetricsCollector.NotificationSnapshot	Counter snapshot for notification metrics.
static enum	MetricsCollector.PhysicalTransactionBeginFailurePhase	Physical transaction begin phase that failed.
static final record	MetricsCollector.Snapshot	Counter snapshot for collectors that support in-process inspection.
static enum	MetricsCollector.StreamTerminalOutcome	Terminal outcome for an opened stream.
static enum	MetricsCollector.TransactionClosureOutcome	Logical outcome for a closure-based transaction.

Method Summary

Modifier and Type	Method	Description
default void	didAcquireStatementConnection(@NonNull StatementContext<?> ctx, @NonNull Duration acquisitionDuration)	Called after Pyranid successfully acquires a statement-scoped Connection.
default void	didAcquireTransactionConnection(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration acquisitionDuration)	Called after Pyranid successfully acquires the JDBC connection backing a physical transaction.
default void	didBeginPhysicalTransaction(@NonNull Transaction transaction, @NonNull TransactionIsolation isolation, @NonNull DatabaseType databaseType)	Called after Pyranid successfully begins a physical JDBC transaction.
default void	didCloseNotificationSession(@NonNull DatabaseType databaseType, @NonNull UUID notificationSessionId, @NonNull MetricsCollector.NotificationSessionOutcome outcome, @NonNull Duration sessionDuration, @Nullable Throwable throwable)	Called after an opened notification session reaches a terminal state and cleanup completes.
default void	didCloseStream(@NonNull StatementContext<?> ctx, @NonNull MetricsCollector.StreamTerminalOutcome outcome, @NonNull Long rowsConsumed, @NonNull Duration streamDuration, @Nullable Throwable throwable)	Called after an opened stream reaches a terminal state.
default void	didCommitPhysicalTransaction(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration physicalDuration)	Called after Pyranid successfully commits a physical JDBC transaction.
default void	didCreateSavepoint(@NonNull Transaction transaction, @NonNull DatabaseType databaseType)	Called after Pyranid successfully creates a transaction savepoint.
default void	didDeliverNotificationBatch(@NonNull DatabaseType databaseType, @NonNull UUID notificationSessionId, @NonNull Long notificationCount)	Called when Pyranid delivers a nonempty notification batch to application code.
default void	didEnterTransactionClosure(@NonNull Transaction transaction, @NonNull TransactionIsolation isolation, @NonNull DatabaseType databaseType)	Called when Pyranid enters a closure-based transaction.
default void	didExecuteStatement(@NonNull StatementContext<?> ctx, @NonNull StatementLog<?> statementLog, @NonNull StatementResult result)	Called after Pyranid successfully executes a statement.
default void	didExitTransactionClosure(@NonNull Transaction transaction, @NonNull MetricsCollector.TransactionClosureOutcome outcome, @NonNull DatabaseType databaseType, @NonNull Duration logicalDuration, @Nullable Throwable thrown)	Called when Pyranid exits a closure-based transaction.
default void	didFailToAcquireStatementConnection(@NonNull StatementContext<?> ctx, @NonNull DatabaseType databaseType, @NonNull Duration acquisitionDuration, @NonNull Throwable throwable)	Called after Pyranid fails to acquire a statement-scoped Connection.
default void	didFailToAcquireTransactionConnection(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration acquisitionDuration, @NonNull Throwable throwable)	Called after Pyranid fails to acquire the JDBC connection backing a physical transaction.
default void	didFailToBeginPhysicalTransaction(@NonNull Transaction transaction, @NonNull TransactionIsolation isolation, @NonNull MetricsCollector.PhysicalTransactionBeginFailurePhase phase, @NonNull DatabaseType databaseType, @NonNull Throwable throwable)	Called after Pyranid fails while beginning a physical JDBC transaction.
default void	didFailToCommitPhysicalTransaction(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration physicalDuration, @NonNull Throwable throwable)	Called after Pyranid fails to commit a physical JDBC transaction.
default void	didFailToExecuteStatement(@NonNull StatementContext<?> ctx, @NonNull StatementLog<?> statementLog, @NonNull DatabaseType databaseType, @NonNull Throwable throwable)	Called after Pyranid fails to execute a statement.
default void	didFailToOpenNotificationSession(@NonNull DatabaseType databaseType, @NonNull UUID notificationSessionId, @NonNull Duration openDuration, @NonNull Throwable throwable)	Called after Pyranid fails to open a notification session.
default void	didFailToOpenStream(@NonNull StatementContext<?> ctx, @NonNull DatabaseType databaseType, @NonNull Duration openDuration, @NonNull Throwable throwable)	Called after Pyranid fails to open a streaming statement.
default void	didFailToReleaseStatementConnection(@NonNull StatementContext<?> ctx, @NonNull Duration heldDuration, @NonNull Throwable throwable)	Called after Pyranid fails to release a statement-scoped Connection.
default void	didFailToReleaseTransactionConnection(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration heldDuration, @NonNull Throwable throwable)	Called after Pyranid fails to release the JDBC connection backing a physical transaction.
default void	didFailToRollbackPhysicalTransaction(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration physicalDuration, @NonNull Throwable throwable)	Called after Pyranid fails to roll back a physical JDBC transaction.
default void	didLoseNotificationConnection(@NonNull DatabaseType databaseType, @NonNull UUID notificationSessionId, @NonNull Throwable throwable)	Called when a receive operation detects terminal uncertainty or loss of an opened notification connection.
default void	didOpenNotificationSession(@NonNull DatabaseType databaseType, @NonNull UUID notificationSessionId, @NonNull Duration openDuration)	Called after Pyranid successfully opens a notification session and registers every requested channel.
default void	didOpenStream(@NonNull StatementContext<?> ctx, @NonNull Duration openDuration)	Called after Pyranid successfully opens a streaming statement.
default void	didReleaseSavepoint(@NonNull Transaction transaction, @NonNull DatabaseType databaseType)	Called after Pyranid successfully releases a transaction savepoint.
default void	didReleaseStatementConnection(@NonNull StatementContext<?> ctx, @NonNull Duration heldDuration)	Called after Pyranid successfully releases a statement-scoped Connection.
default void	didReleaseTransactionConnection(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration heldDuration)	Called after Pyranid successfully releases the JDBC connection backing a physical transaction.
default void	didRollbackPhysicalTransaction(@NonNull Transaction transaction, @NonNull DatabaseType databaseType, @NonNull Duration physicalDuration)	Called after Pyranid successfully rolls back a physical JDBC transaction.
default void	didRollbackToSavepoint(@NonNull Transaction transaction, @NonNull DatabaseType databaseType)	Called after Pyranid successfully rolls back to a transaction savepoint.
default void	didRunPostTransactionOperation(@NonNull Transaction transaction, @NonNull TransactionResult result, @NonNull DatabaseType databaseType, @NonNull Duration duration, @Nullable Throwable throwable)	Called after a post-transaction operation runs.
static @NonNull MetricsCollector	disabledInstance()	Returns the shared no-op metrics collector.
static @NonNull MetricsCollector	inMemoryInstance()	Creates a fresh in-memory counter collector.
default @NonNull Optional<MetricsCollector.NotificationSnapshot>	notificationSnapshot()	Returns a notification counter snapshot if this collector supports in-process inspection.
default void	reset()	Best-effort reset for test and ad-hoc use.
default @NonNull Optional<MetricsCollector.Snapshot>	snapshot()	Returns a counter snapshot if this collector supports in-process inspection.
default void	willAcquireStatementConnection(@NonNull StatementContext<?> ctx)	Called immediately before Pyranid attempts to acquire a statement-scoped Connection.
default void	willAcquireTransactionConnection(@NonNull Transaction transaction, @NonNull DatabaseType databaseType)	Called immediately before Pyranid attempts to acquire the JDBC connection backing a physical transaction.
default void	willExecuteStatement(@NonNull StatementContext<?> ctx)	Called immediately before Pyranid executes a statement.
default void	willOpenNotificationSession(@NonNull DatabaseType databaseType, @NonNull UUID notificationSessionId)	Called immediately before Pyranid attempts to open a notification session.
default void	willOpenStream(@NonNull StatementContext<?> ctx)	Called immediately before Pyranid opens a streaming statement.

Method Details

willAcquireStatementConnection

default void willAcquireStatementConnection(@NonNull StatementContext<?> ctx)

Called immediately before Pyranid attempts to acquire a statement-scoped Connection.

Statement-scoped connections are used for standalone statement execution and stream opening outside a physical Transaction.

Parameters:

ctx - statement context for the operation that needs a connection

didAcquireStatementConnection

default void didAcquireStatementConnection(@NonNull StatementContext<?> ctx,
 @NonNull Duration acquisitionDuration)

Called after Pyranid successfully acquires a statement-scoped Connection.

Parameters:

ctx - statement context for the operation that acquired a connection

acquisitionDuration - elapsed time spent acquiring the connection

didFailToAcquireStatementConnection

default void didFailToAcquireStatementConnection(@NonNull StatementContext<?> ctx,
 @NonNull DatabaseType databaseType,
 @NonNull Duration acquisitionDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to acquire a statement-scoped Connection.

Parameters:

ctx - statement context for the operation that needed a connection

databaseType - database type known at the time of failure

acquisitionDuration - elapsed time spent attempting to acquire the connection

throwable - failure that prevented connection acquisition

didReleaseStatementConnection

default void didReleaseStatementConnection(@NonNull StatementContext<?> ctx,
 @NonNull Duration heldDuration)

Called after Pyranid successfully releases a statement-scoped Connection.

Parameters:

ctx - statement context for the operation that used the connection

heldDuration - elapsed time between successful acquisition and release

didFailToReleaseStatementConnection

default void didFailToReleaseStatementConnection(@NonNull StatementContext<?> ctx,
 @NonNull Duration heldDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to release a statement-scoped Connection.

Parameters:

ctx - statement context for the operation that used the connection

heldDuration - elapsed time between successful acquisition and the failed release attempt

throwable - failure that prevented connection release

willAcquireTransactionConnection

default void willAcquireTransactionConnection(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType)

Called immediately before Pyranid attempts to acquire the JDBC connection backing a physical transaction.

Pyranid transactions acquire their JDBC connection lazily, so this callback is emitted only when transaction work first needs database access.

Parameters:

transaction - transaction that needs a physical connection

databaseType - database type known at the time of acquisition

didAcquireTransactionConnection

default void didAcquireTransactionConnection(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration acquisitionDuration)

Called after Pyranid successfully acquires the JDBC connection backing a physical transaction.

Parameters:

transaction - transaction that acquired the connection

databaseType - database type known at the time of acquisition

acquisitionDuration - elapsed time spent acquiring the connection

didFailToAcquireTransactionConnection

default void didFailToAcquireTransactionConnection(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration acquisitionDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to acquire the JDBC connection backing a physical transaction.

Parameters:

transaction - transaction that needed a connection

databaseType - database type known at the time of failure

acquisitionDuration - elapsed time spent attempting to acquire the connection

throwable - failure that prevented connection acquisition

didReleaseTransactionConnection

default void didReleaseTransactionConnection(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration heldDuration)

Called after Pyranid successfully releases the JDBC connection backing a physical transaction.

Parameters:

transaction - transaction that owned the connection

databaseType - database type known at the time of release

heldDuration - elapsed time between successful acquisition and release

didFailToReleaseTransactionConnection

default void didFailToReleaseTransactionConnection(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration heldDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to release the JDBC connection backing a physical transaction.

Parameters:

transaction - transaction that owned the connection

databaseType - database type known at the time of failure

heldDuration - elapsed time between successful acquisition and the failed release attempt

throwable - failure that prevented connection release

didEnterTransactionClosure

default void didEnterTransactionClosure(@NonNull Transaction transaction,
 @NonNull TransactionIsolation isolation,
 @NonNull DatabaseType databaseType)

Called when Pyranid enters a closure-based transaction.

This is a logical transaction event and may occur even if user code never performs database work and no physical JDBC transaction is begun.

Parameters:

transaction - transaction passed to the closure through Pyranid APIs

isolation - requested transaction isolation

databaseType - database type known at transaction entry

didExitTransactionClosure

default void didExitTransactionClosure(@NonNull Transaction transaction,
 @NonNull MetricsCollector.TransactionClosureOutcome outcome,
 @NonNull DatabaseType databaseType,
 @NonNull Duration logicalDuration,
 @Nullable Throwable thrown)

Called when Pyranid exits a closure-based transaction.

Parameters:

transaction - transaction that is exiting

outcome - logical transaction outcome

databaseType - database type known at transaction exit

logicalDuration - elapsed time from transaction entry to exit, including user code, physical transaction work, cleanup, and post-transaction operations

thrown - exception or error that caused the transaction to exit abnormally, or null when the transaction completed without a reported failure

didBeginPhysicalTransaction

default void didBeginPhysicalTransaction(@NonNull Transaction transaction,
 @NonNull TransactionIsolation isolation,
 @NonNull DatabaseType databaseType)

Called after Pyranid successfully begins a physical JDBC transaction.

Parameters:

transaction - transaction whose physical JDBC transaction began

isolation - requested transaction isolation

databaseType - database type known at transaction begin

didFailToBeginPhysicalTransaction

default void didFailToBeginPhysicalTransaction(@NonNull Transaction transaction,
 @NonNull TransactionIsolation isolation,
 @NonNull MetricsCollector.PhysicalTransactionBeginFailurePhase phase,
 @NonNull DatabaseType databaseType,
 @NonNull Throwable throwable)

Called after Pyranid fails while beginning a physical JDBC transaction.

Parameters:

transaction - transaction whose physical JDBC transaction failed to begin

isolation - requested transaction isolation

phase - begin phase that failed

databaseType - database type known at the time of failure

throwable - failure that prevented the physical transaction from beginning

didCommitPhysicalTransaction

default void didCommitPhysicalTransaction(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration physicalDuration)

Called after Pyranid successfully commits a physical JDBC transaction.

Parameters:

transaction - transaction that committed

databaseType - database type known at commit time

physicalDuration - elapsed time between physical transaction begin and commit

didFailToCommitPhysicalTransaction

default void didFailToCommitPhysicalTransaction(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration physicalDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to commit a physical JDBC transaction.

Reported when Pyranid's physical commit attempt fails: the JDBC commit call itself, or the success handling that immediately follows it. It does not establish that the driver never received the commit, nor that the commit did not succeed. A completion that refuses the commit before issuing it, such as a savepoint-scope ownership conflict, still fails the transaction without reaching this callback.

Parameters:

transaction - transaction whose commit failed

databaseType - database type known at commit time

physicalDuration - elapsed time between physical transaction begin and the failed commit attempt

throwable - failure that prevented commit from completing normally

didRollbackPhysicalTransaction

default void didRollbackPhysicalTransaction(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration physicalDuration)

Called after Pyranid successfully rolls back a physical JDBC transaction.

Parameters:

transaction - transaction that rolled back

databaseType - database type known at rollback time

physicalDuration - elapsed time between physical transaction begin and rollback

didFailToRollbackPhysicalTransaction

default void didFailToRollbackPhysicalTransaction(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType,
 @NonNull Duration physicalDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to roll back a physical JDBC transaction.

Parameters:

transaction - transaction whose rollback failed

databaseType - database type known at rollback time

physicalDuration - elapsed time between physical transaction begin and the failed rollback attempt

throwable - failure that prevented rollback from completing normally

didRunPostTransactionOperation

default void didRunPostTransactionOperation(@NonNull Transaction transaction,
 @NonNull TransactionResult result,
 @NonNull DatabaseType databaseType,
 @NonNull Duration duration,
 @Nullable Throwable throwable)

Called after a post-transaction operation runs.

Parameters:

transaction - transaction whose post-transaction operation ran

result - transaction result visible to the post-transaction operation

databaseType - database type known at post-transaction execution time

duration - elapsed time spent running the post-transaction operation

throwable - failure thrown by the post-transaction operation, or null when it completed normally

didCreateSavepoint

default void didCreateSavepoint(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType)

Called after Pyranid successfully creates a transaction savepoint.

Parameters:

transaction - transaction that created the savepoint

databaseType - database type known at savepoint creation time

didRollbackToSavepoint

default void didRollbackToSavepoint(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType)

Called after Pyranid successfully rolls back to a transaction savepoint.

Parameters:

transaction - transaction that rolled back to the savepoint

databaseType - database type known at savepoint rollback time

didReleaseSavepoint

default void didReleaseSavepoint(@NonNull Transaction transaction,
 @NonNull DatabaseType databaseType)

Called after Pyranid successfully releases a transaction savepoint.

Parameters:

transaction - transaction that released the savepoint

databaseType - database type known at savepoint release time

willExecuteStatement

default void willExecuteStatement(@NonNull StatementContext<?> ctx)

Called immediately before Pyranid executes a statement.

Parameters:

ctx - statement context for the statement about to execute

didExecuteStatement

default void didExecuteStatement(@NonNull StatementContext<?> ctx,
 @NonNull StatementLog<?> statementLog,
 @NonNull StatementResult result)

Called after Pyranid successfully executes a statement.

Parameters:

ctx - statement context for the executed statement

statementLog - diagnostic statement log for the execution

result - statement execution result

didFailToExecuteStatement

default void didFailToExecuteStatement(@NonNull StatementContext<?> ctx,
 @NonNull StatementLog<?> statementLog,
 @NonNull DatabaseType databaseType,
 @NonNull Throwable throwable)

Called after Pyranid fails to execute a statement.

Parameters:

ctx - statement context for the failed statement

statementLog - diagnostic statement log for the failed execution

databaseType - database type known at statement failure time

throwable - failure thrown while executing the statement

willOpenStream

default void willOpenStream(@NonNull StatementContext<?> ctx)

Called immediately before Pyranid opens a streaming statement.

Parameters:

ctx - statement context for the stream about to open

didOpenStream

default void didOpenStream(@NonNull StatementContext<?> ctx,
 @NonNull Duration openDuration)

Called after Pyranid successfully opens a streaming statement.

Parameters:

ctx - statement context for the opened stream

openDuration - elapsed time spent opening the stream

didFailToOpenStream

default void didFailToOpenStream(@NonNull StatementContext<?> ctx,
 @NonNull DatabaseType databaseType,
 @NonNull Duration openDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to open a streaming statement.

Parameters:

ctx - statement context for the stream that failed to open

databaseType - database type known at stream-open failure time

openDuration - elapsed time spent attempting to open the stream

throwable - failure that prevented the stream from opening

didCloseStream

default void didCloseStream(@NonNull StatementContext<?> ctx,
 @NonNull MetricsCollector.StreamTerminalOutcome outcome,
 @NonNull Long rowsConsumed,
 @NonNull Duration streamDuration,
 @Nullable Throwable throwable)

Called after an opened stream reaches a terminal state.

Pyranid does not emit this callback for streams that fail before they open; those failures are reported through didFailToOpenStream(StatementContext, DatabaseType, Duration, Throwable).

Parameters:

ctx - statement context for the stream

outcome - terminal stream outcome

rowsConsumed - number of rows consumed from the stream

streamDuration - elapsed time between stream-open start and terminal close handling

throwable - failure associated with the terminal outcome, or null when no failure is available

willOpenNotificationSession

default void willOpenNotificationSession(@NonNull DatabaseType databaseType,
 @NonNull UUID notificationSessionId)

Called immediately before Pyranid attempts to open a notification session.

Argument validation, ambient-transaction rejection, database-type resolution, and backend-specific channel validation occur before this callback. Exactly one of didOpenNotificationSession(DatabaseType, UUID, Duration) or didFailToOpenNotificationSession(DatabaseType, UUID, Duration, Throwable) follows it.

Parameters:

databaseType - database type resolved for the notification session

notificationSessionId - identifier for this notification-session invocation

Since:

4.6.0

didOpenNotificationSession

default void didOpenNotificationSession(@NonNull DatabaseType databaseType,
 @NonNull UUID notificationSessionId,
 @NonNull Duration openDuration)

Called after Pyranid successfully opens a notification session and registers every requested channel.

This callback occurs before the application operation is dispatched. It does not indicate that application reconciliation or readiness work has completed.

Parameters:

databaseType - database type resolved for the notification session

notificationSessionId - identifier for this notification-session invocation

openDuration - elapsed time from the corresponding willOpenNotificationSession(DatabaseType, UUID) callback through successful channel registration

Since:

4.6.0

didFailToOpenNotificationSession

default void didFailToOpenNotificationSession(@NonNull DatabaseType databaseType,
 @NonNull UUID notificationSessionId,
 @NonNull Duration openDuration,
 @NonNull Throwable throwable)

Called after Pyranid fails to open a notification session.

This is the terminal lifecycle callback for an invocation that never reached didOpenNotificationSession(DatabaseType, UUID, Duration). It is not followed by didCloseNotificationSession(DatabaseType, UUID, NotificationSessionOutcome, Duration, Throwable). Pyranid emits it after selecting the opening failure and before cleaning up any acquired candidate connection.

Parameters:

databaseType - database type resolved for the notification session

notificationSessionId - identifier for this notification-session invocation

openDuration - elapsed time from the corresponding willOpenNotificationSession(DatabaseType, UUID) callback through the opening failure

throwable - failure that prevented the notification session from opening

Since:

4.6.0

didDeliverNotificationBatch

default void didDeliverNotificationBatch(@NonNull DatabaseType databaseType,
 @NonNull UUID notificationSessionId,
 @NonNull Long notificationCount)

Called when Pyranid delivers a nonempty notification batch to application code.

Empty receive results and notifications discarded during setup or cleanup are not reported.

Parameters:

databaseType - database type resolved for the notification session

notificationSessionId - identifier for the notification session that delivered the batch

notificationCount - number of notifications in the delivered batch

Since:

4.6.0

didLoseNotificationConnection

default void didLoseNotificationConnection(@NonNull DatabaseType databaseType,
 @NonNull UUID notificationSessionId,
 @NonNull Throwable throwable)

Called when a receive operation detects terminal uncertainty or loss of an opened notification connection.

This callback is emitted at most once for a notification session. It does not report setup failures, failures from ordinary database operations performed by application code, or cleanup-only failures.

Parameters:

databaseType - database type resolved for the notification session

notificationSessionId - identifier for the notification session whose connection was lost

throwable - terminal connection failure

Since:

4.6.0

didCloseNotificationSession

default void didCloseNotificationSession(@NonNull DatabaseType databaseType,
 @NonNull UUID notificationSessionId,
 @NonNull MetricsCollector.NotificationSessionOutcome outcome,
 @NonNull Duration sessionDuration,
 @Nullable Throwable throwable)

Called after an opened notification session reaches a terminal state and cleanup completes.

Every invocation that emits didOpenNotificationSession(DatabaseType, UUID, Duration) emits this callback exactly once. Invocations that fail before opening terminate through didFailToOpenNotificationSession(DatabaseType, UUID, Duration, Throwable) instead.

Parameters:

databaseType - database type resolved for the notification session

notificationSessionId - identifier for the notification session

outcome - terminal notification-session outcome

sessionDuration - elapsed time from the corresponding willOpenNotificationSession(DatabaseType, UUID) callback through completed cleanup

throwable - selected failure for MetricsCollector.NotificationSessionOutcome.FAILED, or null for MetricsCollector.NotificationSessionOutcome.CALLBACK_RETURNED and MetricsCollector.NotificationSessionOutcome.INTERRUPTED

Since:

4.6.0

notificationSnapshot

default @NonNull Optional<MetricsCollector.NotificationSnapshot> notificationSnapshot()

Returns a notification counter snapshot if this collector supports in-process inspection.

Implementations may read counters independently without cross-counter atomicity. Callers that need invariant-consistent snapshots should drain in-flight work before reading.

Returns:

a notification metrics snapshot, if supported

Since:

4.6.0

snapshot

default @NonNull Optional<MetricsCollector.Snapshot> snapshot()

Returns a counter snapshot if this collector supports in-process inspection.

Implementations may read counters independently without cross-counter atomicity. Callers that need invariant-consistent snapshots should drain in-flight work before reading.

Returns:

a metrics snapshot, if supported

reset

default void reset()

Best-effort reset for test and ad-hoc use.

Concurrent updates may race with reset operations. Production rolling-window semantics should be implemented outside this interface.

disabledInstance

static @NonNull MetricsCollector disabledInstance()

Returns the shared no-op metrics collector.

Returns:

no-op metrics collector used when metrics collection is disabled

inMemoryInstance

static @NonNull MetricsCollector inMemoryInstance()

Creates a fresh in-memory counter collector.

This collector is intended for tests and lightweight local inspection through snapshot() and notificationSnapshot().

Returns:

new in-memory metrics collector