aws / aws/aws-durable-execution-sdk-java

[Feature]: Java Workflow Insight plugin follow-up work

Open
#679 3 comments 0 reactions 1 assignee Claimed by @wangyb-A View on GitHub
enhancement parity pkg:sdk
Dominant language
Java
Stars
28
Forks
11
Avg merge
1d 8h
Merged PRs (30d)
47

Description

### What would you like?

Add a Workflow Insight plugin to the AWS Lambda Durable Execution SDK for Java.

The plugin should emit a structured summary of each durable execution, including
execution status, timing, input/output, errors, and operation details. It should
follow the JavaScript Workflow Insight contract where practical while accounting
for Java-specific threading, serialization, and plugin lifecycle behavior.

### Why?

Customers need an easier way to inspect and analyze durable workflows without
reconstructing execution state from raw Lambda logs and execution history.

Workflow Insight records enable:

- Execution monitoring and troubleshooting
- Workflow latency and failure analysis
- Operation-level visibility
- Querying records through CloudWatch Logs, S3, and analytics tools
- Consistent observability across JavaScript, Python, and Java SDKs

### Initial scope

- Add a publishable `insight-plugin` Maven module.
- Support schema version `1.0` of the Workflow Insight record.
- Support `ON_COMPLETE`, `ON_FAILURE`, and `ON_CHANGE` emission modes.
- Support deterministic per-execution sampling.
- Support top-level and full-tree operation detail.
- Support input/output transforms, operation result transforms, filtering, and
error controls.
- Support record-size limits and deterministic truncation.
- Isolate plugin and exporter failures from durable execution.
- Publish the plugin to Maven Central and attach it to GitHub releases.

### Acceptance criteria

- [ ] Java plugin hooks expose the execution and operation data required by the
record contract.
- [ ] Workflow Insight module builds as part of the Maven reactor.
- [ ] Records include execution metadata, operation summaries, errors, attempts,
and opted-in results.
- [ ] S3 emits the canonical `operations` array.
- [ ] Lambda and CloudWatch Logs emit `operationsByName`.
- [ ] Sampling, content controls, filtering, truncation, and exporter isolation
have unit coverage.
- [ ] S3 Workflow Insight conformance passes all applicable requirements.
- [ ] CloudWatch Workflow Insight conformance passes all applicable requirements.
- [ ] Release automation publishes the new Maven artifact.
- [ ] Public preview APIs use `@Experimental`.
- [ ] `includeErrors(false)` suppresses execution and operation errors.
- [ ] Plugin `Throwable`s do not disrupt durable execution.
- [ ] Add an ADR documenting the record contract, lifecycle, sampling,
truncation, content-transform, and exporter-ordering decisions.
- [ ] Add customer-facing installation, IAM, configuration, schema, and
troubleshooting documentation.
- [ ] Add automated cloud integration coverage for both S3 and CloudWatch.
- [ ] Complete final human review and merge the implementation PR.

### Design constraints

- Plugin failures must never change the durable execution result.
- Remote exporter I/O must not block SDK checkpoint coordination.
- Memory use must remain bounded across suspended and resumed executions.
- Terminal records must not be overwritten by delayed `RUNNING` records.
- Sensitive input, output, and error content must be configurable.
- Sampling decisions and record behavior should remain aligned across SDKs.
- Breaking record-contract changes require a schema-version change.

### Follow-up work

Check the comments

### Links

- Java implementation:
[PR #661](https://github.com/aws/aws-durable-execution-sdk-java/pull/661)
- Follow-up work:
[Issue #679](https://github.com/aws/aws-durable-execution-sdk-java/issues/679)
- Conformance requirements:
[Conformance PR #73](https://github.com/aws/aws-durable-execution-conformance-tests/pull/73)
- JavaScript reference:
[Workflow Insight package](https://github.com/aws/aws-durable-execution-sdk-js/tree/main/packages/aws-durable-execution-sdk-js-insight)

### Is this a breaking change?

No.

### Does this require an RFC?

No.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.