diff --git a/.github/workflows/telemetry-conformance-tests.yml b/.github/workflows/telemetry-conformance-tests.yml index 13fd648f9..507b43b86 100644 --- a/.github/workflows/telemetry-conformance-tests.yml +++ b/.github/workflows/telemetry-conformance-tests.yml @@ -44,8 +44,8 @@ jobs: 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 #179 on that repository's main branch. - uses: aws/aws-durable-execution-conformance-tests/.github/workflows/telemetry-suite.yml@41e034a23b8d12630a8a2d67b9f02c0477fca22d + # aws-durable-execution-conformance-tests PR #183 on that repository's main branch. + uses: aws/aws-durable-execution-conformance-tests/.github/workflows/telemetry-suite.yml@cf13ef27d6e13a4423f7e0a178f9a3d4bb1099f0 with: language: java resource_prefix: java diff --git a/conformance-tests-telemetry/README.md b/conformance-tests-telemetry/README.md index 4e94d2b6e..c8085e38b 100644 --- a/conformance-tests-telemetry/README.md +++ b/conformance-tests-telemetry/README.md @@ -20,6 +20,7 @@ template that maps it to the requirement ID. | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `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 with an `error` on the execution and on `operationsByName.charge`. | +| `telemetry` | `telemetry-3` | An `OperationOverride.withResult` transform exports exactly `{userId}` of a three-key step result; the record has no `input` or `output`. | ## Layout @@ -29,16 +30,18 @@ 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 + Telemetry3ResultSelect.java # step "fetch-user"; override transform keeps only userId in the record + TelemetryConformanceConfig.java # shared log-group guard and plugin config; every handler calls it src/test/java/software/amazon/lambda/durable/conformance/telemetry/ - TelemetryConformanceConfigTest.java # guard rejects null/blank; telemetry settings match the runner + TelemetryConformanceConfigTest.java # guard rejects null/blank; telemetry settings match the runner; telemetry-3 transform and content section ``` 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. +`TOP_LEVEL`, and content input and output enabled. telemetry-3 differs in the content section only: input and output are +disabled, and one `OperationOverride.withResult("fetch-user", ...)` transform selects `userId` from the step result. ## Template contract diff --git a/conformance-tests-telemetry/pom.xml b/conformance-tests-telemetry/pom.xml index a66690f0d..37f671e11 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, telemetry-2). + suite (telemetry-1, telemetry-2, telemetry-3). diff --git a/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry3ResultSelect.java b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry3ResultSelect.java new file mode 100644 index 000000000..5bf3ab508 --- /dev/null +++ b/conformance-tests-telemetry/src/main/java/software/amazon/lambda/durable/conformance/telemetry/Telemetry3ResultSelect.java @@ -0,0 +1,66 @@ +// 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; + +/** + * Per-operation result selection for requirement telemetry-3. + * + *

The step {@code fetch-user} returns {@code {userId, email, token}}. The plugin exports an operation's result only + * when an {@code OperationOverride.withResult} transform opts the operation in. The transform + * {@link TelemetryConformanceConfig#selectUserId(Object)} returns a new map that holds {@code userId} alone. So the + * record's {@code operationsByName.fetch-user.result} is exactly {@code {"userId": "u-123"}}, and {@code email} and + * {@code token} never reach CloudWatch Logs. + * + *

The content section also excludes input and output. telemetry-3 requires that the record carry no {@code input} + * and no {@code output} key. The execution result still holds all three keys, so the core {@code ExpectedResult} check + * proves the transform removed data from the record, not from the step. + * + *

