Logger Durable Execution ARN Field Name

[zhongkechen]

Summary

Python and JavaScript SDK loggers currently add the durable execution ARN to
replay-safe logger metadata with the field name executionArn. The Java SDK uses
durableExecutionArn for the same concept, and durableExecutionArn is also the
term used by backend APIs and other durable execution surfaces across SDKs.

At the same time, the Lambda console currently uses executionArn when querying
CloudWatch Logs for a specific durable execution ARN. That makes executionArn
part of an existing user and console workflow, not just an SDK implementation
detail.

This document proposes possible fixes and recommends a compatibility-preserving
path that aligns SDK logger metadata with the broader durableExecutionArn term
without breaking existing Lambda console and user queries.

Current Behavior

In the Python SDK, Logger.from_log_info builds default logger extras like this:

extra = {"executionArn": info.execution_state.durable_execution_arn}

The JavaScript SDK also uses executionArn for the durable execution ARN logger
field. The Java SDK uses durableExecutionArn.

Current naming:

Surface	Durable execution ARN field
Python SDK logger	executionArn
JavaScript SDK logger	executionArn
Java SDK logger	durableExecutionArn
Lambda console CloudWatch Logs query	executionArn
Backend APIs and other durable execution SDK surfaces	durableExecutionArn

Why This Matters

The durable execution ARN is the main correlation key for logs emitted by
durable workflows. Having both executionArn and durableExecutionArn in active
use creates a split between log-query compatibility and API/domain terminology.

Problems:

• Users need different CloudWatch Logs Insights queries across Python,
  JavaScript, Java, and current Lambda console workflows.
• Shared dashboards, alarms, and metric filters need duplicated logic.
• Cross-language examples and documentation become inconsistent.
• Downstream log processors may drop or fail to normalize one of the names.
• A direct rename could break Lambda console log lookup behavior unless the
  console is updated first or the old field is retained.

The desired end state is one canonical durable execution ARN field name across
SDKs, APIs, docs, examples, and console-generated queries.

Goals

• Align logger metadata with durableExecutionArn, the broader backend/API term.
• Preserve compatibility with existing Python and JavaScript users who query
  executionArn.
• Preserve Lambda console CloudWatch Logs lookup behavior while it depends on
  executionArn.
• Keep logger behavior replay-safe and otherwise unchanged.
• Make the migration easy to test and document.

Non-Goals

• Auditing every logger field for cross-language parity.

Short-Term Action: Update Lambda Console Query

Update the Lambda console to query logs using
coalesce(durableExecutionArn, executionArn) or an equivalent fallback. Do this
regardless of which SDK option is chosen.

This short-term action decouples console log lookup from the current
executionArn logger field and lets the console work with:

• Current Python and JavaScript SDK logs that only contain executionArn.
• Current Java SDK logs that contain durableExecutionArn.
• Future Python and JavaScript SDK logs that may contain durableExecutionArn.
• Historical logs from existing durable executions.

Benefits:

• Preserves current console-driven log lookup.
• Allows SDKs to migrate independently.
• Reduces the chance that any SDK field-name change breaks the Lambda console.
• Provides an immediate compatibility improvement for mixed-language logs.

Costs:

• Requires Lambda console work outside the SDK repositories.
• Does not by itself fix SDK logger field inconsistency.
• User-owned queries still need documentation and migration guidance.

Because this action is useful for all SDK migration paths, it should happen in
parallel with the SDK decision rather than being treated as a competing option.

Options

Option 1: Rename executionArn to durableExecutionArn

Change Python and JavaScript logger extras to emit only durableExecutionArn.

Example output:

{
  "durableExecutionArn": "arn:aws:lambda:..."
}

Benefits:

• Fully aligns SDK loggers with Java and backend/API terminology.
• Keeps log payloads minimal.
• Simple implementation in each SDK.

Costs:

• Breaking change for Python and JavaScript users querying, filtering, indexing,
  or alerting on executionArn.
• Breaks current Lambda console CloudWatch Logs lookup behavior unless the
  console is updated in lockstep.
• Hard to detect all downstream consumers before release.
• Requires a major version or very explicit coordinated migration notice.

