Skip to content

New Integration. aws-durable-execution-sdk-js.#8012

Draft
joeyzhao2018 wants to merge 23 commits intomasterfrom
joey/apm-ai-toolkit/aws-durable-execution-sdk-js
Draft

New Integration. aws-durable-execution-sdk-js.#8012
joeyzhao2018 wants to merge 23 commits intomasterfrom
joey/apm-ai-toolkit/aws-durable-execution-sdk-js

Conversation

@joeyzhao2018
Copy link
Copy Markdown
Contributor

@joeyzhao2018 joeyzhao2018 commented Apr 15, 2026

Note: This PR is based on this apm-ai-toolkit generated PR

Summary

Adds automatic instrumentation for the @aws/durable-execution-sdk-js library, tracing durable workflow executions and all
DurableContextImpl operations. Naming conventions are aligned with the Python (dd-trace-py) counterpart.

Traced Operations

The plugin is a CompositePlugin with server, client, and internal sub-plugins, communicating via diagnostics_channel prefixes set by the
orchestrion rewriter:

Target Span Name Kind Plugin
withDurableExecution aws.durable_execution.execute server ServerPlugin
DurableContextImpl.invoke() aws.durable_execution.invoke client ClientPlugin
DurableContextImpl.step() aws.durable_execution.step internal BaseInternalPlugin
DurableContextImpl.wait() aws.durable_execution.wait internal subclass
DurableContextImpl.waitForCondition() aws.durable_execution.wait_for_condition internal subclass
DurableContextImpl.waitForCallback() aws.durable_execution.wait_for_callback internal subclass
DurableContextImpl.createCallback() aws.durable_execution.create_callback internal subclass
DurableContextImpl.map() aws.durable_execution.map internal subclass
DurableContextImpl.parallel() aws.durable_execution.parallel internal subclass
DurableContextImpl.runInChildContext() aws.durable_execution.child_context internal subclass

Key Features

Resource Name Extraction

All plugins extract a human-readable resource name from ctx.arguments:

  • Server: Fixed resource aws.durable_execution.execute
  • Internal operations: args[0] if it's a string (the optional name parameter), falling back to the span name
  • Invoke: Two overloads — invoke(name, funcId, ...) vs invoke(funcId, ...). If both args[0] and args[1] are strings, args[0] is the
    operation name (used as resource) and args[1] is the function identifier. Otherwise args[0] is the function identifier.

Peer Service Support

The client plugin (invoke) sets functionname as a tag and declares it as a peerServicePrecursor. When spanComputePeerService is enabled,
peer.service is derived from the target function ARN/name, giving downstream dependency visibility in APM.

Service Name

Default service: aws.durable_execution. Overridable via DD_DURABLE_EXECUTION_SERVICE environment variable (shared with the Python
integration).

Span Lifecycle

All plugins implement both asyncEnd and end to call finish(), ensuring the span is closed regardless of how the tracingChannel fires (sync
vs async completion).

Internal Plugin Architecture

internal.js uses a base class (BaseAwsDurableExecutionSdkJsInternalPlugin) with shared bindStart, getOperationName, getTags, and lifecycle
methods. The 7 operation-specific subclasses only override static prefix (diagnostics channel) and static spanName. This keeps the code DRY
while allowing each operation to be independently subscribed to its own channel.

Plugin Structure

packages/datadog-plugin-aws-durable-execution-sdk-js/
├── src/
│ ├── index.js # CompositePlugin registering server + client + internal plugins
│ ├── server.js # withDurableExecution (server span)
│ ├── client.js # DurableContextImpl.invoke (client span, peer service)
│ └── internal.js # Base class + 7 subclasses for all other operations
└── test/
├── test-setup.js # Mock clients, event builders, operation invokers
└── index.spec.js # Integration tests via createIntegrationTestSuite

Test Coverage

Tests use createIntegrationTestSuite with a mock agent. Each operation has happy-path and error-path tests:

  • Happy path: Verifies span name, service, resource, component tag, and span.kind
  • Error path: Verifies span is still created and (where applicable) error tags are set (error.type, error.message, error: 1)
  • Peer service: Verifies functionname, operationname, peer.service, and _dd.peer.service.source on invoke spans when spanComputePeerService
    is enabled

Test Plan

  • All 10 operations produce spans with correct name, service, resource, and tags
  • Error paths produce spans with appropriate error metadata
  • Invoke peer service correctly derived from functionname
  • Invoke resource correctly resolves from operation name overload

