{"id":18142,"library":"aws-xray-sdk-koa2","title":"AWS X-Ray SDK for Koa","description":"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.","status":"active","version":"3.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/aws/aws-xray-sdk-node#master","tags":["javascript","amazon","api","aws","koa","xray","x-ray","x ray","typescript"],"install":[{"cmd":"npm install aws-xray-sdk-koa2","lang":"bash","label":"npm"},{"cmd":"yarn add aws-xray-sdk-koa2","lang":"bash","label":"yarn"},{"cmd":"pnpm add aws-xray-sdk-koa2","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core SDK for segment creation and AWS service integration","package":"aws-xray-sdk-core","optional":false},{"reason":"Koa 2.x framework required for middleware","package":"koa","optional":false}],"imports":[{"note":"ESM export since v3; CJS also available but use ESM for TypeScript.","wrong":"const xrayKoa = require('aws-xray-sdk-koa2')","symbol":"xrayKoa","correct":"import { xrayKoa } from 'aws-xray-sdk-koa2'"},{"note":"Named import is preferred; CJS destructure also works.","wrong":"const openSegment = require('aws-xray-sdk-koa2').openSegment","symbol":"openSegment","correct":"import { openSegment } from 'aws-xray-sdk-koa2'"},{"note":"Core SDK default export; CJS require is common but ESM is encouraged.","wrong":"const AWSXRay = require('aws-xray-sdk-core')","symbol":"AWSXRay","correct":"import AWSXRay from 'aws-xray-sdk-core'"}],"quickstart":{"code":"import Koa from 'koa';\nimport Router from '@koa/router';\nimport { openSegment } from 'aws-xray-sdk-koa2';\nimport AWSXRay from 'aws-xray-sdk-core';\n\nconst app = new Koa();\nconst router = new Router();\n\n// Enable AWS X-Ray automatic mode\napp.use(openSegment('defaultName'));\n\nrouter.get('/', (ctx) => {\n  const segment = AWSXRay.getSegment();\n  segment?.addAnnotation('myAnnotation', 'value');\n  ctx.body = 'Hello, X-Ray!';\n});\n\napp.use(router.routes());\napp.listen(3000);","lang":"typescript","description":"Shows ESM imports, middleware setup, and segment retrieval in automatic mode with Koa and @koa/router."},"warnings":[{"fix":"Place app.use(openSegment(...)) immediately before your router or route middleware.","message":"openSegment middleware must be the last middleware before route definitions in automatic mode, otherwise cls-hooked context may be lost.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Update to >=3.8.0, preferably 3.12.0.","message":"Version 3.7.0 is deprecated; upgrade to latest.","severity":"deprecated","affected_versions":"3.7.0"},{"fix":"Use manual mode with ctx.segment if you encounter context loss.","message":"CLS context may not work with async/await if not placed correctly; manual mode is safer for complex async flows.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use AWSXRay.getSegment()?.close() or let the SDK handle it via automatic mode.","message":"Segment must be closed manually in some cases; openSegment automatically closes on response but subsegments need explicit close.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure aws-xray-sdk-core is installed and imported: import AWSXRay from 'aws-xray-sdk-core'.","cause":"AWSXRay is not imported or core SDK not initialized.","error":"TypeError: Cannot read properties of undefined (reading 'getSegment')"},{"fix":"Add app.use(openSegment('name')) before routes; use manual mode if async context is lost.","cause":"Middleware not applied before route handler, or context lost in async code.","error":"Error: No segment open, cannot add subsegment"},{"fix":"Provide a name string: app.use(openSegment('myApp')).","cause":"openSegment called without a segment name argument.","error":"AssertionError [ERR_ASSERTION]: The 'name' argument must be of type string"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}