Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/telemetry-conformance-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 6 additions & 3 deletions conformance-tests-telemetry/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion conformance-tests-telemetry/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
<name>AWS Lambda Durable Execution SDK Telemetry Conformance Tests</name>
<description>
Java SDK handlers and SAM template for the Durable Execution Telemetry conformance
suite (telemetry-1, telemetry-2).
suite (telemetry-1, telemetry-2, telemetry-3).
</description>

<properties>
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
*
* <p>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.
*
* <p>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.
*
* <p>The handler constructs no record and calls no exporter method. The plugin builds and exports the record.
*/
public final class Telemetry3ResultSelect
extends DurableHandler<Telemetry3ResultSelect.Input, Telemetry3ResultSelect.Output> {

// 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;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
* <p>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.
* <p>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() {}

/**
Expand Down Expand Up @@ -48,20 +55,70 @@ 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.
*
* <p>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)
.build())
.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)}.
*
* <p>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) {
Comment thread
hln33 marked this conversation as resolved.
Resolved
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.
*
* <p>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)}.
*
Expand All @@ -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.
*
* <p>{@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();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand All @@ -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<String, Object> PARSED_FETCH_USER_RESULT =
Map.of("userId", "u-123", "email", "test@example.com", "token", "tok-456");

@ParameterizedTest
@NullSource
Expand Down Expand Up @@ -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));
}
}
11 changes: 11 additions & 0 deletions conformance-tests-telemetry/template.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading