Registry / aws / aws-xray-sdk-koa2

aws-xray-sdk-koa2

library3.12.0jsnpmunverified

Official AWS X-Ray middleware for Koa 2.x that records incoming/outgoing requests and responses. Version 3.12.0 is latest stable; released with the aws-xray-sdk-node monorepo on a monthly cadence. Key differentiator: deep AWS service integration with automatic segment/subsegment management via cls-hooked. Supports ESM and CJS; ships TypeScript types. Requires aws-xray-sdk-core and Koa 2.x. Offers both automatic (default) and manual tracing modes. Minimal overhead but can cause context issues if middleware order is wrong.

aws observability web-framework http-networking

npm install aws-xray-sdk-koa2

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWS-XRAY-SDK-KOA2

aws-xray-sdk-koa2

awsjavascriptv3.12.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

xrayKoa

✓ import { xrayKoa } from 'aws-xray-sdk-koa2'

✗ const xrayKoa = require('aws-xray-sdk-koa2')

ESM export since v3; CJS also available but use ESM for TypeScript.

openSegment

✓ import { openSegment } from 'aws-xray-sdk-koa2'

✗ const openSegment = require('aws-xray-sdk-koa2').openSegment

Named import is preferred; CJS destructure also works.

AWSXRay

✓ import AWSXRay from 'aws-xray-sdk-core'

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

Core SDK default export; CJS require is common but ESM is encouraged.

Shows ESM imports, middleware setup, and segment retrieval in automatic mode with Koa and @koa/router.

import Koa from 'koa'; import Router from '@koa/router'; import { openSegment } from 'aws-xray-sdk-koa2'; import AWSXRay from 'aws-xray-sdk-core'; const app = new Koa(); const router = new Router(); // Enable AWS X-Ray automatic mode app.use(openSegment('defaultName')); router.get('/', (ctx) => { const segment = AWSXRay.getSegment(); segment?.addAnnotation('myAnnotation', 'value'); ctx.body = 'Hello, X-Ray!'; }); app.use(router.routes()); app.listen(3000);

Debug

Known issues

gotchaopenSegment middleware must be the last middleware before route definitions in automatic mode, otherwise cls-hooked context may be lost.

fix

Place app.use(openSegment(...)) immediately before your router or route middleware.

affects: >=3.0.0

deprecatedVersion 3.7.0 is deprecated; upgrade to latest.

fix

Update to >=3.8.0, preferably 3.12.0.

affects: 3.7.0

breakingCLS context may not work with async/await if not placed correctly; manual mode is safer for complex async flows.

fix

Use manual mode with ctx.segment if you encounter context loss.

affects: >=3.0.0

gotchaSegment must be closed manually in some cases; openSegment automatically closes on response but subsegments need explicit close.

fix

Use AWSXRay.getSegment()?.close() or let the SDK handle it via automatic mode.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'getSegment')

AWSXRay is not imported or core SDK not initialized.

fix

Ensure aws-xray-sdk-core is installed and imported: import AWSXRay from 'aws-xray-sdk-core'.

Error: No segment open, cannot add subsegment

Middleware not applied before route handler, or context lost in async code.

fix

Add app.use(openSegment('name')) before routes; use manual mode if async context is lost.

AssertionError [ERR_ASSERTION]: The 'name' argument must be of type string

openSegment called without a segment name argument.

fix

Provide a name string: app.use(openSegment('myApp')).

Upgrade

Version history

3.12.0latest on npm

Audit

Dependencies

aws-xray-sdk-corerequiredCore SDK for segment creation and AWS service integration

koarequiredKoa 2.x framework required for middleware

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

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

packagehttps://www.npmjs.com/package/aws-xray-sdk-koa2 ↗

homepagehttps://aws.amazon.com/xray/ ↗