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

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

      Returns:
      new in-memory metrics collector