The handler constructs no record and calls no exporter method. The plugin builds and exports the record. + */ +public final class Telemetry3ResultSelect + extends DurableHandler { + + // 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 TelemetryConformanceConfig.durableConfig( + TelemetryConformanceConfig.resultSelectTelemetryConfig(LOG_GROUP_NAME)); + } + + @Override + public Output handleRequest(Input input, DurableContext context) { + return context.step( + TelemetryConformanceConfig.RESULT_SELECT_STEP_NAME, + Output.class, + step -> new Output(input.userId, "test@example.com", "tok-456")); + } + + /** Event payload: {"userId": "u-123"}. */ + public static final class Input { + public String userId; + + public Input() {} + } + + /** Step and execution result: {"userId": "u-123", "email": "test@example.com", "token": "tok-456"}. */ + public static final class Output { + public String userId; + public String email; + public String token; + + public Output() {} + + public Output(String userId, String email, String token) { + this.userId = userId; + this.email = email; + this.token = token; + } + } +} 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 834365fa4..a6c9d0988 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 @@ -2,24 +2,31 @@ // SPDX-License-Identifier: Apache-2.0 package software.amazon.lambda.durable.conformance.telemetry; +import java.util.Map; 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.OperationOverride; 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. + *

Every handler in this module exports to the same log group. Every handler shares the exporter, emit mode, sampling + * rate and operation detail. The content section differs per requirement: telemetry-1 and telemetry-2 include input and + * output; telemetry-3 excludes them and adds one result transform. The runner reads that log group and compares the + * record to the requirement. A handler with different shared settings would produce a record the runner cannot match. + * So the shared 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"; + /** Name of the telemetry-3 step. The override and the step call must use the same string. */ + static final String RESULT_SELECT_STEP_NAME = "fetch-user"; + private TelemetryConformanceConfig() {} /** @@ -48,9 +55,25 @@ static String requireLogGroupName(String logGroupName) { * 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 + * @return the plugin settings the telemetry-1 and telemetry-2 handlers use */ static DurableExecutionTelemetryConfig telemetryConfig(String logGroupName) { + return telemetryConfig( + logGroupName, ContentConfig.builder().input(true).output(true).build()); + } + + /** + * Builds the telemetry plugin settings with a caller-supplied content section. + * + *

Every handler shares the exporter, emit mode, sampling rate, and operation detail. Only the content section + * differs per requirement. telemetry-1 and telemetry-2 include input and output. telemetry-3 excludes both and adds + * a per-operation result override. So the shared settings live here and the content is a parameter. + * + * @param logGroupName the log group the exporter writes to + * @param content the content section for the requirement the handler covers + * @return the plugin settings with the shared fields fixed and the given content + */ + static DurableExecutionTelemetryConfig telemetryConfig(String logGroupName, ContentConfig content) { return DurableExecutionTelemetryConfig.builder() .addExporter(CloudWatchLogsExporter.builder() .logGroupName(logGroupName) @@ -58,10 +81,44 @@ static DurableExecutionTelemetryConfig telemetryConfig(String logGroupName) { .emitMode(DurableExecutionTelemetryConfig.EmitMode.ON_COMPLETE) .samplingRate(1.0) .operationDetail(DurableExecutionTelemetryConfig.OperationDetail.TOP_LEVEL) - .content(ContentConfig.builder().input(true).output(true).build()) + .content(content) .build(); } + /** + * Builds the telemetry-3 settings: the shared exporter and modes, no input, no output, and one result override on + * {@link #RESULT_SELECT_STEP_NAME} that applies {@link #selectUserId(Object)}. + * + *

telemetry-3 requires that the record carry no {@code input} and no {@code output} key, and that + * {@code operationsByName.fetch-user.result} hold exactly {@code {"userId": "u-123"}}. + * + * @param logGroupName the log group the exporter writes to + * @return the plugin settings the telemetry-3 handler uses + */ + static DurableExecutionTelemetryConfig resultSelectTelemetryConfig(String logGroupName) { + return telemetryConfig( + logGroupName, + ContentConfig.builder() + .input(false) + .output(false) + .addOverride(OperationOverride.withResult( + RESULT_SELECT_STEP_NAME, TelemetryConformanceConfig::selectUserId)) + .build()); + } + + /** + * Keeps {@code userId} and drops every other key of a parsed step result. + * + *

The plugin JSON-parses the checkpointed step result before it calls the transform. So the argument is a + * detached {@code Map}, not the handler's output class and not a JSON string. + * + * @param result the parsed step result: a {@code Map} with {@code userId}, {@code email}, and {@code token} + * @return a new single-entry map + */ + static Object selectUserId(Object result) { + return Map.of("userId", ((Map) result).get("userId")); + } + /** * Builds the handler configuration with the telemetry plugin from {@link #telemetryConfig(String)}. * @@ -72,8 +129,21 @@ static DurableExecutionTelemetryConfig telemetryConfig(String logGroupName) { * @return the configuration a telemetry conformance handler returns from {@code createConfiguration()} */ static DurableConfig durableConfig(String logGroupName) { + return durableConfig(telemetryConfig(logGroupName)); + } + + /** + * Builds the handler configuration with the telemetry plugin from the given settings. + * + *

{@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. + * + * @param telemetryConfig the plugin settings, from one of the {@code telemetryConfig} overloads + * @return the configuration a telemetry conformance handler returns from {@code createConfiguration()} + */ + static DurableConfig durableConfig(DurableExecutionTelemetryConfig telemetryConfig) { return DurableConfig.builder() - .withPlugins(DurableExecutionTelemetry.durableExecutionTelemetry(telemetryConfig(logGroupName))) + .withPlugins(DurableExecutionTelemetry.durableExecutionTelemetry(telemetryConfig)) .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 df757f759..39198b194 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,17 +3,21 @@ package software.amazon.lambda.durable.conformance.telemetry; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; 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 java.util.Map; 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.OperationOverride; import software.amazon.lambda.durable.telemetry.exporters.CloudWatchLogsExporter; /** @@ -26,6 +30,9 @@ class TelemetryConformanceConfigTest { private static final String LOG_GROUP = "/aws/lambda/durable-execution-telemetry"; + // The shape the plugin hands to a result transform: the checkpointed step result, JSON-parsed to a Map. + private static final Map PARSED_FETCH_USER_RESULT = + Map.of("userId", "u-123", "email", "test@example.com", "token", "tok-456"); @ParameterizedTest @NullSource @@ -59,4 +66,41 @@ void telemetryConfigMatchesTheRunnerExpectations() { assertTrue(config.content().includeInput()); assertTrue(config.content().includeOutput()); } + + @Test + void selectUserIdKeepsOnlyTheUserIdKey() { + assertEquals(Map.of("userId", "u-123"), TelemetryConformanceConfig.selectUserId(PARSED_FETCH_USER_RESULT)); + } + + @Test + void resultSelectTelemetryConfigKeepsTheSharedSettings() { + var config = TelemetryConformanceConfig.resultSelectTelemetryConfig(LOG_GROUP); + assertEquals(1, config.exporters().size()); + assertInstanceOf(CloudWatchLogsExporter.class, config.exporters().get(0)); + assertEquals(ON_COMPLETE, config.emitMode()); + assertEquals(1.0, config.samplingRate()); + assertEquals(TOP_LEVEL, config.operationDetail()); + } + + @Test + void resultSelectTelemetryConfigExcludesInputAndOutput() { + var content = TelemetryConformanceConfig.resultSelectTelemetryConfig(LOG_GROUP) + .content(); + // telemetry-3 requires that the record carry no input and no output key. + assertFalse(content.includeInput()); + assertFalse(content.includeOutput()); + } + + @Test + void resultSelectTelemetryConfigOverridesTheStepResultWithTheSelectingTransform() { + var overrides = TelemetryConformanceConfig.resultSelectTelemetryConfig(LOG_GROUP) + .content() + .overrides(); + assertEquals(1, overrides.size()); + OperationOverride override = overrides.get(0); + assertEquals("fetch-user", override.operationName()); + assertFalse(override.isExclude()); + assertNotNull(override.result()); + assertEquals(Map.of("userId", "u-123"), override.result().apply(PARSED_FETCH_USER_RESULT)); + } } diff --git a/conformance-tests-telemetry/template.yaml b/conformance-tests-telemetry/template.yaml index 81dfd7a2b..aa0b7aab4 100644 --- a/conformance-tests-telemetry/template.yaml +++ b/conformance-tests-telemetry/template.yaml @@ -54,3 +54,14 @@ Resources: CodeUri: . Handler: software.amazon.lambda.durable.conformance.telemetry.Telemetry2Failure Role: !Ref LambdaExecutionRoleArn + + Telemetry3ResultSelect: + Type: AWS::Serverless::Function + DependsOn: TelemetryLogGroup + TestingMetadata: + TestDescription: + - telemetry-3 + Properties: + CodeUri: . + Handler: software.amazon.lambda.durable.conformance.telemetry.Telemetry3ResultSelect + Role: !Ref LambdaExecutionRoleArn