Package at.aimon.session.web.metrics

Interface SessionMetrics

public interface SessionMetrics
Operational metric hooks for WebAgentSessionManager (design §12 WS-06).

Implementations forward to a metrics backend (Micrometer, OpenTelemetry, Dropwizard, …). The interface itself is deliberately framework-agnostic — every method has a no-op default so callers can implement only the metrics they actually export, and so the manager can wire NOOP as the safe default when the application has not asked for instrumentation.

Callback contract:

  • Hooks are invoked on whichever thread emits the corresponding event (turn executor, scheduler, signal-bus dispatcher, …) — implementations must not block and must be thread-safe.
  • Hooks must never throw — the manager wraps each invocation defensively so a metrics outage cannot break the session lifecycle, but well-behaved adapters should still swallow their own exceptions.
  • Latency-bearing hooks receive a non-null Duration. Reason-bearing hooks receive a non-null enum.

The set of hooks mirrors the four §12 acceptance bullets: lock acquire latency, cache hit-rate, evict frequency, and lease-extend failures. Submit-outcome and holder-loss hooks are added because they answer the same operational questions ("are nodes piling up in the inbox?", "did we trip a recovery in production?") with the same backend cost.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    SessionMetrics.CacheEvictionReason
    Why the local session cache dropped an entry.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final SessionMetrics
    NOOP
    No-op metrics.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    onCacheEviction(SessionMetrics.CacheEvictionReason reason)
    Called when the local session cache drops an entry (regardless of cause).
    default void
    onCacheHit()
    Called when LocalSessionCache.ensureOpen found an existing entry.
    default void
    onCacheMiss()
    Called when LocalSessionCache.ensureOpen opened a fresh session.
    default void
    onHolderLossRecovered()
    Called by the holder-loss sweeper after winning the compareAndReset CAS for a stale IN_FLIGHT entry — i.e. exactly once per recovered conversation, on the recovering node.
    default void
    onLeaseExtendFailed()
    Called once per turn when ConversationLock.extend returns false (lease lost).
    default void
    onLeaseExtendSucceeded()
    Called on every successful ConversationLock.extend from the LeaseRenewer.
    default void
    onLockAcquireRejected(Duration latency)
    Called when ConversationLock.tryAcquire() returned empty (lock held elsewhere).
    default void
    onLockAcquireSucceeded(Duration latency)
    Called when ConversationLock.tryAcquire() returned a handle.
    default void
    onSubmitOutcome(WebSubmitOutcome.Kind kind)
    Called once per submit, after the manager has classified the request.

  • Field Details

    • NOOP

      static final SessionMetrics NOOP
      No-op metrics. Wire this in the manager when no metrics backend is configured — keeping the call sites uniform avoids null-checks in hot paths.

  • Method Details

    • onLockAcquireSucceeded

      default void onLockAcquireSucceeded(Duration latency)
      Called when ConversationLock.tryAcquire() returned a handle.
      Parameters:
      latency - wall-clock duration of the tryAcquire call (never null)

    • onLockAcquireRejected

      default void onLockAcquireRejected(Duration latency)
      Called when ConversationLock.tryAcquire() returned empty (lock held elsewhere). The submit is then forwarded to the inbox.
      Parameters:
      latency - wall-clock duration of the tryAcquire call (never null)

    • onCacheHit

      default void onCacheHit()
      Called when LocalSessionCache.ensureOpen found an existing entry.

    • onCacheMiss

      default void onCacheMiss()
      Called when LocalSessionCache.ensureOpen opened a fresh session.

    • onCacheEviction

      default void onCacheEviction(SessionMetrics.CacheEvictionReason reason)
      Called when the local session cache drops an entry (regardless of cause).
      Parameters:
      reason - the eviction classification (never null)

    • onLeaseExtendSucceeded

      default void onLeaseExtendSucceeded()
      Called on every successful ConversationLock.extend from the LeaseRenewer.

    • onLeaseExtendFailed

      default void onLeaseExtendFailed()
      Called once per turn when ConversationLock.extend returns false (lease lost).

    • onSubmitOutcome

      default void onSubmitOutcome(WebSubmitOutcome.Kind kind)
      Called once per submit, after the manager has classified the request.
      Parameters:
      kind - the submit outcome kind (never null)

    • onHolderLossRecovered

      default void onHolderLossRecovered()
      Called by the holder-loss sweeper after winning the compareAndReset CAS for a stale IN_FLIGHT entry — i.e. exactly once per recovered conversation, on the recovering node.