This is the cleanest final shape but the riskiest immediate change.

Option 2: Emit Both Fields

Add durableExecutionArn while continuing to emit executionArn.

Example output:

{
  "executionArn": "arn:aws:lambda:...",
  "durableExecutionArn": "arn:aws:lambda:..."
}

Benefits:

• Aligns new SDK logs with backend/API terminology and the Java SDK.
• Preserves existing Python and JavaScript user queries.
• Preserves current Lambda console CloudWatch Logs lookup behavior.
• Can ship in a minor release.
• Gives users, docs, dashboards, alarms, and the Lambda console time to migrate.

Costs:

• Duplicates one value in every log record.
• Increases customer CloudWatch Logs ingestion and storage costs because every
  replay-safe log event carries the durable execution ARN twice.
• Leaves two accepted names for some period.
• Requires a clear policy for whether executionArn is a compatibility alias or
  will eventually be removed.

This is the safest compatibility fix, but it creates an ongoing log-volume and
cost tradeoff.

Option 3: Rename Java SDK Field to executionArn

Change the Java SDK logger field from durableExecutionArn to executionArn
instead of changing Python and JavaScript to durableExecutionArn.

Example output:

{
  "executionArn": "arn:aws:lambda:..."
}

Benefits:

• Aligns Java logger metadata with current Python and JavaScript SDK logger
  metadata.
• Aligns Java logger metadata with the current Lambda console CloudWatch Logs
  query behavior.
• Avoids duplicate log fields and therefore avoids the cost increase from
  Option 2.

Costs:

• Moves Java away from backend APIs and other durable execution SDK surfaces
  that already use durableExecutionArn.
• Makes executionArn the cross-SDK logger field even though it is not the
  broader durable execution domain term.
• Breaks existing Java users who query, filter, index, or alert on
  durableExecutionArn.
• Does not help converge SDK logs with API and documentation terminology.

This option is not recommended because it optimizes for current logger and
console compatibility at the expense of the longer-term canonical
durableExecutionArn terminology.

Option 4: Add an Opt-In Logger Field Name Configuration

Introduce a setting that controls whether an SDK emits executionArn,
durableExecutionArn, or both.

Possible Python API shapes:

context.configure_logger_fields(durable_execution_arn_field="durableExecutionArn")

or:

context.set_logger_field_compatibility("backend")

Benefits:

• Lets applications choose their migration timing.
• Avoids duplicate fields for users who care about log size.

Costs:

• Adds API surface for a narrow compatibility issue.
• Creates more behavior combinations to document and test.
• Does not establish a simple cross-SDK default unless paired with another
  option.
• Does not help Lambda console workflows unless users choose a compatible mode.

This is flexible but likely more complexity than the issue warrants.

Option 5: Document Query Aliases Only

Leave SDK behavior unchanged and update docs with cross-language query examples
that handle both names.

Example query:

fields coalesce(durableExecutionArn, executionArn) as durableExecutionArn
| filter durableExecutionArn = "..."

Benefits:

• No SDK behavior change.
• No compatibility risk.

Costs:

• Does not fix the cross-language inconsistency.
• Every user must remember to normalize the field.
• Dashboard, alarm, and console query duplication remains.

This is useful migration guidance, not a complete SDK fix.

Recommendation

Adopt Option 1 for SDKs: rename the durable execution ARN logger field from
executionArn to durableExecutionArn in Python and JavaScript SDK loggers.
This aligns logger metadata with Java, backend APIs, and the broader durable
execution terminology without permanently increasing customer log volume and
cost by emitting duplicate ARN fields.

Recommended actions:

1. Update Lambda console log lookup to support both fields, ideally by querying
   coalesce(durableExecutionArn, executionArn). This should happen regardless
   of which SDK option is chosen.
2. After console fallback support is available, update Python and JavaScript SDK
   loggers to emit durableExecutionArn instead of executionArn.
3. Treat the SDK logger rename as a breaking or explicitly called-out migration,
   because user-owned queries may still depend on executionArn.
4. Update SDK documentation and examples to use durableExecutionArn.
5. Document coalesce(durableExecutionArn, executionArn) for historical logs and
   mixed SDK versions.

