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

  • 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.
      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