Serverless Integrations

Serverless Integrations

Use this skill for platform-boundary instrumentation where dd-trace-js owns the function invocation lifecycle.

Use apm-integrations instead for ordinary library instrumentation that runs inside a serverless function.

Decision Gate

Classify the request before touching code:

| Request shape | Skill path | Span model |

| --- | --- | --- |

| Trace a third-party library call inside Lambda/Azure/GCP | apm-integrations | Child spans under the invocation |

| Trace the cloud function invocation itself | This skill | Root type = 'serverless' span |

| Trace an HTTP, queue, or event trigger | This skill plus trigger references | Root span plus context or links |

| Change AWS Lambda bootstrap or timeout behavior | This skill | Special-case runtime wrapper path |

Do not model ordinary library plugins after the Lambda bootstrap. Lambda is a compatibility/runtime wrapper path,

not the default architecture for new integrations.

Core Invariants

• Serverless platform integrations represent the invocation as the primary unit of work.
• Root plugins set static kind = 'server' and static type = 'serverless'.
• Use TracingPlugin unless a more specific local pattern clearly applies. Do not default to ServerPlugin just

because the span kind is server.

• The integration owns every completion path: success, thrown error, rejected promise, callback completion,

timeout, and runtime shutdown when the platform exposes it.

• Flush behavior must be designed around the platform freezing or terminating the process.
• Context extraction happens at the platform boundary: HTTP headers, event/message attributes, client context, or

batch span links.

• Preserve diagnostic-channel subscriber behavior. AppSec, IAST, telemetry, and other subscribers may depend on

published events even when the tracing plugin is disabled.

• Prefer Orchestrion for static module hooks. Use shimmer/runtime wrapping only when the platform's handler model

requires dynamic interception, and document why.

Workflow

• Read references/architecture.md to confirm whether the work is serverless-root or ordinary APM.
• Read references/reference-integrations.md and inspect at least one matching in-repo implementation.
• For implementation work, follow references/implementation-guide.md.
• For tests and deployed verification, follow references/testing-guide.md.

Implementation Checklist

• Add or update instrumentation in packages/datadog-instrumentations/ when the runtime can be observed through

normal hooks.

• Add or update the plugin under packages/datadog-plugin-<name>/ when spans are created from diagnostic-channel

events.

• Register the plugin in packages/dd-trace/src/plugins/index.js.
• Add service naming behavior under packages/dd-trace/src/service-naming/schemas/*/serverless.js.
• Add docs, TypeScript config surface, and supported-integration metadata only when the user-facing configuration

surface changes.

• For HTTP-triggered functions, reuse web helpers such as web.patch, web.startServerlessSpanWithInferredProxy,

and web.finishAll when they match the trigger model.

• For batch/message triggers, extract upstream context per item when possible and use span links for multiple

upstream contexts.

Review Checklist

• The invocation span starts before user handler execution and finishes exactly once.
• Errors are tagged on the invocation span without crashing the user app.
• Async, promise, callback, and synchronous handlers are all covered when the runtime supports them.
• Timeout or near-shutdown behavior finishes or flushes trace data before the platform freezes execution.
• Disabled instrumentation still leaves unrelated integrations intact.
• Deployed/manual verification instructions confirm traces in Datadog, not only local unit behavior.