{"id":13818167,"url":"https://github.com/narando/nest-xray","last_synced_at":"2026-02-15T00:02:35.182Z","repository":{"id":36946159,"uuid":"232841816","full_name":"narando/nest-xray","owner":"narando","description":"Distributed tracing for Nestjs with AWS X-Ray as the backend. Instrument incoming and outgoing HTTP requests","archived":false,"fork":false,"pushed_at":"2026-02-12T14:38:00.000Z","size":2097,"stargazers_count":66,"open_issues_count":25,"forks_count":22,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-12T23:08:47.609Z","etag":null,"topics":["aws-xray","nest","nestjs","nodejs","tracing","typescript","xray"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@narando/nest-xray","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/narando.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-01-09T15:35:58.000Z","updated_at":"2025-12-10T18:08:25.000Z","dependencies_parsed_at":"2023-09-23T07:29:30.194Z","dependency_job_id":"d9c63db9-4840-4385-b7da-787f227bbda7","html_url":"https://github.com/narando/nest-xray","commit_stats":{"total_commits":442,"total_committers":12,"mean_commits":"36.833333333333336","dds":"0.31221719457013575","last_synced_commit":"fea748fd1fada39b0e7c92306bc3b5b1895fd8a8"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/narando/nest-xray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narando%2Fnest-xray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narando%2Fnest-xray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narando%2Fnest-xray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narando%2Fnest-xray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/narando","download_url":"https://codeload.github.com/narando/nest-xray/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/narando%2Fnest-xray/sbom","scorecard":{"id":674474,"data":{"date":"2025-08-11","repo":{"name":"github.com/narando/nest-xray","commit":"2f10d0857b1a024c39326fa85119d90e28a6073e"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.6,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yaml:1","Warn: no topLevel permission defined: .github/workflows/release.yaml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Pinned-Dependencies","score":2,"reason":"dependency not pinned by hash detected -- score normalized to 2","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yaml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/narando/nest-xray/ci.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yaml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/narando/nest-xray/ci.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yaml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/narando/nest-xray/ci.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yaml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/narando/nest-xray/ci.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yaml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/narando/nest-xray/release.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yaml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/narando/nest-xray/release.yaml/master?enable=pin","Warn: npmCommand not pinned by hash: .github/workflows/release.yaml:23","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   2 out of   3 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"31 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-cj7v-w2c7-cp7c","Warn: Project is vulnerable to: GHSA-wf5p-g6vw-rhxx","Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6","Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x","Warn: Project is vulnerable to: GHSA-h452-7996-h45h","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c","Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc","Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx","Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc","Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3","Warn: Project is vulnerable to: GHSA-44fp-w29j-9vj5","Warn: Project is vulnerable to: GHSA-4pg4-qvpc-4q3h","Warn: Project is vulnerable to: GHSA-g5hg-p3ph-g8qg","Warn: Project is vulnerable to: GHSA-fjgf-rc76-4x9p","Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg","Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-4vvj-4cpr-p986"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-21T21:05:12.440Z","repository_id":36946159,"created_at":"2025-08-21T21:05:12.440Z","updated_at":"2025-08-21T21:05:12.440Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29461367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T22:42:09.113Z","status":"ssl_error","status_checked_at":"2026-02-14T22:42:05.053Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-xray","nest","nestjs","nodejs","tracing","typescript","xray"],"created_at":"2024-08-04T07:00:34.744Z","updated_at":"2026-02-15T00:02:35.159Z","avatar_url":"https://github.com/narando.png","language":"TypeScript","funding_links":[],"categories":["Components \u0026 Libraries"],"sub_categories":[],"readme":"# @narando/nest-xray\n\nThis module implements [Distributed Tracing](https://opentracing.io/docs/overview/what-is-tracing/) with [AWS X-Ray](https://aws.amazon.com/xray/) for Nest.js services.\n\n## Features\n\n- Supported Environments\n  - HTTP (express.js)\n- Clients\n  - `HttpService`/`HttpModule`\n- Manually create new Subsegments to trace custom functions\n\n## Usage\n\n\u003e ⚠️ If you want to use `@narando/nest-xray` with NestJS Version 6 or 7,\n\u003e please use the v1 release.\n\u003e\n\u003e The v2 release is only compatible with NestJS Version 8 or 9 and @nestjs/axios `\u003e=0.0.5 \u003c=0.1.0`.\n\n### Installation\n\nInstall this module and `aws-xray-sdk`:\n\n```shell\n$ npm i @narando/nest-xray aws-xray-sdk\n```\n\n### Initialization\n\nRegister the `TracingModule` with your app module:\n\n```typescript\nimport { TracingModule } from \"@narando/nest-xray\";\n\n@Module({\n  imports: [TracingModule.forRoot({ serviceName: \"your-service-name\" })],\n})\nexport class AppModule {}\n```\n\n### Environments\n\nAn _environment_ is responsible for automatically reading the trace metadata from the incoming request (if available), creating a segment for the processing that happens in the service and recording additional metadata about the request.\n\nThere are multiple available _environment candidates_ in Nest.js. By default most applications use the HTTP application model, where they define a `@Controller` and use `express` or `fastify` in the background.  \nFor this application type, the `HttpEnvironment` tries to read an existing trace segment from the `X-Amzn-Trace-Id`, and then creates a new segment and adds the URL and other information about the request to the segment. This segment is then made available throughout the request, **Clients** can now read the segment and add subsegment for the calls that are made through them.\n\nThe `HttpEnvironment` is activated by default in `@narando/nest-xray`.\n\nCurrently no other environments are supported.\n\n\u003e **If you are interested in contributing**:\n\u003e\n\u003e Building and supporting more environments would greatly improve the usefulness of this package.\n\u003e\n\u003e Potential environments could be:\n\u003e\n\u003e - `@nestjs/graphql`\n\u003e - `@nestjs/websockets`\n\u003e - `@nestjs/microservices`\n\u003e - `AWS Lambda` - where the trace metadata is presented in environment variables, see #67\n\n#### Http\n\nThe `HttpEnvironment` checks whether the `X-Amzn-Trace-Id` header is set and valid, and then creates a segment that references this origin trace.\nWhen the request succeeds or fails, the environment adds the current time and the success/error status to the segment.\n\nThis environment is mostly implemented through the [express middleware](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/express) of the official `aws-xray-sdk`\n\n### Clients\n\nTo trace calls made to a different service, you can either use a premade _client_, or use the `TracingService#createSubSegment` method to manually instrument the client of your choosing.\nThe premade _clients_ will automatically create a subsegment for all requests made, and track the duration and response code.\n\n#### `HttpService`\n\nThis _client_ is a drop-in replacement for the [`HttpService`](https://docs.nestjs.com/techniques/http-module) from `@nestjs/axios`.\n\nTo use it, you must only replace the imports like this:\n\n```diff\n- import { HttpModule } from \"@nestjs/axios\"\n+ import { HttpTracingModule } from \"@narando/nest-xray\"\n\n @Module({\n   imports: [\n-    HttpModule.registerAsync({\n+    HttpTracingModule.registerAsync({\n       useFactory: async (config: ConfigService) =\u003e ({\n         baseURL: config.get(\"api.base_url\"),\n         timeout: config.get(\"api.http_timeout\"),\n         headers: {\n           \"user-agent\": config.get(\"api.http_user_agent\")\n         }\n       }),\n       inject: [ConfigService]\n     })\n   ],\n   providers: [APIService],\n   exports: [APIService]\n })\n export class APIModule {}\n```\n\nKeep using `HttpService` as before, and all requests are traced as Subsegment and the necessary header for the downstream service is added to the the request.\n\n### Custom Tracing\n\nIf the premade _clients_ are not sufficient or you want more control, you can use the `TracingService`.\n\nYou can use it to create new subsegments and to access the currently set segment and subsegment.\n\nOnce you have access to a segment/subsegment, you can add any data you want to it.\n\n```typescript\nimport { TracingService } from \"@narando/nest-xray\";\n\n@Injectable()\nexport class ExternalAPIClient {\n  constructor(\n    private readonly client: ExternalModule,\n    private readonly tracingService: TracingService\n  ) {}\n\n  async doThing() {\n    // Create Subsegment for any Function\n    const subSegment = this.tracingService.createSubSegment(\"external-doThing\");\n\n    let response;\n\n    try {\n      response = await client.doThing();\n    } catch (err) {\n      subSegment.close(err);\n      throw err;\n    }\n\n    subSegment.close();\n  }\n}\n```\n\n## Implementation\n\nWe use `async_hooks` to store the traces and `aws-xray-sdk` to interact with AWS X-Ray.\n\n### `async_hooks`\n\nThis module uses the Node.js API [`async_hooks`](https://nodejs.org/api/async_hooks.html) to persist the Segment without having to explicitly pass it around to every function involved. It is what enables the \"automatic\" part of this module.\n\nThis API is currently not considered stable, though I have not yet seen any issues (besides slightly worse performance) from using it. This stability is currently being worked on in [nodejs/diagnostics#124](https://github.com/nodejs/diagnostics/issues/124).\n\n### AsyncContext\n\n`AsyncContext` is an experimental integration of `async_hooks` into the Nest.js ecosystem. It was initially developed by Kamil Mysliwiec in [nestjs/nest#1407](https://github.com/nestjs/nest/pull/1407) but not merged because `async_hooks` are not yet stable.\n\nI adopted his implementation into this module for following reasons:\n\na) It implements all the hard parts with `async_hooks` and provides enough functionality for our use cases.\nb) It was developed by the Nest.js Maintainer and is proposed to be merged into Nest.js. If this happens, we may be able to switch to the official implementation without changing any usages of the module.\n\n### TracingCoreModule\n\nThe TracingCoreModule combines the `AsyncContext` with the official `AWSXRay` client. It exports the `TracingService`, that can be used by other modules to implement additional tracing behaviour (e.g. tracing outgoing http requests).\n\n## Known Bugs\n\n- The XRay Daemon Address can only be configured through the environment variable.\n\n## License\n\nThis repository is published under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarando%2Fnest-xray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnarando%2Fnest-xray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnarando%2Fnest-xray/lists"}