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.

serverless-integrations