Tests in datadog-plugin-aws-durable-execution-sdk-js/test

  1. Set up. test-setup.js
    No Lambda required. These tests run entirely in-process with mocks.
    The TestSetup class creates a fully mocked SDK environment:
    • MockDurableExecutionClient / ImmediateCompletionMockClient — In-memory mock clients that replace the real AWS checkpoint service. They return fake checkpoint responses with SUCCEEDED (or FAILED) status so durable operations resolve immediately without any network calls.
    • createMockLambdaContext() — Fake Lambda context object with hardcoded ARNs, function name, and a timer.
    • createMockEvent() — Creates a DurableExecutionInvocationInputWithClient with the mock client injected, simulating what the SDK would receive in a real Lambda invocation.
    • _invokeHandler() — Calls withDurableExecution(handlerFn) and invokes the returned handler with the mock event/context. This exercises the real SDK code paths (step, invoke, map, etc.) but with the checkpoint backend mocked out.
  2. Span Assertions. test/index.spec.js
    Uses createIntegrationTestSuite which starts dd-trace with a local test agent (not a real Datadog backend). For each DurableContext operation it tests
    1. Happy path — calls the operation, asserts a span with the correct name, service, meta.component, and meta['span.kind']
    2. Error path — triggers a failure, asserts error tags (error: 1, error.type, error.message)
  3. Covered operations:
    withDurableExecution (workflow.execute), step, invoke, runInChildContext, wait, waitForCondition, waitForCallback, createCallback, map, parallel — plus a peer.service test for invoke.

@joeyzhao2018 joeyzhao2018 changed the title Joey/apm ai toolkit/aws durable execution sdk js New Integration. aws-durable-execution-sdk-js. Apr 15, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 15, 2026

Overall package size

Self size: 5.51 MB
Deduped: 6.35 MB
No deduping: 6.35 MB

Dependency sizes | name | version | self size | total size | |------|---------|-----------|------------| | import-in-the-middle | 3.0.1 | 82.56 kB | 817.39 kB | | dc-polyfill | 0.1.10 | 26.73 kB | 26.73 kB |

🤖 This report was automatically generated by heaviest-objects-in-the-universe

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: ./.github/actions/plugins/test-and-upstream

aws-durable-execution-sdk-js:
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@codecov
Copy link
Copy Markdown

codecov bot commented Apr 15, 2026

Codecov Report

❌ Patch coverage is 46.15385% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.59%. Comparing base (3e74642) to head (6222c9b).

Files with missing lines Patch % Lines
...-trace/src/service-naming/schemas/v0/serverless.js 0.00% 3 Missing ⚠️
...-trace/src/service-naming/schemas/v1/serverless.js 0.00% 3 Missing ⚠️
packages/dd-trace/src/plugins/index.js 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #8012      +/-   ##
==========================================
- Coverage   73.59%   68.59%   -5.01%     
==========================================
  Files         773      682      -91     
  Lines       36088    31349    -4739     
