aws / aws/aws-durable-execution-sdk-java
[Feature]: Java Workflow Insight plugin follow-up work
- 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
Assessment
This issue has not been assessed yet.