Package software.amazon.lambda.durable.plugin

Interface DurableExecutionPlugin

@Deprecated public interface DurableExecutionPlugin
Deprecated.
This is a preview API that is experimental and may be changed or removed in future releases.
Plugin interface for instrumenting durable execution lifecycle events.

Implement this interface to integrate observability tools (OpenTelemetry, Datadog, etc.) with the durable execution SDK. The SDK calls these hooks at key lifecycle points without requiring modifications to core SDK code.

All methods have default no-op implementations, allowing plugins to override only the hooks they need.

Plugin errors are isolated — exceptions thrown by plugin methods are caught and logged but never disrupt SDK execution.

  • Method Details

    • onInvocationStart

      default void onInvocationStart(InvocationInfo info)
      Deprecated.
      Called at the start of each Lambda invocation. Use to set up per-invocation state (trace ID, invocation span).

      Check InvocationInfo.isFirstInvocation() to detect the first invocation of an execution (useful for sampling decisions or execution-level span creation).

    • onInvocationEnd

      default void onInvocationEnd(InvocationEndInfo info)
      Deprecated.
      Called at the end of each Lambda invocation. Use to flush spans/metrics before Lambda freezes.

      This hook is awaited — the SDK blocks until it returns. This is the only safe flush point before Lambda freezes the execution environment.

      Check InvocationEndInfo.invocationStatus() to detect if the execution reached a terminal state in this invocation (useful for writing summary records or flushing final data).

    • onOperationStart

      default void onOperationStart(OperationInfo info)
      Deprecated.
      Called when an operation starts (including replay). Use for logging/metrics that want replay visibility.

    • onOperationEnd

      default void onOperationEnd(OperationEndInfo info)
      Deprecated.
      Called once when an operation's terminal status is first observed.

      This is usually the invocation that completes the operation, but it can also be a later invocation that first observes a completion which happened while the execution was suspended (for example an operation that finished during a wait). In that case OperationEndInfo.isReplay() is true, so do not assume this hook only fires with isReplay() == false. It does not fire again on subsequent replays of an already-observed completion.

      The OTel plugin creates operation spans here with backfilled start/end timestamps (emitting a linked continuation span when the completion is observed on a replaying invocation).

    • onOperationChange

      default void onOperationChange(OperationChangeInfo info)
      Deprecated.
      Called when a checkpoint response changes the status of one or more operations.

      Receives the operations that changed and a snapshot of all operations.

    • onUserFunctionStart

      default void onUserFunctionStart(UserFunctionStartInfo info)
      Deprecated.
      Called when a user-provided function starts executing. This fires for both step attempts (with attempt set) and child context functions (with attempt null).

      This hook fires on the same thread as user code, so plugins can set OTel context via Context.makeCurrent() here.

    • onUserFunctionEnd

      default void onUserFunctionEnd(UserFunctionEndInfo info)
      Deprecated.
      Called when a user-provided function finishes executing. This fires for both step attempts and child context functions.

      This hook fires on the same thread as user code, so plugins can close OTel scopes here.

      It fires for every terminal outcome of the user function: normal return, a thrown failure, and suspension. UserFunctionEndInfo.succeeded() is true only on normal return; it is false for both a genuine failure and a suspension. On suspension the UserFunctionEndInfo.error() is the SDK's internal SuspendExecutionException, which is not a user error — plugins that count failures should treat a suspension as a neutral outcome (for example by checking the error type) rather than a failure.