This approach moves SDKs to one canonical field, avoids ongoing duplicate-log
costs, and keeps the Lambda console compatible with both old and new logs.

Proposed Python Implementation

Update Logger.from_log_info in
packages/aws-durable-execution-sdk-python/src/aws_durable_execution_sdk_python/logger.py:

extra: MutableMapping[str, object] = {
    "durableExecutionArn": info.execution_state.durable_execution_arn,
}

Keep the existing merge behavior:

merged_extra = {**self._default_extra, **(extra or {})}

This means a user can still override durableExecutionArn by passing extra,
consistent with current override behavior.

JavaScript SDK Follow-Up

Apply the same logger metadata policy in the JavaScript SDK:

• Add durableExecutionArn wherever SDK logger metadata currently emits
  executionArn.
• Stop emitting executionArn from SDK logger metadata after the Lambda console
  supports fallback queries.
• Update JavaScript SDK tests and docs to treat durableExecutionArn as the
  canonical field.

Lambda Console Follow-Up

The Lambda console currently uses executionArn to query CloudWatch Logs for a
specific durable execution ARN. To avoid coupling console behavior to the legacy
SDK logger field, update the console-generated query to handle both fields.

Suggested CloudWatch Logs Insights expression:

fields coalesce(durableExecutionArn, executionArn) as durableExecutionArn,
       @timestamp,
       @message,
       operationName,
       operationId
| filter durableExecutionArn = "arn:aws:lambda:..."
| sort @timestamp asc

After all active SDKs emit durableExecutionArn, the console can prefer the
canonical field while retaining the fallback for historical logs.

Python Test Plan

Update tests that assert logger extras:

• packages/aws-durable-execution-sdk-python/tests/logger_test.py
  • Expect durableExecutionArn instead of executionArn.
  • Add or update an override test to confirm user-provided extra can override
    durableExecutionArn.
• packages/aws-durable-execution-sdk-python/tests/e2e/execution_int_test.py
  • Update expected logger metadata for step/context logging.

Recommended focused command:

hatch run test:unit packages/aws-durable-execution-sdk-python/tests/logger_test.py

Recommended broader validation:

hatch run test:unit packages/aws-durable-execution-sdk-python/tests/e2e/execution_int_test.py

Documentation Plan

Update Python, JavaScript, and shared durable execution documentation where
replay-safe logging is described:

• Document durableExecutionArn as the canonical durable execution correlation
  field.
• Mention executionArn may appear in historical Python and JavaScript SDK logs
  and current Lambda console queries.
• Use durableExecutionArn in new examples, queries, and dashboard guidance.
• Include coalesce(durableExecutionArn, executionArn) guidance for mixed
  historical logs.

Example CloudWatch Logs Insights query for new logs:

fields @timestamp, @message, durableExecutionArn, operationName, operationId
| filter durableExecutionArn = "arn:aws:lambda:..."
| sort @timestamp asc

Compatibility query for mixed SDK versions or historical logs:

fields coalesce(durableExecutionArn, executionArn) as durableExecutionArn,
       @timestamp,
       @message,
       operationName,
       operationId
| filter durableExecutionArn = "arn:aws:lambda:..."
| sort @timestamp asc

Risks and Mitigations

Risk	Mitigation
User-owned queries still depend on executionArn	Treat the SDK change as breaking or explicitly called out, and document compatibility queries.
Lambda console still queries only executionArn	Ship console fallback support before the SDK logger rename.
Historical logs contain only executionArn	Keep coalesce(durableExecutionArn, executionArn) guidance in console and docs.
Option 2 would increase log costs if chosen later	Prefer Option 1 to avoid emitting the same ARN twice in every log event.
Cross-language parity has more mismatches	Treat this as the first fix; optionally follow with a separate logger field parity audit.

[ParidelPooya]

Option 3 is the most reasonable option to me.
Also we are following SemVer, if any change is breaking change for Java, simply releast is as next major version.

[zhongkechen]

Option 3 is the most reasonable option to me.

What makes you think it's most reasonable?

Also we are following SemVer, if any change is breaking change for Java, simply releast is as next major version.

same for JS and Python