The `aws-xray-sdk-core` package provides foundational capabilities for instrumenting Node.js applications to integrate with AWS X-Ray, enabling distributed tracing, performance analysis, and service map visualization. Currently at version 3.12.0, the SDK receives regular updates, typically on a monthly or bi-monthly release cadence, focusing on stability, bug fixes, and maintaining compatibility with AWS services. It supports both automatic and manual instrumentation modes; automatic mode, leveraging `cls-hooked` for asynchronous context propagation, is ideal for web frameworks like Express and Restify, as well as AWS Lambda functions, by automatically managing trace segments. Manual mode offers granular control over segment and subsegment creation for custom instrumentation scenarios. Its key differentiators include native integration with AWS services and robust support for Node.js environments.
npm install aws-xray-sdk-coreVerified import paths — ran on the pinned version, not inferred.
Demonstrates basic setup of `aws-xray-sdk-core` in automatic mode, capturing an incoming HTTP request, adding annotations and metadata, and creating a custom subsegment for an asynchronous operation.
Upgrade your Node.js runtime to version 14.x or higher. If you need to support older Node.js versions, consider using a previous major version of the AWS X-Ray SDK for Node.js.
Ensure all asynchronous operations are wrapped with SDK provided functions like `AWSXRay.captureAsyncFunc`, `AWSXRay.capturePromise`, or are part of an automatically captured middleware context (e.g., Express middleware). Confirm `cls-hooked` is correctly installed.
Add `aws-sdk` to your project's dependencies: `npm install aws-sdk` or `yarn add aws-sdk`. This is separate from `@aws-sdk/client-*` packages for AWS SDK v3.
Consider setting `AWSXRay.setContextMissingStrategy('RUNTIME_ERROR')` or `process.env.AWS_XRAY_CONTEXT_MISSING = 'RUNTIME_ERROR'` during development to make missing trace contexts explicit and prevent silently untraced operations.Verify that `AWSXRay.enableAutomaticMode()` is called early in your application's lifecycle. Ensure the code executing is within a traced context (e.g., an incoming HTTP request handled by X-Ray middleware, or inside `captureAsyncFunc`). All async operations must properly propagate context for automatic mode to work reliably.
Install the `cls-hooked` dependency: `npm install cls-hooked` or `yarn add cls-hooked`. Although it's a direct dependency, issues can arise from aggressive dependency pruning or package manager inconsistencies.
Ensure the X-Ray daemon is running and listening on the expected UDP port. Check the `AWS_XRAY_DAEMON_ADDRESS` environment variable or `AWSXRay.setDaemonAddress()` configuration if you've customized it. Verify local firewall rules are not blocking traffic to the daemon.
Inspect the incoming `X-Amzn-Trace-Id` header to ensure it conforms to the X-Ray trace header specification (`Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1`). This often indicates an issue upstream in the trace propagation chain.