plugins.md

Instrumentation plugins

Instrumentation plugins observe durable execution without changing workflow semantics. The contract is versioned by instrumentation_plugin_api_version, currently 1.

Derive from instrumentation_plugin and override only the hooks needed:

class metrics_plugin final
    : public aws::durable_execution::instrumentation_plugin {
 public:
  void on_operation_end(
      const aws::durable_execution::operation_info& info) override {
    record_operation(info.type, info.status.value_or("UNKNOWN"));
  }
};

Register plugins through run_options:

aws::durable_execution::run_options options{
    .plugins = {std::make_shared<metrics_plugin>()},
};

auto handler = aws::durable_execution::make_lambda_handler(
    service, durable_function,
    aws::durable_execution::default_serdes<Result>{},
    std::move(options));

Hook model

The API exposes:

• invocation start/end, including request ID, execution ARN, input, full operation snapshots, updated operations, first-invocation state, terminal status, result, and error;
• operation start/end with name, type, subtype, parent, status, timestamps, checkpointed result/error, attempt, and replay flags;
• user-function attempt start/end, including outcome and context-children replay state;
• operation-change notifications containing both the updated delta and full operation snapshot.

UpdatedOperationIds from the Lambda invocation identifies operations changed externally between invocations, such as completed waits, callbacks, and chained invokes. The field is optional for backward compatibility.

Safety and performance

Every plugin callback is isolated with a catch-all boundary. A plugin exception is swallowed and remaining plugins still run. Hooks execute synchronously so records are complete before the Lambda response is returned.

When no plugins are configured, lifecycle paths short-circuit before allocating plugin snapshots. Plugins may be called concurrently by parallel/map worker threads and must synchronize mutable state they share.