docs: add plugins page to SDK reference

Author: nvasiu

docs/sdk-reference/index.md

@@ -30,6 +30,10 @@ The core building blocks for constructing durable workflows:
 
 - [Logging](observability/logging.md) Structured logging within durable functions
 
+## Plugins
+
+- [Plugins](plugins/plugins.md) Instrument the execution lifecycle to integrate external tooling
+
 ## Configuration
 
 - [Custom Lambda Client](configuration/custom-lambda-client.md) Configure the Lambda

docs/sdk-reference/plugins/plugins.md

@@ -0,0 +1,228 @@
+# Plugins
+
+Create plugins for instrumenting durable execution lifecycle events. Each SDK
+calls plugin hooks at invocation, operation, and user-function boundaries, so
+you can integrate external tooling, such as observability platforms, without
+changing your handler logic. For example, you can use a plugin to emit a metric
+or trace span each time an operation runs. Errors thrown by a plugin are caught
+and logged, and never affect the execution outcome.
+
+!!! note "Experimental feature"
+
+    The plugin interface is currently experimental and may change in a
+    future release. Feedback is welcome, please share your input through our
+    [GitHub Discussion](https://github.com/aws/aws-durable-execution-docs/discussions/206).
+
+## Define a plugin
+
+A plugin implements any of the following lifecycle hooks, and the SDK calls
+them as the execution runs. Every hook is optional, so implement only the
+ones you need.
+
+The following example plugin shows how to implement every available hook.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/plugins/complete-plugin.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/sdk-reference/plugins/complete-plugin.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/sdk-reference/plugins/complete-plugin.java"
+    ```
+
+The hooks fire at three boundaries: invocation, operation, and the user
+function. Each hook receives an info object describing that event, including
+fields like operation identity, timestamps, or error details.
+
+### Invocation hooks
+
+Invocation hooks run when a Lambda invocation of the execution starts or ends.
+The SDK passes an `isFirstInvocation` flag to the start hook, which indicates
+whether this is the execution's first invocation or a replay.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/plugins/invocation-hooks.ts"
+    ```
+
+    `onInvocationStart` and `onInvocationEnd` both return `Promise<void>`, and
+    the SDK awaits them before continuing the execution.
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/sdk-reference/plugins/invocation-hooks.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/sdk-reference/plugins/invocation-hooks.java"
+    ```
+
+    The SDK awaits `onInvocationEnd` before continuing the execution. All other
+    hooks are fire-and-forget.
+
+### Operation hooks
+
+Operation hooks run when a durable operation, such as a step or wait, starts
+or reaches a terminal status.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/plugins/operation-hooks.ts"
+    ```
+
+    The `isReplay` field on `OperationInfo` indicates whether the hook is
+    firing for the first time or during a replay.
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/sdk-reference/plugins/operation-hooks.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/sdk-reference/plugins/operation-hooks.java"
+    ```
+
+### User-function hooks
+
+User-function hooks run when the code you supply for an operation begins or
+finishes, on that operation's thread.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/plugins/user-function-hooks.ts"
+    ```
+
+    These hooks fire around each step or wait-for-condition attempt. Child
+    context functions are instrumented through `wrapChildContextFn`, a
+    TypeScript-only hook described in
+    [TypeScript-only hooks](#typescript-only-hooks).
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/sdk-reference/plugins/user-function-hooks.py"
+    ```
+
+    These hooks fire around step attempts, child context functions, and
+    wait-for-condition checks.
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/sdk-reference/plugins/user-function-hooks.java"
+    ```
+
+    These hooks fire around step attempts, child context functions, and
+    wait-for-condition checks.
+
+## Use a plugin
+
+Provide plugins in the durable handler configuration. The SDK calls each plugin
+in the order you provide.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/plugins/use-plugin.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/sdk-reference/plugins/use-plugin.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/sdk-reference/plugins/use-plugin.java"
+    ```
+
+## Logging from a plugin
+
+A plugin can add custom fields to log entries so that logs emitted during the
+execution carry extra context.
+
+=== "TypeScript"
+
+    `enrichLogContext` is called for each log entry, and the fields it returns
+    are added to that entry. The enrichment applies wherever the SDK logs. See
+    [Logging](../observability/logging.md) for more about the SDK logger.
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/plugins/log-enrichment-hook.ts"
+    ```
+
+=== "Python"
+
+    A plugin can enrich logs by installing a standard `logging.Filter` on the
+    root logger, usually in its constructor. The filter runs for every log
+    record on the emitting thread, so it can add fields that reflect the
+    plugin's current state. See
+    [Logging](../observability/logging.md) for more about the SDK logger.
+
+    ```python
+    --8<-- "examples/python/sdk-reference/plugins/log-enrichment.py"
+    ```
+
+=== "Java"
+
+    The `onUserFunctionStart` and `onUserFunctionEnd` hooks run on the same
+    thread as the user function, so a plugin can add fields to the SLF4J MDC in
+    those hooks and the logs the function emits include those fields. See
+    [Logging](../observability/logging.md) for more information.
+
+    ```java
+    --8<-- "examples/java/sdk-reference/plugins/log-enrichment.java"
+    ```
+
+## TypeScript-only hooks
+
+!!! warning "TypeScript only"
+
+    These hooks exist only in the TypeScript SDK. The Python and Java plugin
+    interfaces provide observer hooks only, and these methods will not be added
+    to them.
+
+The TypeScript SDK adds wrapper hooks and a checkpoint-change hook. These hooks
+were added to match the callback style common in JavaScript.
+
+### Wrapper hooks
+
+Wrapper hooks run code around a unit of work. `wrapInvocation` wraps the whole
+invocation, `wrapChildContextFn` wraps a child context function, and
+`wrapOperationAttemptFn` wraps a single step or wait-for-condition attempt. Use
+them to run setup and teardown around the work, such as establishing context
+that the wrapped code runs within.
+
+```typescript
+--8<-- "examples/typescript/sdk-reference/plugins/wrapper-hooks.ts"
+```
+
+### Checkpoint-change hook
+
+`onOperationChange` fires when a checkpoint response reports that operations
+changed status. It receives the operations that changed and a snapshot of all
+operations.
+
+```typescript
+--8<-- "examples/typescript/sdk-reference/plugins/checkpoint-change-hook.ts"
+```

examples/java/sdk-reference/plugins/complete-plugin.java

@@ -0,0 +1,40 @@
+import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
+import software.amazon.lambda.durable.plugin.InvocationInfo;
+import software.amazon.lambda.durable.plugin.InvocationEndInfo;
+import software.amazon.lambda.durable.plugin.OperationInfo;
+import software.amazon.lambda.durable.plugin.OperationEndInfo;
+import software.amazon.lambda.durable.plugin.UserFunctionStartInfo;
+import software.amazon.lambda.durable.plugin.UserFunctionEndInfo;
+
+public class ExamplePlugin implements DurableExecutionPlugin {
+    @Override
+    public void onInvocationStart(InvocationInfo info) {
+        System.out.println("invocation start " + info.durableExecutionArn()
+                + " " + info.isFirstInvocation());
+    }
+
+    @Override
+    public void onInvocationEnd(InvocationEndInfo info) {
+        System.out.println("invocation end " + info.invocationStatus());
+    }
+
+    @Override
+    public void onOperationStart(OperationInfo info) {
+        System.out.println("operation start " + info.type() + " " + info.name());
+    }
+
+    @Override
+    public void onOperationEnd(OperationEndInfo info) {
+        System.out.println("operation end " + info.name());
+    }
+
+    @Override
+    public void onUserFunctionStart(UserFunctionStartInfo info) {
+        System.out.println("user function start " + info.name() + " " + info.attempt());
+    }
+
+    @Override
+    public void onUserFunctionEnd(UserFunctionEndInfo info) {
+        System.out.println("user function end " + info.name() + " " + info.succeeded());
+    }
+}

examples/java/sdk-reference/plugins/invocation-hooks.java

@@ -0,0 +1,10 @@
+@Override
+public void onInvocationStart(InvocationInfo info) {
+    System.out.println("invocation start " + info.durableExecutionArn()
+            + " " + info.isFirstInvocation());
+}
+
+@Override
+public void onInvocationEnd(InvocationEndInfo info) {
+    System.out.println("invocation end " + info.invocationStatus());
+}

examples/java/sdk-reference/plugins/log-enrichment.java

@@ -0,0 +1,9 @@
+@Override
+public void onUserFunctionStart(UserFunctionStartInfo info) {
+    MDC.put("operationName", info.name());
+}
+
+@Override
+public void onUserFunctionEnd(UserFunctionEndInfo info) {
+    MDC.remove("operationName");
+}

examples/java/sdk-reference/plugins/operation-hooks.java

@@ -0,0 +1,9 @@
+@Override
+public void onOperationStart(OperationInfo info) {
+    System.out.println("operation start " + info.type() + " " + info.name());
+}
+
+@Override
+public void onOperationEnd(OperationEndInfo info) {
+    System.out.println("operation end " + info.name());
+}

examples/java/sdk-reference/plugins/use-plugin.java

@@ -0,0 +1,17 @@
+import software.amazon.lambda.durable.DurableConfig;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+
+public class ExampleHandler extends DurableHandler<Object, String> {
+    @Override
+    protected DurableConfig createConfiguration() {
+        return DurableConfig.builder()
+                .withPlugins(new ExamplePlugin())
+                .build();
+    }
+
+    @Override
+    protected String handleRequest(Object event, DurableContext context) {
+        return context.step("process", String.class, stepCtx -> "done");
+    }
+}

examples/java/sdk-reference/plugins/user-function-hooks.java

@@ -0,0 +1,9 @@
+@Override
+public void onUserFunctionStart(UserFunctionStartInfo info) {
+    System.out.println("user function start " + info.name() + " " + info.attempt());
+}
+
+@Override
+public void onUserFunctionEnd(UserFunctionEndInfo info) {
+    System.out.println("user function end " + info.name() + " " + info.succeeded());
+}

examples/python/sdk-reference/plugins/complete-plugin.py

@@ -0,0 +1,29 @@
+from aws_durable_execution_sdk_python.plugin import (
+    DurableInstrumentationPlugin,
+    InvocationStartInfo,
+    InvocationEndInfo,
+    OperationStartInfo,
+    OperationEndInfo,
+    UserFunctionStartInfo,
+    UserFunctionEndInfo,
+)
+
+
+class ExamplePlugin(DurableInstrumentationPlugin):
+    def on_invocation_start(self, info: InvocationStartInfo) -> None:
+        print("invocation start", info.execution_arn, info.is_first_invocation)
+
+    def on_invocation_end(self, info: InvocationEndInfo) -> None:
+        print("invocation end", info.status)
+
+    def on_operation_start(self, info: OperationStartInfo) -> None:
+        print("operation start", info.operation_type, info.name)
+
+    def on_operation_end(self, info: OperationEndInfo) -> None:
+        print("operation end", info.name, info.status, info.error)
+
+    def on_user_function_start(self, info: UserFunctionStartInfo) -> None:
+        print("user function start", info.name, info.attempt)
+
+    def on_user_function_end(self, info: UserFunctionEndInfo) -> None:
+        print("user function end", info.name, info.attempt, info.outcome)

examples/python/sdk-reference/plugins/invocation-hooks.py

@@ -0,0 +1,5 @@
+def on_invocation_start(self, info: InvocationStartInfo) -> None:
+    print("invocation start", info.execution_arn, info.is_first_invocation)
+
+def on_invocation_end(self, info: InvocationEndInfo) -> None:
+    print("invocation end", info.status)