Registry / devops / aws-xray-sdk-fetch

aws-xray-sdk-fetch

library3.12.0jsnpmunverified

Plugin for AWS X-Ray SDK that instruments fetch (global fetch in Node.js 18+, or node-fetch v2). Current version 3.12.0 requires aws-xray-sdk-core as a peer dependency. Provides captureFetchGlobal and captureFetchModule functions. Key differentiator: enables distributed tracing for HTTP requests made with fetch, with support for downstream X-Ray headers. Ships TypeScript types. CJS-only, incompatible with node-fetch v3 (ESM).

devops

npm install aws-xray-sdk-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWS-XRAY-SDK-FETCH

aws-xray-sdk-fetch

devopsjavascriptv3.12.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

captureFetchGlobal

✓ const { captureFetchGlobal } = require('aws-xray-sdk-fetch');

✗ import { captureFetchGlobal } from 'aws-xray-sdk-fetch';

Package is CJS-only; ESM imports cause runtime error.

captureFetchModule

✓ const { captureFetchModule } = require('aws-xray-sdk-fetch');

✗ import captureFetchModule from 'aws-xray-sdk-fetch';

CJS-only export; also the first argument to captureFetchModule must be the node-fetch module, not a reference to fetch function.

types

✓ import type { CaptureFetchGlobal, CaptureFetchModule } from 'aws-xray-sdk-fetch';

✗ import { CaptureFetchGlobal } from 'aws-xray-sdk-fetch';

Use type-only imports for TypeScript types to avoid runtime side effects.

AWSXRay

✓ const AWSXRay = require('aws-xray-sdk-core');

✗ const AWSXRay = require('aws-xray-sdk-fetch');

The core SDK is a separate package; fetch plugin only provides capture functions.

Shows how to initialize AWSXRay with manual mode and instrument global fetch using captureFetchGlobal.

const AWSXRay = require('aws-xray-sdk-core'); const { captureFetchGlobal } = require('aws-xray-sdk-fetch'); // Enable AWSXRay (e.g., with manual mode) AWSXRay.enableManualMode(); // Use global fetch (Node.js 18+) const fetch = captureFetchGlobal(); async function makeRequest() { const result = await fetch('https://api.example.com/data'); const data = await result.json(); console.log(data); } makeRequest();

Debug

Known issues

breakingCannot use ESM import syntax; package is CommonJS only.

fix

Use require() for import.

affects: >=3.0.0

breakingNode.js 18+ required for global fetch support; earlier versions must use node-fetch v2.

fix

Use captureFetchModule with node-fetch v2 or upgrade Node.js to >=18.

affects: >=3.10.0

breakingIncompatible with node-fetch v3 (ESM-only).

fix

Use node-fetch v2 (e.g., 'npm install node-fetch@2').

affects: >=3.0.0

gotchacaptureFetchModule expects the node-fetch module as first argument, not a fetch function.

fix

Pass require('node-fetch') directly, not just the fetch function.

affects: >=3.0.0

gotchaSubsegment callback can cause memory leaks if not properly handled.

fix

Ensure callbacks do not hold references to large objects beyond segment lifecycle.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: fetch is not a function

captureFetchGlobal() returns undefined if global fetch is not available (Node <18).

fix

Use captureFetchModule with node-fetch v2 instead, or upgrade Node.

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Trying to require node-fetch v3 which is ESM-only.

fix

Install node-fetch v2: npm install node-fetch@2

Cannot find module 'aws-xray-sdk-core'

Missing peer dependency aws-xray-sdk-core.

fix

Install it: npm install aws-xray-sdk-core

TypeError: segment is not a segment

AWSXRay not properly initialized before calling captureFetchGlobal/Module.

fix

Ensure AWSXRay.enableManualMode() or other initialization is called first.

SyntaxError: Cannot use import statement outside a module

Using ESM import syntax in a CommonJS file.

fix

Switch to require() or use .mjs extension with ESM imports (but package is CJS-only).

Upgrade

Version history

3.12.0latest on npm

Audit

Dependencies

aws-xray-sdk-corerequiredpeer dependency; provides core segment/subsegment creation and context management

node-fetchoptionaloptional; required only when using captureFetchModule with node-fetch v2

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/aws/aws-xray-sdk-node#master ↗

packageaws-xray-sdk-fetch ↗

homepagehttps://github.com/aws/aws-xray-sdk-node/tree/master#readme ↗