==========================================
- Hits        26560    21503    -5057     
- Misses       9528     9846     +318     
Flag Coverage Δ
aiguard-macos 36.53% <37.50%> (-0.09%) ⬇️
aiguard-ubuntu 36.64% <37.50%> (-0.09%) ⬇️
aiguard-windows 36.44% <37.50%> (-0.09%) ⬇️
apm-capabilities-tracing-macos ?
apm-capabilities-tracing-ubuntu ?
apm-capabilities-tracing-windows ?
apm-integrations-child-process 36.16% <37.50%> (-0.09%) ⬇️
apm-integrations-couchbase-18 35.14% <27.27%> (-0.10%) ⬇️
apm-integrations-couchbase-eol 35.22% <27.27%> (-0.07%) ⬇️
apm-integrations-oracledb 35.19% <27.27%> (-0.10%) ⬇️
appsec-express 52.90% <37.50%> (-0.06%) ⬇️
appsec-fastify 49.37% <37.50%> (-0.08%) ⬇️
appsec-graphql 49.63% <37.50%> (-0.07%) ⬇️
appsec-kafka 42.16% <37.50%> (-0.08%) ⬇️
appsec-ldapjs 41.48% <37.50%> (-0.08%) ⬇️
appsec-lodash 41.51% <37.50%> (-0.08%) ⬇️
appsec-macos 56.81% <37.50%> (-0.07%) ⬇️
appsec-mongodb-core 46.14% <37.50%> (-0.09%) ⬇️
appsec-mongoose 46.70% <37.50%> (-0.08%) ⬇️
appsec-mysql 48.85% <37.50%> (-0.08%) ⬇️
appsec-node-serialize 40.68% <37.50%> (-0.08%) ⬇️
appsec-passport 44.67% <37.50%> (-0.09%) ⬇️
appsec-postgres 48.53% <37.50%> (+0.02%) ⬆️
appsec-sourcing 40.17% <37.50%> (-0.08%) ⬇️
appsec-stripe 42.52% <37.50%> (+0.03%) ⬆️
appsec-template 40.85% <37.50%> (-0.08%) ⬇️
appsec-ubuntu 56.89% <37.50%> (-0.08%) ⬇️
appsec-windows 56.70% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-bluebird 29.86% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-body-parser 37.76% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-child_process 35.54% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-cookie-parser 31.78% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-express 32.00% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-express-mongo-sanitize 31.90% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-express-session 37.39% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-fs 29.52% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-generic-pool 31.01% <42.85%> (+0.01%) ⬆️
instrumentations-instrumentation-http 36.99% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-knex 29.83% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-mongoose 30.93% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-multer 37.53% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-mysql2 35.51% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-passport 41.26% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-passport-http 40.96% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-passport-local 41.46% <37.50%> (-0.08%) ⬇️
instrumentations-instrumentation-pg 35.03% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-promise 29.79% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-promise-js 29.80% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-q 29.83% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-url 29.79% <37.50%> (-0.09%) ⬇️
instrumentations-instrumentation-when 29.81% <37.50%> (-0.09%) ⬇️
llmobs-ai 38.47% <37.50%> (-0.09%) ⬇️
llmobs-anthropic 37.92% <37.50%> (-0.09%) ⬇️
llmobs-bedrock 37.17% <37.50%> (-0.08%) ⬇️
llmobs-google-genai 37.61% <37.50%> (-0.08%) ⬇️
llmobs-langchain 37.15% <37.50%> (+0.03%) ⬆️
llmobs-openai 41.29% <37.50%> (-0.09%) ⬇️
llmobs-vertex-ai 37.78% <37.50%> (-0.09%) ⬇️
platform-core 29.85% <0.00%> (-0.17%) ⬇️
platform-esbuild 32.67% <0.00%> (-0.17%) ⬇️
platform-instrumentations-misc 40.29% <50.00%> (+0.04%) ⬆️
platform-shimmer 35.56% <0.00%> (-0.18%) ⬇️
platform-unit-guardrails 31.22% <0.00%> (-0.17%) ⬇️
platform-webpack 20.85% <60.00%> (+0.02%) ⬆️
plugins-azure-durable-functions 25.43% <50.00%> (+0.21%) ⬆️
plugins-azure-event-hubs 25.58% <50.00%> (+0.21%) ⬆️
plugins-azure-service-bus 25.00% <50.00%> (+0.21%) ⬆️
plugins-bullmq 40.80% <37.50%> (-0.10%) ⬇️
plugins-cassandra 35.33% <27.27%> (-0.10%) ⬇️
plugins-cookie 26.54% <50.00%> (+0.20%) ⬆️
plugins-cookie-parser 26.35% <50.00%> (+0.20%) ⬆️
plugins-crypto 25.51% <0.00%> (-0.15%) ⬇️
plugins-dd-trace-api 35.48% <37.50%> (-0.09%) ⬇️
plugins-express-mongo-sanitize 26.49% <50.00%> (+0.20%) ⬆️
plugins-express-session 26.31% <50.00%> (+0.20%) ⬆️
plugins-fastify 39.44% <37.50%> (-0.09%) ⬇️
plugins-fetch 35.84% <27.27%> (-0.10%) ⬇️
plugins-fs 35.76% <37.50%> (-0.09%) ⬇️
plugins-generic-pool 25.47% <50.00%> (+0.21%) ⬆️
plugins-google-cloud-pubsub 43.10% <27.27%> (-0.10%) ⬇️
plugins-grpc 38.11% <27.27%> (-0.10%) ⬇️
plugins-handlebars 26.53% <50.00%> (+0.20%) ⬆️
plugins-hapi 37.49% <37.50%> (+0.04%) ⬆️
plugins-hono 37.60% <37.50%> (-0.09%) ⬇️
plugins-ioredis 35.79% <27.27%> (-0.10%) ⬇️
plugins-knex 26.21% <50.00%> (+0.19%) ⬆️
plugins-langgraph 35.15% <37.50%> (-0.09%) ⬇️
plugins-ldapjs 24.09% <50.00%> (+0.21%) ⬆️
plugins-light-my-request 25.95% <50.00%> (+0.20%) ⬆️
plugins-limitd-client 30.07% <37.50%> (-0.09%) ⬇️
plugins-lodash 25.55% <50.00%> (+0.21%) ⬆️
plugins-mariadb 36.71% <27.27%> (-0.10%) ⬇️
plugins-memcached 35.44% <27.27%> (-0.10%) ⬇️
plugins-microgateway-core 36.44% <37.50%> (-0.09%) ⬇️
plugins-moleculer 38.14% <27.27%> (-0.10%) ⬇️
plugins-mongodb 36.53% <27.27%> (-0.10%) ⬇️
plugins-mongodb-core 36.25% <27.27%> (-0.10%) ⬇️
plugins-mongoose 36.13% <37.50%> (-0.09%) ⬇️
plugins-multer 26.31% <50.00%> (+0.20%) ⬆️
plugins-mysql 36.53% <27.27%> (-0.10%) ⬇️
plugins-mysql2 36.51% <27.27%> (-0.10%) ⬇️
plugins-node-serialize 26.58% <50.00%> (+0.20%) ⬆️
plugins-opensearch 35.09% <27.27%> (-0.10%) ⬇️
plugins-passport-http 26.36% <50.00%> (+0.20%) ⬆️
plugins-postgres 34.48% <27.27%> (-0.09%) ⬇️
plugins-process 25.51% <0.00%> (-0.15%) ⬇️
plugins-pug 26.54% <50.00%> (+0.20%) ⬆️
plugins-redis 35.99% <27.27%> (-0.10%) ⬇️
plugins-router 40.01% <37.50%> (-0.09%) ⬇️
plugins-sequelize 25.25% <50.00%> (+0.21%) ⬆️
plugins-test-and-upstream-amqp10 35.76% <27.27%> (-0.10%) ⬇️
plugins-test-and-upstream-amqplib 40.95% <27.27%> (-0.11%) ⬇️
plugins-test-and-upstream-apollo 36.61% <27.27%> (-0.09%) ⬇️
plugins-test-and-upstream-avsc 35.62% <37.50%> (-0.09%) ⬇️
plugins-test-and-upstream-bunyan 31.22% <37.50%> (-0.09%) ⬇️
plugins-test-and-upstream-connect 37.95% <37.50%> (-0.09%) ⬇️
plugins-test-and-upstream-graphql 37.29% <27.27%> (-0.10%) ⬇️
plugins-test-and-upstream-koa 37.56% <37.50%> (-0.09%) ⬇️
plugins-test-and-upstream-protobufjs 35.83% <37.50%> (-0.09%) ⬇️
plugins-test-and-upstream-rhea 41.03% <27.27%> (-0.11%) ⬇️
plugins-undici 36.62% <27.27%> (-0.09%) ⬇️
plugins-url 25.51% <0.00%> (-0.15%) ⬇️
plugins-valkey 35.35% <27.27%> (-0.10%) ⬇️
plugins-vm 25.51% <0.00%> (-0.15%) ⬇️
plugins-winston 31.66% <37.50%> (-0.09%) ⬇️
plugins-ws 39.07% <37.50%> (-0.09%) ⬇️
profiling-macos 38.03% <37.50%> (-0.09%) ⬇️
profiling-ubuntu 38.19% <37.50%> (-0.09%) ⬇️
profiling-windows 39.55% <37.50%> (-0.09%) ⬇️
serverless-azure-functions-client 25.32% <50.00%> (+0.21%) ⬆️
serverless-azure-functions-eventhubs 25.32% <50.00%> (+0.21%) ⬆️
serverless-azure-functions-servicebus 25.32% <50.00%> (+0.21%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@datadog-datadog-prod-us1-2
Copy link
Copy Markdown

datadog-datadog-prod-us1-2 bot commented Apr 15, 2026

Tests

Fix all issues with BitsAI or with Cursor

⚠️ Other Violations

🧪 1 Test failed

should stay in sync with supported-configurations.json from Mocha Tests   View in Datadog   (Fix with Cursor)
Expected values to be strictly equal:
+ actual - expected
... Skipped lines

  '// This file is generated from packages/dd-trace/src/config/supported-configurations.json\n' +
    '// by scripts/generate-config-types.js. Do not edit this file directly.\n' +
    '\n' +
    'export interface GeneratedConfig {\n' +
    '  _DD_APM_TRACING_AGENTLESS_ENABLED: boolean;\n' +
...
...

ℹ️ Info

No other issues found (see more)

❄️ No new flaky tests detected

🎯 Code Coverage (details)
Patch Coverage: 46.15%
Overall Coverage: 61.74% (-6.27%)

This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 6222c9b | Docs | Datadog PR Page | Was this helpful? React with 👍/👎 or give us feedback!

@pr-commenter
Copy link
Copy Markdown

pr-commenter bot commented Apr 15, 2026

Benchmarks

Benchmark execution time: 2026-04-17 14:59:15

Comparing candidate commit 6222c9b in PR branch joey/apm-ai-toolkit/aws-durable-execution-sdk-js with baseline commit 3e74642 in branch master.

Found 0 performance improvements and 1 performance regressions! Performance is the same for 1374 metrics, 109 unstable metrics.

scenario:spans-finish-immediately-20

  • 🟥 max_rss_usage [+4.931MB; +5.991MB] or [+6.816%; +8.281%]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant