From 740bcb4d35ffe418628d3779b2019a746e2ee321 Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Tue, 3 Nov 2026 16:18:12 -0700 Subject: [PATCH 1/8] feat(telemetry): add telemetry-2 failure handler Add the handler for conformance requirement telemetry-2. The step "charge" throws "card declined" with no retry. The handler catches the step error and throws "payment failed" with the step error as its cause. So the execution fails and the exported record is FAILED with an error on the execution and on the operation. Add the template function, the README row, and the pom description. --- conformance-tests-telemetry/README.md | 6 +- conformance-tests-telemetry/pom.xml | 2 +- .../telemetry/Telemetry2Failure.java | 83 +++++++++++++++++++ conformance-tests-telemetry/template.yaml | 11 +++ 4 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java diff --git a/conformance-tests-telemetry/README.md b/conformance-tests-telemetry/README.md index e987ec697..4b438e2cb 100644 --- a/conformance-tests-telemetry/README.md +++ b/conformance-tests-telemetry/README.md @@ -19,6 +19,7 @@ template that maps it to the requirement ID. | Suite | Requirement | What it pins down | | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `telemetry` | `telemetry-1` | One successful single-step execution emits one `SUCCEEDED` record with `input`, `output`, ARN-derived identity fields, and `operationsByName`. | +| `telemetry` | `telemetry-2` | One failed execution emits one `FAILED` record. The execution `error` and `operationsByName.charge.error` carry a cause chain. | ## Layout @@ -27,10 +28,11 @@ pom.xml # standalone Maven project (not a reac template.yaml # telemetry suite; declares TelemetryLogGroupName and creates the group src/main/java/software/amazon/lambda/durable/conformance/telemetry/ Telemetry1Success.java # single step "increment"; plugin + CloudWatchLogsExporter + Telemetry2Failure.java # step "charge" fails; handler throws "payment failed" with the step error as cause ``` -The handler uses the real SDK API only. It constructs no record and calls no exporter method. A missing or wrong record -is the plugin's defect. That defect is the signal the suite measures. +The handlers use the real SDK API only. They construct no record and call no exporter method. A missing or wrong +record is the plugin's defect. That defect is the signal the suite measures. The handler configuration is: one `CloudWatchLogsExporter`, emit mode `ON_COMPLETE`, sampling rate 1, operation detail `TOP_LEVEL`, and content input and output enabled. diff --git a/conformance-tests-telemetry/pom.xml b/conformance-tests-telemetry/pom.xml index 4c55da4c0..6e6b03837 100644 --- a/conformance-tests-telemetry/pom.xml +++ b/conformance-tests-telemetry/pom.xml @@ -21,7 +21,7 @@ AWS Lambda Durable Execution SDK Telemetry Conformance Tests Java SDK handlers and SAM template for the Durable Execution Telemetry conformance - suite (telemetry-1). + suite (telemetry-1, telemetry-2). diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java new file mode 100644 index 000000000..0c7da0a3d --- /dev/null +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java @@ -0,0 +1,83 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 +package software.amazon.lambda.durable.conformance.telemetry; + +import software.amazon.lambda.durable.DurableConfig; +import software.amazon.lambda.durable.DurableContext; +import software.amazon.lambda.durable.DurableHandler; +import software.amazon.lambda.durable.config.StepConfig; +import software.amazon.lambda.durable.retry.RetryStrategies; +import software.amazon.lambda.durable.telemetry.ContentConfig; +import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetry; +import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig; +import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; + +/** + * Failed single-step scenario for requirement telemetry-2. + * + *

The step {@code charge} throws {@code card declined}. The retry strategy declines, so the step fails on its first + * attempt. The handler catches the step error and throws {@code payment failed} with the step error as its cause. So + * the execution fails and the exported record carries a cause chain on the execution {@code error} and an + * {@code error} on {@code operationsByName.charge}. telemetry-2 pins the messages {@code card declined} and + * {@code payment failed}. Do not change them. + * + *

The handler configures the telemetry plugin exactly as {@link Telemetry1Success}. It constructs no record and + * calls no exporter method. The plugin builds and exports the record. + */ +public final class Telemetry2Failure extends DurableHandler { + + // The deployed function must export to the log group the runner reads. + // A missing variable would produce a function that exports nowhere. + // So class initialization fails when the variable is unset. + private static final String LOG_GROUP_NAME = System.getenv("TELEMETRY_LOG_GROUP_NAME"); + + static { + if (LOG_GROUP_NAME == null || LOG_GROUP_NAME.isBlank()) { + throw new IllegalStateException("TELEMETRY_LOG_GROUP_NAME must be set"); + } + } + + @Override + protected DurableConfig createConfiguration() { + return DurableConfig.builder() + .withPlugins(DurableExecutionTelemetry.durableExecutionTelemetry( + DurableExecutionTelemetryConfig.builder() + .addExporter(CloudWatchLogsExporter.builder() + .logGroupName(LOG_GROUP_NAME) + .build()) + .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) + .samplingRate(1.0) + .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) + .content(ContentConfig.builder() + .input(true) + .output(true) + .build()) + .build())) + .build(); + } + + @Override + public Void handleRequest(Input input, DurableContext context) { + try { + context.step( + "charge", + Void.class, + step -> { + throw new RuntimeException("card declined"); + }, + StepConfig.builder() + .retryStrategy(RetryStrategies.Presets.NO_RETRY) + .build()); + } catch (RuntimeException stepError) { + throw new RuntimeException("payment failed", stepError); + } + return null; + } + + /** Event payload: {"value": 41}. */ + public static final class Input { + public int value; + + public Input() {} + } +} diff --git a/conformance-tests-telemetry/template.yaml b/conformance-tests-telemetry/template.yaml index 1f900ba84..81dfd7a2b 100644 --- a/conformance-tests-telemetry/template.yaml +++ b/conformance-tests-telemetry/template.yaml @@ -43,3 +43,14 @@ Resources: CodeUri: . Handler: software.amazon.lambda.durable.conformance.telemetry.Telemetry1Success Role: !Ref LambdaExecutionRoleArn + + Telemetry2Failure: + Type: AWS::Serverless::Function + DependsOn: TelemetryLogGroup + TestingMetadata: + TestDescription: + - telemetry-2 + Properties: + CodeUri: . + Handler: software.amazon.lambda.durable.conformance.telemetry.Telemetry2Failure + Role: !Ref LambdaExecutionRoleArn From 3d4eba3085d09beb3897fad7f484e436514f276b Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Wed, 4 Nov 2026 11:57:00 -0700 Subject: [PATCH 2/8] docs(telemetry): telemetry-2 asserts error presence; pin the shared workflow to the #179 head The team decided that error names and cause depth differ per SDK by design. Conformance PR #179 at 121e832 now matches each telemetry-2 `error` with `{$object: {}}`: present and an object, keys unchecked. So this SDK's two- level execution error and one-level step error pass. The README row and the handler javadoc no longer describe a cause chain. The workflow pin moves from 0eaf734, which predates telemetry-2 and made the runner skip the new handler, to the #179 head 121e832 so this PR's run exercises telemetry-2. telemetry-suite.yml is identical between the two commits. TEMPORARY: bump to the #179 merge commit on main before merging. --- .github/workflows/telemetry-conformance-tests.yml | 8 +++++--- conformance-tests-telemetry/README.md | 2 +- .../durable/conformance/telemetry/Telemetry2Failure.java | 7 ++++--- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/.github/workflows/telemetry-conformance-tests.yml b/.github/workflows/telemetry-conformance-tests.yml index c36149916..04b2241b0 100644 --- a/.github/workflows/telemetry-conformance-tests.yml +++ b/.github/workflows/telemetry-conformance-tests.yml @@ -43,9 +43,11 @@ jobs: contents: read id-token: write # The pinned SHA also selects the runner and telemetry-extension revision the shared - # workflow installs, so it must be reachable from a branch. It is the merge commit of - # aws-durable-execution-conformance-tests PR #150 on that repository's main branch. - uses: aws/aws-durable-execution-conformance-tests/.github/workflows/telemetry-suite.yml@0eaf7341c0c7ff937e6a4bf6bda1682ff07e7502 + # workflow installs, so it must be reachable from a branch. TEMPORARY: it is the head of + # aws-durable-execution-conformance-tests PR #179, which adds telemetry-2. The pin makes + # this PR's run exercise telemetry-2 before #179 merges. Bump it to the #179 merge commit + # on that repository's main branch before merging this PR. + uses: aws/aws-durable-execution-conformance-tests/.github/workflows/telemetry-suite.yml@121e832ec6d28f2daae48ce9d8ca92b2d3f20c12 with: language: java resource_prefix: java diff --git a/conformance-tests-telemetry/README.md b/conformance-tests-telemetry/README.md index 4b438e2cb..9ee702d28 100644 --- a/conformance-tests-telemetry/README.md +++ b/conformance-tests-telemetry/README.md @@ -19,7 +19,7 @@ template that maps it to the requirement ID. | Suite | Requirement | What it pins down | | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `telemetry` | `telemetry-1` | One successful single-step execution emits one `SUCCEEDED` record with `input`, `output`, ARN-derived identity fields, and `operationsByName`. | -| `telemetry` | `telemetry-2` | One failed execution emits one `FAILED` record. The execution `error` and `operationsByName.charge.error` carry a cause chain. | +| `telemetry` | `telemetry-2` | One failed execution emits one `FAILED` record with an `error` on the execution and on `operationsByName.charge`. | ## Layout diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java index 0c7da0a3d..b91283ba7 100644 --- a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java @@ -17,9 +17,10 @@ * *

The step {@code charge} throws {@code card declined}. The retry strategy declines, so the step fails on its first * attempt. The handler catches the step error and throws {@code payment failed} with the step error as its cause. So - * the execution fails and the exported record carries a cause chain on the execution {@code error} and an - * {@code error} on {@code operationsByName.charge}. telemetry-2 pins the messages {@code card declined} and - * {@code payment failed}. Do not change them. + * the execution fails and the exported record carries an {@code error} on the execution and on + * {@code operationsByName.charge}. Error names and cause depth differ per SDK by design, so telemetry-2 asserts only + * that each error is an object. It pins the messages {@code card declined} and {@code payment failed} through the + * core execution-result and history sections. Do not change them. * *

The handler configures the telemetry plugin exactly as {@link Telemetry1Success}. It constructs no record and * calls no exporter method. The plugin builds and exports the record. From ecb5e34e99410cea558c45c371d68ebfa97b24df Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Wed, 4 Nov 2026 17:44:25 -0700 Subject: [PATCH 3/8] refactor(telemetry): share the handler setup and test the log-group guard Telemetry2Failure copied the TELEMETRY_LOG_GROUP_NAME guard and the full plugin configuration from Telemetry1Success. Two copies of the same setup would have to be changed together by hand. So both now live once in TelemetryConformanceConfig and each handler calls it. The guard used to run inside a static initializer that read the environment. A static initializer that reads the environment cannot be unit tested without a subprocess or a custom classloader. So the guard is now a pure function, requireLogGroupName(String), and the handler passes System.getenv to it. Six tests cover it: null and three blank values throw with the exact message, a set value is returned, and the shared config registers exactly one plugin factory. Removing the guard fails four of them. The module is outside the SDK reactor, so the root build never runs its tests. The telemetry conformance workflow now runs `mvn package` without -DskipTests, which runs them before the deploy artifact is built. JUnit and surefire versions are repeated in the standalone pom from the root pom for the same reason. --- .../workflows/telemetry-conformance-tests.yml | 4 +- conformance-tests-telemetry/README.md | 6 +- conformance-tests-telemetry/pom.xml | 18 +++++ .../telemetry/Telemetry1Success.java | 33 ++------- .../telemetry/Telemetry2Failure.java | 37 ++-------- .../telemetry/TelemetryConformanceConfig.java | 68 +++++++++++++++++++ .../TelemetryConformanceConfigTest.java | 42 ++++++++++++ 7 files changed, 146 insertions(+), 62 deletions(-) create mode 100644 conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java create mode 100644 conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java diff --git a/.github/workflows/telemetry-conformance-tests.yml b/.github/workflows/telemetry-conformance-tests.yml index 04b2241b0..3dd4b597a 100644 --- a/.github/workflows/telemetry-conformance-tests.yml +++ b/.github/workflows/telemetry-conformance-tests.yml @@ -109,7 +109,9 @@ jobs: echo "Using Java SDK version $JAVA_SDK_VERSION" # The runner's sam build runs in a later step. Only GITHUB_ENV carries the version to it. echo "JAVA_SDK_VERSION=$JAVA_SDK_VERSION" >> "$GITHUB_ENV" - mvn -B -q -DskipTests package \ + # No -DskipTests: the module is outside the SDK reactor, so this is the only place its + # unit tests run. The package phase runs them before the deploy artifact is built. + mvn -B -q package \ -Ddurable.sdk.version="$JAVA_SDK_VERSION" \ --file "$EXAMPLES_DIR/pom.xml" secrets: diff --git a/conformance-tests-telemetry/README.md b/conformance-tests-telemetry/README.md index 9ee702d28..48ec560f9 100644 --- a/conformance-tests-telemetry/README.md +++ b/conformance-tests-telemetry/README.md @@ -29,6 +29,9 @@ template.yaml # telemetry suite; declares TelemetryL src/main/java/software/amazon/lambda/durable/conformance/telemetry/ Telemetry1Success.java # single step "increment"; plugin + CloudWatchLogsExporter Telemetry2Failure.java # step "charge" fails; handler throws "payment failed" with the step error as cause + TelemetryConformanceConfig.java # shared log-group guard and plugin config; both handlers call it +src/test/java/software/amazon/lambda/durable/conformance/telemetry/ + TelemetryConformanceConfigTest.java # guard rejects null/blank; config registers one plugin ``` The handlers use the real SDK API only. They construct no record and call no exporter method. A missing or wrong @@ -58,6 +61,7 @@ mvn -B -q -Dmaven.test.skip=true install export JAVA_SDK_VERSION=$(mvn -q help:evaluate -Dexpression=project.version -DforceStdout) cd conformance-tests-telemetry +mvn -B -q package # runs the unit tests; the module is outside the reactor, so the root build does not sam build ``` @@ -76,7 +80,7 @@ durable-execution-conformance \ ## CI -[`.github/workflows/telemetry-conformance-tests.yml:1–118`](../.github/workflows/telemetry-conformance-tests.yml#L1-L118) +[`.github/workflows/telemetry-conformance-tests.yml:1–120`](../.github/workflows/telemetry-conformance-tests.yml#L1-L120) runs on pull requests and pushes to `main` that touch the SDK, telemetry exporter, this module, or the root `pom.xml`. It also supports manual dispatch. diff --git a/conformance-tests-telemetry/pom.xml b/conformance-tests-telemetry/pom.xml index 6e6b03837..a66690f0d 100644 --- a/conformance-tests-telemetry/pom.xml +++ b/conformance-tests-telemetry/pom.xml @@ -33,6 +33,9 @@ ${env.JAVA_SDK_VERSION} 2.56.0 1.4.1 + + 6.1.3 + 3.6.1 @@ -56,6 +59,14 @@ aws-lambda-java-core ${aws.lambda.java.core.version} + + + + org.junit.jupiter + junit-jupiter + ${junit.version} + test + @@ -66,6 +77,13 @@ 3.15.0 + + + org.apache.maven.plugins + maven-surefire-plugin + ${surefire.version} + + org.apache.maven.plugins diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry1Success.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry1Success.java index ffd63802e..5e201cddf 100644 --- a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry1Success.java +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry1Success.java @@ -5,10 +5,6 @@ import software.amazon.lambda.durable.DurableConfig; import software.amazon.lambda.durable.DurableContext; import software.amazon.lambda.durable.DurableHandler; -import software.amazon.lambda.durable.telemetry.ContentConfig; -import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetry; -import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig; -import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; /** * Single successful step scenario for requirement telemetry-1. @@ -18,34 +14,13 @@ */ public final class Telemetry1Success extends DurableHandler { - // The deployed function must export to the log group the runner reads. - // A missing variable would produce a function that exports nowhere. - // So class initialization fails when the variable is unset. - private static final String LOG_GROUP_NAME = System.getenv("TELEMETRY_LOG_GROUP_NAME"); - - static { - if (LOG_GROUP_NAME == null || LOG_GROUP_NAME.isBlank()) { - throw new IllegalStateException("TELEMETRY_LOG_GROUP_NAME must be set"); - } - } + // Class initialization fails when the variable is unset. See TelemetryConformanceConfig.requireLogGroupName. + private static final String LOG_GROUP_NAME = + TelemetryConformanceConfig.requireLogGroupName(System.getenv(TelemetryConformanceConfig.LOG_GROUP_ENV)); @Override protected DurableConfig createConfiguration() { - return DurableConfig.builder() - .withPlugins(DurableExecutionTelemetry.durableExecutionTelemetry( - DurableExecutionTelemetryConfig.builder() - .addExporter(CloudWatchLogsExporter.builder() - .logGroupName(LOG_GROUP_NAME) - .build()) - .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) - .samplingRate(1.0) - .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) - .content(ContentConfig.builder() - .input(true) - .output(true) - .build()) - .build())) - .build(); + return TelemetryConformanceConfig.durableConfig(LOG_GROUP_NAME); } @Override diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java index b91283ba7..6d5f3fe04 100644 --- a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java @@ -7,10 +7,6 @@ import software.amazon.lambda.durable.DurableHandler; import software.amazon.lambda.durable.config.StepConfig; import software.amazon.lambda.durable.retry.RetryStrategies; -import software.amazon.lambda.durable.telemetry.ContentConfig; -import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetry; -import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig; -import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; /** * Failed single-step scenario for requirement telemetry-2. @@ -19,42 +15,21 @@ * attempt. The handler catches the step error and throws {@code payment failed} with the step error as its cause. So * the execution fails and the exported record carries an {@code error} on the execution and on * {@code operationsByName.charge}. Error names and cause depth differ per SDK by design, so telemetry-2 asserts only - * that each error is an object. It pins the messages {@code card declined} and {@code payment failed} through the - * core execution-result and history sections. Do not change them. + * that each error is an object. It pins the messages {@code card declined} and {@code payment failed} through the core + * execution-result and history sections. Do not change them. * *

The handler configures the telemetry plugin exactly as {@link Telemetry1Success}. It constructs no record and * calls no exporter method. The plugin builds and exports the record. */ public final class Telemetry2Failure extends DurableHandler { - // The deployed function must export to the log group the runner reads. - // A missing variable would produce a function that exports nowhere. - // So class initialization fails when the variable is unset. - private static final String LOG_GROUP_NAME = System.getenv("TELEMETRY_LOG_GROUP_NAME"); - - static { - if (LOG_GROUP_NAME == null || LOG_GROUP_NAME.isBlank()) { - throw new IllegalStateException("TELEMETRY_LOG_GROUP_NAME must be set"); - } - } + // Class initialization fails when the variable is unset. See TelemetryConformanceConfig.requireLogGroupName. + private static final String LOG_GROUP_NAME = + TelemetryConformanceConfig.requireLogGroupName(System.getenv(TelemetryConformanceConfig.LOG_GROUP_ENV)); @Override protected DurableConfig createConfiguration() { - return DurableConfig.builder() - .withPlugins(DurableExecutionTelemetry.durableExecutionTelemetry( - DurableExecutionTelemetryConfig.builder() - .addExporter(CloudWatchLogsExporter.builder() - .logGroupName(LOG_GROUP_NAME) - .build()) - .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) - .samplingRate(1.0) - .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) - .content(ContentConfig.builder() - .input(true) - .output(true) - .build()) - .build())) - .build(); + return TelemetryConformanceConfig.durableConfig(LOG_GROUP_NAME); } @Override diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java new file mode 100644 index 000000000..a87afa5b6 --- /dev/null +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java @@ -0,0 +1,68 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 +package software.amazon.lambda.durable.conformance.telemetry; + +import software.amazon.lambda.durable.DurableConfig; +import software.amazon.lambda.durable.telemetry.ContentConfig; +import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetry; +import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig; +import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; + +/** + * Shared plugin setup for the telemetry conformance handlers. + * + *

Every handler in this module exports to the same log group with the same plugin settings. The runner reads that + * log group and compares the record to the requirement. A handler with different settings would produce a record the + * runner cannot match. So the settings live here once and each handler calls these methods. + */ +final class TelemetryConformanceConfig { + + /** Environment variable that names the log group the runner reads. */ + static final String LOG_GROUP_ENV = "TELEMETRY_LOG_GROUP_NAME"; + + private TelemetryConformanceConfig() {} + + /** + * Validates the configured log group name. + * + *

The deployed function must export to the log group the runner reads. A missing name would produce a function + * that exports nowhere, and the runner would time out instead of reporting a configuration error. So this method + * rejects a null or blank name, and the caller fails class initialization. + * + * @param logGroupName the value of {@link #LOG_GROUP_ENV}, possibly null + * @return the same value when it is set and not blank + * @throws IllegalStateException when the value is null or blank + */ + static String requireLogGroupName(String logGroupName) { + if (logGroupName == null || logGroupName.isBlank()) { + throw new IllegalStateException(LOG_GROUP_ENV + " must be set"); + } + return logGroupName; + } + + /** + * Builds the handler configuration with one telemetry plugin and one CloudWatch Logs exporter. + * + *

The exporter creates its client on first export, so calling this method makes no network call. + * + * @param logGroupName the log group the exporter writes to + * @return the configuration a telemetry conformance handler returns from {@code createConfiguration()} + */ + static DurableConfig durableConfig(String logGroupName) { + return DurableConfig.builder() + .withPlugins( + DurableExecutionTelemetry.durableExecutionTelemetry(DurableExecutionTelemetryConfig.builder() + .addExporter(CloudWatchLogsExporter.builder() + .logGroupName(logGroupName) + .build()) + .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) + .samplingRate(1.0) + .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) + .content(ContentConfig.builder() + .input(true) + .output(true) + .build()) + .build())) + .build(); + } +} diff --git a/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java b/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java new file mode 100644 index 000000000..675595b78 --- /dev/null +++ b/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java @@ -0,0 +1,42 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 +package software.amazon.lambda.durable.conformance.telemetry; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.NullSource; +import org.junit.jupiter.params.provider.ValueSource; +import software.amazon.lambda.durable.DurableConfig; + +/** + * Tests the shared handler setup. The handlers read the log group name in a static initializer, so the guard and the + * configuration are tested here through the helper with explicit values instead of through the environment. + */ +class TelemetryConformanceConfigTest { + + @ParameterizedTest + @NullSource + @ValueSource(strings = {"", " ", "\t"}) + void requireLogGroupNameRejectsMissingValue(String value) { + IllegalStateException e = + assertThrows(IllegalStateException.class, () -> TelemetryConformanceConfig.requireLogGroupName(value)); + assertEquals("TELEMETRY_LOG_GROUP_NAME must be set", e.getMessage()); + } + + @Test + void requireLogGroupNameReturnsSetValue() { + String name = "/aws/lambda/durable-execution-telemetry"; + assertSame(name, TelemetryConformanceConfig.requireLogGroupName(name)); + } + + @Test + void durableConfigRegistersOneTelemetryPlugin() { + DurableConfig config = TelemetryConformanceConfig.durableConfig("/aws/lambda/durable-execution-telemetry"); + // The factory is a lambda, so its type carries no useful name. One registered factory is the contract. + assertEquals(1, config.getPluginFactories().size()); + } +} From 0ccc30f2391c9e790b1246321e583bd416f9f014 Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Wed, 4 Nov 2026 18:01:58 -0700 Subject: [PATCH 4/8] test(telemetry): keep the config unit test off the Lambda client DurableConfig.build() fills in a default DurableExecutionClient when none is given. That constructor builds a LambdaClient from environment credentials and sends one getDurableExecutionState warm-up request. So the test that called TelemetryConformanceConfig.durableConfig sent a real request whenever AWS credentials were exported. The helper javadoc also said the method made no network call, which was false. The plugin settings now live in a pure function, telemetryConfig(String), and durableConfig(String) wraps it. The test checks telemetryConfig: one CloudWatchLogsExporter, emit ON_COMPLETE, sampling rate 1.0, TOP_LEVEL operation detail, input and output included. The exporter creates its client on first export, so the test builds no client. The deployed run exercises durableConfig, which has no branch of its own. Test declarations use var where the type is obvious, per AGENTS.md. --- conformance-tests-telemetry/README.md | 2 +- .../telemetry/TelemetryConformanceConfig.java | 41 +++++++++++------- .../TelemetryConformanceConfigTest.java | 42 ++++++++++++++----- 3 files changed, 58 insertions(+), 27 deletions(-) diff --git a/conformance-tests-telemetry/README.md b/conformance-tests-telemetry/README.md index 48ec560f9..4e94d2b6e 100644 --- a/conformance-tests-telemetry/README.md +++ b/conformance-tests-telemetry/README.md @@ -31,7 +31,7 @@ src/main/java/software/amazon/lambda/durable/conformance/telemetry/ Telemetry2Failure.java # step "charge" fails; handler throws "payment failed" with the step error as cause TelemetryConformanceConfig.java # shared log-group guard and plugin config; both handlers call it src/test/java/software/amazon/lambda/durable/conformance/telemetry/ - TelemetryConformanceConfigTest.java # guard rejects null/blank; config registers one plugin + TelemetryConformanceConfigTest.java # guard rejects null/blank; telemetry settings match the runner ``` The handlers use the real SDK API only. They construct no record and call no exporter method. A missing or wrong diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java index a87afa5b6..834365fa4 100644 --- a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfig.java @@ -41,28 +41,39 @@ static String requireLogGroupName(String logGroupName) { } /** - * Builds the handler configuration with one telemetry plugin and one CloudWatch Logs exporter. + * Builds the telemetry plugin settings: one CloudWatch Logs exporter for the given log group, emit on completion, + * sample every execution, top-level operation detail, input and output included. * - *

The exporter creates its client on first export, so calling this method makes no network call. + *

This method constructs no client. The exporter creates its CloudWatch Logs client on first export, and the + * settings object is a plain value. So a unit test can call it with no credentials and no network. + * + * @param logGroupName the log group the exporter writes to + * @return the plugin settings every handler in this module uses + */ + static DurableExecutionTelemetryConfig telemetryConfig(String logGroupName) { + return DurableExecutionTelemetryConfig.builder() + .addExporter(CloudWatchLogsExporter.builder() + .logGroupName(logGroupName) + .build()) + .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) + .samplingRate(1.0) + .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) + .content(ContentConfig.builder().input(true).output(true).build()) + .build(); + } + + /** + * Builds the handler configuration with the telemetry plugin from {@link #telemetryConfig(String)}. + * + *

{@code DurableConfig.build()} constructs the default Lambda client, and that constructor sends one warm-up + * request. So this method is for the deployed handler only. Tests check {@link #telemetryConfig(String)} instead. * * @param logGroupName the log group the exporter writes to * @return the configuration a telemetry conformance handler returns from {@code createConfiguration()} */ static DurableConfig durableConfig(String logGroupName) { return DurableConfig.builder() - .withPlugins( - DurableExecutionTelemetry.durableExecutionTelemetry(DurableExecutionTelemetryConfig.builder() - .addExporter(CloudWatchLogsExporter.builder() - .logGroupName(logGroupName) - .build()) - .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) - .samplingRate(1.0) - .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) - .content(ContentConfig.builder() - .input(true) - .output(true) - .build()) - .build())) + .withPlugins(DurableExecutionTelemetry.durableExecutionTelemetry(telemetryConfig(logGroupName))) .build(); } } diff --git a/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java b/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java index 675595b78..79ef0d905 100644 --- a/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java +++ b/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java @@ -3,40 +3,60 @@ package software.amazon.lambda.durable.conformance.telemetry; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; import org.junit.jupiter.api.Test; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.NullSource; import org.junit.jupiter.params.provider.ValueSource; -import software.amazon.lambda.durable.DurableConfig; +import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig.EmitMode; +import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig.OperationDetail; +import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; /** - * Tests the shared handler setup. The handlers read the log group name in a static initializer, so the guard and the - * configuration are tested here through the helper with explicit values instead of through the environment. + * Tests the shared handler setup through the helper with explicit values. + * + *

The handlers read the log group name in a static initializer, so the guard is tested here, not through the + * environment. {@code durableConfig} builds a {@code DurableConfig}, whose constructor creates the default Lambda + * client and sends a warm-up request. So these tests check {@code telemetryConfig}, which constructs no client. */ class TelemetryConformanceConfigTest { + private static final String LOG_GROUP = "/aws/lambda/durable-execution-telemetry"; + @ParameterizedTest @NullSource @ValueSource(strings = {"", " ", "\t"}) void requireLogGroupNameRejectsMissingValue(String value) { - IllegalStateException e = - assertThrows(IllegalStateException.class, () -> TelemetryConformanceConfig.requireLogGroupName(value)); + var e = assertThrows(IllegalStateException.class, () -> TelemetryConformanceConfig.requireLogGroupName(value)); assertEquals("TELEMETRY_LOG_GROUP_NAME must be set", e.getMessage()); } @Test void requireLogGroupNameReturnsSetValue() { - String name = "/aws/lambda/durable-execution-telemetry"; - assertSame(name, TelemetryConformanceConfig.requireLogGroupName(name)); + assertSame(LOG_GROUP, TelemetryConformanceConfig.requireLogGroupName(LOG_GROUP)); + } + + @Test + void telemetryConfigUsesOneCloudWatchLogsExporter() { + var config = TelemetryConformanceConfig.telemetryConfig(LOG_GROUP); + assertEquals(1, config.exporters().size()); + // The exporter exposes no log group accessor, so the name is not asserted here. The handler passes its + // static LOG_GROUP_NAME straight through, and the deployed run matches no record if the name is wrong. + assertInstanceOf(CloudWatchLogsExporter.class, config.exporters().get(0)); } @Test - void durableConfigRegistersOneTelemetryPlugin() { - DurableConfig config = TelemetryConformanceConfig.durableConfig("/aws/lambda/durable-execution-telemetry"); - // The factory is a lambda, so its type carries no useful name. One registered factory is the contract. - assertEquals(1, config.getPluginFactories().size()); + void telemetryConfigMatchesTheRunnerExpectations() { + var config = TelemetryConformanceConfig.telemetryConfig(LOG_GROUP); + // The runner reads one record per execution with its input and output. These four settings produce that. + assertEquals(EmitMode.ON_COMPLETE, config.emitMode()); + assertEquals(1.0, config.samplingRate()); + assertEquals(OperationDetail.TOP_LEVEL, config.operationDetail()); + assertTrue(config.content().includeInput()); + assertTrue(config.content().includeOutput()); } } From d5dc7256b29bc5c8bfb6572571fd1df1fcb0f82b Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Wed, 4 Nov 2026 18:07:36 -0700 Subject: [PATCH 5/8] style(telemetry): static-import the enum constants in the config test AGENTS.md requires static imports for enum constants. The two assertions used the qualified names EmitMode.ON_COMPLETE and OperationDetail.TOP_LEVEL. --- .../telemetry/TelemetryConformanceConfigTest.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java b/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java index 79ef0d905..df757f759 100644 --- a/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java +++ b/conformance-tests-telemetry/src/test/java/software/amazon/lambda/durable/conformance/telemetry/TelemetryConformanceConfigTest.java @@ -7,13 +7,13 @@ import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; +import static software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE; +import static software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL; import org.junit.jupiter.api.Test; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.NullSource; import org.junit.jupiter.params.provider.ValueSource; -import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig.EmitMode; -import software.amazon.lambda.durable.telemetry.DurableExecutionTelemetryConfig.OperationDetail; import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; /** @@ -53,9 +53,9 @@ void telemetryConfigUsesOneCloudWatchLogsExporter() { void telemetryConfigMatchesTheRunnerExpectations() { var config = TelemetryConformanceConfig.telemetryConfig(LOG_GROUP); // The runner reads one record per execution with its input and output. These four settings produce that. - assertEquals(EmitMode.ON_COMPLETE, config.emitMode()); + assertEquals(ON_COMPLETE, config.emitMode()); assertEquals(1.0, config.samplingRate()); - assertEquals(OperationDetail.TOP_LEVEL, config.operationDetail()); + assertEquals(TOP_LEVEL, config.operationDetail()); assertTrue(config.content().includeInput()); assertTrue(config.content().includeOutput()); } From 0bb88f5e3d9f8c4a41744aaf587528d8ccbb29c6 Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Thu, 5 Nov 2026 10:56:06 -0700 Subject: [PATCH 6/8] fix(telemetry): catch StepFailedException in Telemetry2Failure --- .../durable/conformance/telemetry/Telemetry2Failure.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java index 6d5f3fe04..2be40f39a 100644 --- a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java @@ -6,6 +6,7 @@ import software.amazon.lambda.durable.DurableContext; import software.amazon.lambda.durable.DurableHandler; import software.amazon.lambda.durable.config.StepConfig; +import software.amazon.lambda.durable.exception.StepFailedException; import software.amazon.lambda.durable.retry.RetryStrategies; /** @@ -44,7 +45,7 @@ public Void handleRequest(Input input, DurableContext context) { StepConfig.builder() .retryStrategy(RetryStrategies.Presets.NO_RETRY) .build()); - } catch (RuntimeException stepError) { + } catch (StepFailedException stepError) { throw new RuntimeException("payment failed", stepError); } return null; From e8a5b91bcd29c1158c339c1b44149ba8ef60b743 Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Thu, 5 Nov 2026 11:26:55 -0700 Subject: [PATCH 7/8] fix(telemetry): catch the rebuilt RuntimeException in Telemetry2Failure StepOperation.get() rebuilds the step's original exception from the checkpoint and rethrows it. StepFailedException is only the fallback when that rebuild fails. So the step surfaces as RuntimeException("card declined"), and catch (StepFailedException) from 0bb88f5e3 let it escape. The telemetry run failed with "expected 'payment failed', got 'card declined'". Catch RuntimeException again and state the reason in a comment. --- .../durable/conformance/telemetry/Telemetry2Failure.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java index 2be40f39a..61700c3d3 100644 --- a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry2Failure.java @@ -6,7 +6,6 @@ import software.amazon.lambda.durable.DurableContext; import software.amazon.lambda.durable.DurableHandler; import software.amazon.lambda.durable.config.StepConfig; -import software.amazon.lambda.durable.exception.StepFailedException; import software.amazon.lambda.durable.retry.RetryStrategies; /** @@ -45,7 +44,10 @@ public Void handleRequest(Input input, DurableContext context) { StepConfig.builder() .retryStrategy(RetryStrategies.Presets.NO_RETRY) .build()); - } catch (StepFailedException stepError) { + } catch (RuntimeException stepError) { + // The SDK rebuilds the step's original exception from the checkpoint and rethrows it, so the + // step surfaces as RuntimeException("card declined"). StepFailedException is only the fallback + // when that rebuild fails. Catching StepFailedException would let "card declined" escape. throw new RuntimeException("payment failed", stepError); } return null; From a86237028d848be3b9125c2d642c48914aba55ea Mon Sep 17 00:00:00 2001 From: Harry Nguyen Date: Thu, 5 Nov 2026 14:03:52 -0700 Subject: [PATCH 8/8] ci(telemetry): pin the suite to the #179 merge commit The previous pin was the head of aws-durable-execution-conformance-tests PR #179 (121e832), a temporary pin so the run exercised telemetry-2 before #179 merged. #179 is merged as ca2cd02 on that repository's main branch, so the pin now points at that merge commit. --- .github/workflows/telemetry-conformance-tests.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/telemetry-conformance-tests.yml b/.github/workflows/telemetry-conformance-tests.yml index 3dd4b597a..8ae0bc030 100644 --- a/.github/workflows/telemetry-conformance-tests.yml +++ b/.github/workflows/telemetry-conformance-tests.yml @@ -43,11 +43,9 @@ jobs: contents: read id-token: write # The pinned SHA also selects the runner and telemetry-extension revision the shared - # workflow installs, so it must be reachable from a branch. TEMPORARY: it is the head of - # aws-durable-execution-conformance-tests PR #179, which adds telemetry-2. The pin makes - # this PR's run exercise telemetry-2 before #179 merges. Bump it to the #179 merge commit - # on that repository's main branch before merging this PR. - uses: aws/aws-durable-execution-conformance-tests/.github/workflows/telemetry-suite.yml@121e832ec6d28f2daae48ce9d8ca92b2d3f20c12 + # workflow installs, so it must be reachable from a branch. It is the merge commit of + # aws-durable-execution-conformance-tests PR #179 on that repository's main branch. + uses: aws/aws-durable-execution-conformance-tests/.github/workflows/telemetry-suite.yml@ca2cd02e1fb0dce34c9d81e361c1556a7e3707ee with: language: java resource_prefix: java