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.
1---2name: serverless-integrations3description: Use when adding, modifying, debugging, or reviewing dd-trace-js serverless platform integrations that create root invocation spans for AWS Lambda, Azure Functions, Google Cloud Functions, or similar runtimes. Triggers: serverless integration, function invocation root span, Lambda runtime, Azure Functions, GCP Functions, type = 'serverless', DD_LAMBDA_HANDLER, datadog-lambda-js, deployed serverless verification, manual serverless test.4---56# Serverless Integrations78Use this skill for platform-boundary instrumentation where dd-trace-js owns the function invocation lifecycle.9Use `apm-integrations` instead for ordinary library instrumentation that runs inside a serverless function.1011## Decision Gate1213Classify the request before touching code:1415| Request shape | Skill path | Span model |16| --- | --- | --- |17| Trace a third-party library call inside Lambda/Azure/GCP | `apm-integrations` | Child spans under the invocation |18| Trace the cloud function invocation itself | This skill | Root `type = 'serverless'` span |19| Trace an HTTP, queue, or event trigger | This skill plus trigger references | Root span plus context or links |20| Change AWS Lambda bootstrap or timeout behavior | This skill | Special-case runtime wrapper path |2122Do not model ordinary library plugins after the Lambda bootstrap. Lambda is a compatibility/runtime wrapper path,23not the default architecture for new integrations.2425## Core Invariants2627- Serverless platform integrations represent the invocation as the primary unit of work.28- Root plugins set `static kind = 'server'` and `static type = 'serverless'`.29- Use `TracingPlugin` unless a more specific local pattern clearly applies. Do not default to `ServerPlugin` just30 because the span kind is server.31- The integration owns every completion path: success, thrown error, rejected promise, callback completion,32 timeout, and runtime shutdown when the platform exposes it.33- Flush behavior must be designed around the platform freezing or terminating the process.34- Context extraction happens at the platform boundary: HTTP headers, event/message attributes, client context, or35 batch span links.36- Preserve diagnostic-channel subscriber behavior. AppSec, IAST, telemetry, and other subscribers may depend on37 published events even when the tracing plugin is disabled.38- Prefer Orchestrion for static module hooks. Use shimmer/runtime wrapping only when the platform's handler model39 requires dynamic interception, and document why.4041## Workflow42431. Read `references/architecture.md` to confirm whether the work is serverless-root or ordinary APM.442. Read `references/reference-integrations.md` and inspect at least one matching in-repo implementation.453. For implementation work, follow `references/implementation-guide.md`.464. For tests and deployed verification, follow `references/testing-guide.md`.4748## Implementation Checklist4950- Add or update instrumentation in `packages/datadog-instrumentations/` when the runtime can be observed through51 normal hooks.52- Add or update the plugin under `packages/datadog-plugin-<name>/` when spans are created from diagnostic-channel53 events.54- Register the plugin in `packages/dd-trace/src/plugins/index.js`.55- Add service naming behavior under `packages/dd-trace/src/service-naming/schemas/*/serverless.js`.56- Add docs, TypeScript config surface, and supported-integration metadata only when the user-facing configuration57 surface changes.58- For HTTP-triggered functions, reuse web helpers such as `web.patch`, `web.startServerlessSpanWithInferredProxy`,59 and `web.finishAll` when they match the trigger model.60- For batch/message triggers, extract upstream context per item when possible and use span links for multiple61 upstream contexts.6263## Review Checklist6465- The invocation span starts before user handler execution and finishes exactly once.66- Errors are tagged on the invocation span without crashing the user app.67- Async, promise, callback, and synchronous handlers are all covered when the runtime supports them.68- Timeout or near-shutdown behavior finishes or flushes trace data before the platform freezes execution.69- Disabled instrumentation still leaves unrelated integrations intact.70- Deployed/manual verification instructions confirm traces in Datadog, not only local unit behavior.
datadog