From 0cdf9f40401bfeead02ee2c47f9e50eee301ce63 Mon Sep 17 00:00:00 2001 From: overcut Date: Sat, 10 Jan 2026 00:09:51 +0000 Subject: [PATCH 1/6] docs: update AGENTS.md - Add comprehensive agent guide covering repository structure and tooling workflows - Document coding/testing patterns, CI/CD expectations, and documentation templates --- AGENTS.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2c70098 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,108 @@ +# AGENTS Guide – `@amplication/opentelemetry-nestjs` + +## Project Overview +- **Purpose:** `@amplication/opentelemetry-nestjs` is a NestJS module that wires OpenTelemetry tracing and metrics into framework primitives, pairing auto-instrumentation with SDK helpers for Node environments (see `README.md`). +- **Tech stack:** TypeScript (NestJS module + decorators), OpenTelemetry SDK, Jest for unit tests, ESLint/Prettier for linting, and semantic-release for automated publishing. +- **Distribution:** Built via `nest build` and published from `dist/` (configured in `package.json`, `tsconfig.json`, and `tsconfig.build.json`). + +## Repository Structure & Key Directories +```text +. +├── src/ +│ ├── open-telemetry.module.ts # Module bootstrap + default instrumentation wiring +│ ├── open-telemetry-nestjs-sdk.ts # NodeSDK helpers (context manager, propagators, auto instrumentation) +│ ├── meta-scanner*.ts # Metadata utilities (+ colocated spec) +│ └── trace/ +│ ├── decorators/ # `span.ts`, `traceable.ts` +│ ├── instrumentation/ # Controller/Guard/etc. instrumentation + tests +│ ├── trace-wrapper*.ts # Helpers and tests for manual wrapping +│ └── trace.service.ts # Service exposed through module exports +├── docs/ +│ ├── migration-5-to-6.md # Example of structured guide w/ before/after blocks +│ ├── log.png & trace-flow.jpeg # Assets referenced by README +├── .github/workflows/ # `ci.yml`, `release.yml`, `releaseBeta.yml` +├── README.md # Primary user documentation +├── package.json / package-lock.json # Scripts, toolchain, dependency definitions +├── tsconfig.json & tsconfig.build.json # Compiler + build pipeline configs +├── .eslintrc.js & .prettierrc # Linting/formatting rules +└── jest.config.js # Testing + coverage thresholds +``` + +## Development Workflow & Tooling +### Node, NPM, and Nest build +- Use **Node LTS** (matching the GitHub Actions workflows that run `actions/setup-node@v3` with `lts/*`). +- Install dependencies with `npm ci` to stay aligned with CI (lockfile enforced). +- `npm run build` executes `nest build`, which reads `tsconfig.build.json` (excluding `src/**/*.spec.ts`) and writes compiled artifacts to `dist/`. + +### Available NPM Scripts (`package.json`) +| Script | Purpose | +| --- | --- | +| `npm run lint` | ESLint with auto-fix over `{src,apps,libs,test}/**/*.ts`. +| `npm run test` | Jest in-band execution. +| `npm run test:cov` | Jest with coverage summary (CI uses this). +| `npm run build` | Clean (`rimraf dist` via `prebuild`) then `nest build`. +| `npm run format` | Prettier `--write` across TypeScript files. +| `npm run semantic-release` | Release automation (triggered in `release.yml`). +| `npm run test:watch` | Local watcher variant. + +### TypeScript Configuration +- `tsconfig.json` targets **ESNext**, enables decorators/metadata, and emits declarations to `dist/`. +- `tsconfig.build.json` extends the base config and excludes `dist`, `node_modules`, and every `*.spec.ts` so builds ship production code only. + +## Coding & Testing Patterns +- **Instrumentation abstraction:** `src/trace/instrumentation/Instrumentation.ts` defines the interface, while `base-trace.instrumentation.ts` centralizes metadata lookup. Concrete instrumentations live under the same directory with paired specs (e.g., `controller.instrumentation.ts` + `.spec.ts`). +- **Default coverage for Nest pieces:** `OpenTelemetryModule` exports `defaultInstrumentation` (controllers, GraphQL resolvers, guards, interceptors, event emitters, schedulers, pipes, console logger) and ensures each class’ `setupInstrumentation()` runs through `ModuleRef` (see `src/open-telemetry.module.ts`). +- **Decorators:** `src/trace/decorators/span.ts` and `traceable.ts` attach metadata consumed by `DecoratorInstrumentation` to wrap provider methods. Class-level `@Traceable()` instruments every method; method-level `@Span()` accepts optional span names. +- **Manual spans:** `TraceService` and `TraceWrapper` provide escape hatches when DI hooks are unavailable. `trace-wrapper.spec.ts` demonstrates wrapping non-injectable classes with automatic span creation. +- **Colocated tests:** Every helper/instrumentation class retains a nearby `.spec.ts` (e.g., `meta-scanner.spec.ts`, `event-emitter.instrumentation.spec.ts`), and Jest is configured to look only inside `src/` (see `jest.config.js`). +- **Coverage requirements:** Global thresholds enforce ≥80% branches and ≥90% lines; maintain or update specs when touching instrumentation logic. + +## Quality & CI/CD Standards +- **Linting & Formatting:** `.eslintrc.js` extends `@typescript-eslint`’s recommended preset plus `plugin:prettier/recommended`; `.prettierrc` enforces single quotes and trailing commas. Always run `npm run lint` + `npm run format` before submitting changes. +- **Continuous Integration (`.github/workflows/ci.yml`):** On PRs/pushes (excluding `main`), CI runs `npm ci`, `npm run lint`, `npm run test:cov`, and `npm run build`. Broken coverage, lint errors, or build failures block merges. +- **Releases:** + - `release.yml` (push to `main`) reruns lint/test/build and executes `npx semantic-release` with OIDC-enabled npm publishing. + - `releaseBeta.yml` is a manual workflow_dispatch that bumps a provided semver (no git tag) and publishes with `npm publish --tag beta`. +- **Versioning:** Managed exclusively by semantic-release; do not hand-edit `version` except inside the manual beta workflow. + +## Documentation Guidance +- **README pattern:** The root `README.md` mixes marketing (badges, description) with practical sections (Installation, Setup, decorator usage, instrumentation table, TIP callouts, code fences, and image embeds like `![Example trace output](./docs/log.png)`). Match this tone—include inline links to NestJS/OpenTelemetry docs, highlight decorators, and use `[!TIP]` blocks for caveats. +- **Migration guides:** `docs/migration-5-to-6.md` illustrates preferred structure—table of contents, before/after TypeScript snippets, checklists, and bold "Key Changes" callouts. Follow its format when documenting future breaking changes. +- **Assets:** Store diagrams/screenshots inside `docs/` (existing `log.png` and `trace-flow.jpeg`) and reference them with relative paths to keep README portable. + +## Common Tasks +### Run validation locally +```bash +npm ci +npm run lint +npm run test:cov +npm run build +``` + +### Adding or updating instrumentation +1. Create a new file in `src/trace/instrumentation/` (kebab-case) that extends `BaseTraceInstrumentation` or implements `Instrumentation`. +2. Add a matching `*.spec.ts` next to it; reuse existing specs (e.g., `guard.instrumentation.spec.ts`) as templates. +3. Export the provider (and optionally add it to `defaultInstrumentation` in `open-telemetry.module.ts`). +4. Update `src/index.ts` if new public exports are required. +5. Run lint/tests to maintain coverage. + +### Writing documentation +- For README additions, keep sections short with code samples highlighting decorators or SDK helpers (reference `@Span`, `@Traceable`, `TraceService`). +- For migrations or deep dives, mirror `docs/migration-5-to-6.md` (sections, before/after diff, checklist, summary). +- Include screenshots/diagrams under `docs/` and ensure relative links are correct (`./docs/your-asset.png`). + +## Reference Examples +- `src/trace/decorators/span.ts` – Minimal decorator implementation showcasing metadata keys from `src/constants.ts`. +- `src/trace/instrumentation/controller.instrumentation.ts` – Full instrumentation pipeline (metadata scanning, wrapping) with `controller.instrumentation.spec.ts` validating behavior. +- `src/trace/trace-wrapper.ts` + `.spec.ts` – Manual span creation for non-injectable objects. +- `src/open-telemetry-nestjs-sdk.ts` – NodeSDK bootstrap, auto-instrumentation config (`nodeAutoInstrumentationReduceNoise`, `nestjsTextMapPropagator`, etc.). +- `docs/migration-5-to-6.md` – Long-form documentation template with before/after comparisons and checklist. +- `.github/workflows/ci.yml` – Source of required validation steps for every contribution. + +## Critical Rules & Tips +- Always keep coverage thresholds satisfied; if you touch instrumentation logic, expand the companion `*.spec.ts` rather than lowering thresholds. +- Stick to lint/format conventions (single quotes, trailing commas) to avoid CI noise. +- Never bypass CI—run `npm ci && npm run lint && npm run test:cov && npm run build` locally before opening a PR. +- Respect release automation: do not manually change versions or publish outside the provided workflows. +- Documentation updates should remain consistent with existing tone (code-forward, NestJS-specific) and cite concrete files or APIs. +- Keep changes focused; new instrumentation should be modular and declared via DI providers to maintain global enablement semantics. From c849391146231e20d55db9d09b155a7d2ef6494b Mon Sep 17 00:00:00 2001 From: overcut Date: Tue, 13 Jan 2026 00:08:14 +0000 Subject: [PATCH 2/6] docs: update AGENTS.md --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2c70098..1444559 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,10 +11,13 @@ ├── src/ │ ├── open-telemetry.module.ts # Module bootstrap + default instrumentation wiring │ ├── open-telemetry-nestjs-sdk.ts # NodeSDK helpers (context manager, propagators, auto instrumentation) +│ ├── index.ts # Export hub (barrel) exposing module pieces to consumers │ ├── meta-scanner*.ts # Metadata utilities (+ colocated spec) │ └── trace/ │ ├── decorators/ # `span.ts`, `traceable.ts` │ ├── instrumentation/ # Controller/Guard/etc. instrumentation + tests +│ ├── logger.interface.ts # Contracts for pluggable trace logger implementations +│ ├── noop.trace-exporter.ts # No-op exporter helper for logging/testing scenarios │ ├── trace-wrapper*.ts # Helpers and tests for manual wrapping │ └── trace.service.ts # Service exposed through module exports ├── docs/ @@ -94,6 +97,7 @@ npm run build ## Reference Examples - `src/trace/decorators/span.ts` – Minimal decorator implementation showcasing metadata keys from `src/constants.ts`. - `src/trace/instrumentation/controller.instrumentation.ts` – Full instrumentation pipeline (metadata scanning, wrapping) with `controller.instrumentation.spec.ts` validating behavior. +- `src/trace/instrumentation/guard.instrumentation.spec.ts` (paired with `guard.instrumentation.ts`) – Canonical Jest template for instrumentation tests; copy this when adding new providers. - `src/trace/trace-wrapper.ts` + `.spec.ts` – Manual span creation for non-injectable objects. - `src/open-telemetry-nestjs-sdk.ts` – NodeSDK bootstrap, auto-instrumentation config (`nodeAutoInstrumentationReduceNoise`, `nestjsTextMapPropagator`, etc.). - `docs/migration-5-to-6.md` – Long-form documentation template with before/after comparisons and checklist. From ad66e0a88d0f22239c3fe0086875fcb3b32e7e1a Mon Sep 17 00:00:00 2001 From: overcut Date: Wed, 14 Jan 2026 00:10:24 +0000 Subject: [PATCH 3/6] docs: update AGENTS.md --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1444559..68c70b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -96,12 +96,15 @@ npm run build ## Reference Examples - `src/trace/decorators/span.ts` – Minimal decorator implementation showcasing metadata keys from `src/constants.ts`. +- `src/meta-scanner.ts` + `.spec.ts` – Utility for enumerating Nest providers and their metadata; refer to this when adding new reflection-driven instrumentation. +- `src/open-telemetry.module.ts` – Central module wiring that registers the default instrumentation array and exposes the tracing services. - `src/trace/instrumentation/controller.instrumentation.ts` – Full instrumentation pipeline (metadata scanning, wrapping) with `controller.instrumentation.spec.ts` validating behavior. - `src/trace/instrumentation/guard.instrumentation.spec.ts` (paired with `guard.instrumentation.ts`) – Canonical Jest template for instrumentation tests; copy this when adding new providers. - `src/trace/trace-wrapper.ts` + `.spec.ts` – Manual span creation for non-injectable objects. - `src/open-telemetry-nestjs-sdk.ts` – NodeSDK bootstrap, auto-instrumentation config (`nodeAutoInstrumentationReduceNoise`, `nestjsTextMapPropagator`, etc.). - `docs/migration-5-to-6.md` – Long-form documentation template with before/after comparisons and checklist. - `.github/workflows/ci.yml` – Source of required validation steps for every contribution. +- `.github/workflows/release.yml` & `.github/workflows/releaseBeta.yml` – Release automation pipelines (semantic-release on `main`, manual beta publishing). ## Critical Rules & Tips - Always keep coverage thresholds satisfied; if you touch instrumentation logic, expand the companion `*.spec.ts` rather than lowering thresholds. From 9dc04628f912c2de8c46872ee4934fa64c98a5a8 Mon Sep 17 00:00:00 2001 From: overcut Date: Mon, 19 Jan 2026 00:09:08 +0000 Subject: [PATCH 4/6] docs: update AGENTS.md --- AGENTS.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 68c70b8..485ae65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,8 +22,12 @@ │ └── trace.service.ts # Service exposed through module exports ├── docs/ │ ├── migration-5-to-6.md # Example of structured guide w/ before/after blocks -│ ├── log.png & trace-flow.jpeg # Assets referenced by README -├── .github/workflows/ # `ci.yml`, `release.yml`, `releaseBeta.yml` +│ ├── log.png # Asset referenced by README (trace log screenshot) +│ └── trace-flow.jpeg # Asset referenced by README (trace flow diagram) +├── .github/workflows/ +│ ├── ci.yml # Validation pipeline +│ ├── release.yml # Semantic-release pipeline +│ └── releaseBeta.yml # Manual beta publishing workflow ├── README.md # Primary user documentation ├── package.json / package-lock.json # Scripts, toolchain, dependency definitions ├── tsconfig.json & tsconfig.build.json # Compiler + build pipeline configs @@ -58,14 +62,14 @@ - **Decorators:** `src/trace/decorators/span.ts` and `traceable.ts` attach metadata consumed by `DecoratorInstrumentation` to wrap provider methods. Class-level `@Traceable()` instruments every method; method-level `@Span()` accepts optional span names. - **Manual spans:** `TraceService` and `TraceWrapper` provide escape hatches when DI hooks are unavailable. `trace-wrapper.spec.ts` demonstrates wrapping non-injectable classes with automatic span creation. - **Colocated tests:** Every helper/instrumentation class retains a nearby `.spec.ts` (e.g., `meta-scanner.spec.ts`, `event-emitter.instrumentation.spec.ts`), and Jest is configured to look only inside `src/` (see `jest.config.js`). -- **Coverage requirements:** Global thresholds enforce ≥80% branches and ≥90% lines; maintain or update specs when touching instrumentation logic. +- **Coverage requirements:** Global thresholds (≥80% branches / ≥90% lines, per `jest.config.js`) must be satisfied—update companion specs whenever instrumentation logic changes. ## Quality & CI/CD Standards - **Linting & Formatting:** `.eslintrc.js` extends `@typescript-eslint`’s recommended preset plus `plugin:prettier/recommended`; `.prettierrc` enforces single quotes and trailing commas. Always run `npm run lint` + `npm run format` before submitting changes. -- **Continuous Integration (`.github/workflows/ci.yml`):** On PRs/pushes (excluding `main`), CI runs `npm ci`, `npm run lint`, `npm run test:cov`, and `npm run build`. Broken coverage, lint errors, or build failures block merges. +- **Continuous Integration (`.github/workflows/ci.yml`):** On PRs/pushes (excluding `main`), CI enforces the full validation chain—`npm ci`, `npm run lint`, `npm run test:cov`, and `npm run build` (Nest CLI)—and blocks merges on any failure. - **Releases:** - - `release.yml` (push to `main`) reruns lint/test/build and executes `npx semantic-release` with OIDC-enabled npm publishing. - - `releaseBeta.yml` is a manual workflow_dispatch that bumps a provided semver (no git tag) and publishes with `npm publish --tag beta`. + - `release.yml` (push to `main`) reruns the same validation steps before invoking `npx semantic-release` with npm provenance via OIDC. + - `releaseBeta.yml` is a manual `workflow_dispatch` requiring the desired semver input, runs `npm ci`, locally sets that version, and publishes with `npm publish --tag beta`. - **Versioning:** Managed exclusively by semantic-release; do not hand-edit `version` except inside the manual beta workflow. ## Documentation Guidance @@ -79,7 +83,7 @@ npm ci npm run lint npm run test:cov -npm run build +npm run build # Nest CLI build ``` ### Adding or updating instrumentation @@ -96,15 +100,16 @@ npm run build ## Reference Examples - `src/trace/decorators/span.ts` – Minimal decorator implementation showcasing metadata keys from `src/constants.ts`. -- `src/meta-scanner.ts` + `.spec.ts` – Utility for enumerating Nest providers and their metadata; refer to this when adding new reflection-driven instrumentation. +- `src/trace/noop.trace-exporter.ts` – Lightweight helper for logging/testing scenarios when you need a no-op exporter. - `src/open-telemetry.module.ts` – Central module wiring that registers the default instrumentation array and exposes the tracing services. -- `src/trace/instrumentation/controller.instrumentation.ts` – Full instrumentation pipeline (metadata scanning, wrapping) with `controller.instrumentation.spec.ts` validating behavior. -- `src/trace/instrumentation/guard.instrumentation.spec.ts` (paired with `guard.instrumentation.ts`) – Canonical Jest template for instrumentation tests; copy this when adding new providers. -- `src/trace/trace-wrapper.ts` + `.spec.ts` – Manual span creation for non-injectable objects. - `src/open-telemetry-nestjs-sdk.ts` – NodeSDK bootstrap, auto-instrumentation config (`nodeAutoInstrumentationReduceNoise`, `nestjsTextMapPropagator`, etc.). +- `src/trace/instrumentation/controller.instrumentation.ts` + `.spec.ts` – Full instrumentation pipeline (metadata scanning, wrapping) and companion tests validating controller behavior. +- `src/trace/instrumentation/guard.instrumentation.spec.ts` – Canonical Jest template for instrumentation tests; copy this when adding new providers. +- `src/trace/instrumentation/base-trace.instrumentation.ts` – Shared logic for scanning modules/providers and applying wrappers. +- `src/trace/trace-wrapper.ts` + `.spec.ts` – Manual span creation for non-injectable objects. +- `src/meta-scanner.ts` + `.spec.ts` – Utility for enumerating Nest providers and their metadata; reuse when adding reflection-driven instrumentation. +- `README.md` – Primary user-facing guide showcasing setup, decorators, instrumentation tables, and assets. - `docs/migration-5-to-6.md` – Long-form documentation template with before/after comparisons and checklist. -- `.github/workflows/ci.yml` – Source of required validation steps for every contribution. -- `.github/workflows/release.yml` & `.github/workflows/releaseBeta.yml` – Release automation pipelines (semantic-release on `main`, manual beta publishing). ## Critical Rules & Tips - Always keep coverage thresholds satisfied; if you touch instrumentation logic, expand the companion `*.spec.ts` rather than lowering thresholds. From 5e64aecf3bcdf5fbc3a96ae1ab9b3217a49a9a6b Mon Sep 17 00:00:00 2001 From: overcut Date: Wed, 21 Jan 2026 00:11:26 +0000 Subject: [PATCH 5/6] docs: update AGENTS.md --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 485ae65..9f9d520 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,7 +58,7 @@ ## Coding & Testing Patterns - **Instrumentation abstraction:** `src/trace/instrumentation/Instrumentation.ts` defines the interface, while `base-trace.instrumentation.ts` centralizes metadata lookup. Concrete instrumentations live under the same directory with paired specs (e.g., `controller.instrumentation.ts` + `.spec.ts`). -- **Default coverage for Nest pieces:** `OpenTelemetryModule` exports `defaultInstrumentation` (controllers, GraphQL resolvers, guards, interceptors, event emitters, schedulers, pipes, console logger) and ensures each class’ `setupInstrumentation()` runs through `ModuleRef` (see `src/open-telemetry.module.ts`). +- **Default coverage for Nest pieces:** `OpenTelemetryModule` exports `defaultInstrumentation` (controllers, GraphQL resolvers, guards, interceptors, event emitters, schedulers, pipes, console logger) and, when `forRoot` is used, the `Constants.SDK_INJECTORS` factory iterates those classes and calls `setupInstrumentation()` directly; the async builder path instead relies on `ModuleRef` to resolve providers before invoking `setupInstrumentation()` (see `src/open-telemetry.module.ts`). - **Decorators:** `src/trace/decorators/span.ts` and `traceable.ts` attach metadata consumed by `DecoratorInstrumentation` to wrap provider methods. Class-level `@Traceable()` instruments every method; method-level `@Span()` accepts optional span names. - **Manual spans:** `TraceService` and `TraceWrapper` provide escape hatches when DI hooks are unavailable. `trace-wrapper.spec.ts` demonstrates wrapping non-injectable classes with automatic span creation. - **Colocated tests:** Every helper/instrumentation class retains a nearby `.spec.ts` (e.g., `meta-scanner.spec.ts`, `event-emitter.instrumentation.spec.ts`), and Jest is configured to look only inside `src/` (see `jest.config.js`). @@ -109,6 +109,7 @@ npm run build # Nest CLI build - `src/trace/trace-wrapper.ts` + `.spec.ts` – Manual span creation for non-injectable objects. - `src/meta-scanner.ts` + `.spec.ts` – Utility for enumerating Nest providers and their metadata; reuse when adding reflection-driven instrumentation. - `README.md` – Primary user-facing guide showcasing setup, decorators, instrumentation tables, and assets. +- `.github/workflows/ci.yml` – Canonical validation workflow (npm ci → lint → test:cov → build). - `docs/migration-5-to-6.md` – Long-form documentation template with before/after comparisons and checklist. ## Critical Rules & Tips From 88d53b92df97b5b29dc095dab24d4d347ef5896f Mon Sep 17 00:00:00 2001 From: overcut Date: Thu, 22 Jan 2026 00:13:59 +0000 Subject: [PATCH 6/6] docs: update AGENTS.md --- AGENTS.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9f9d520..5494579 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,7 @@ ## Project Overview - **Purpose:** `@amplication/opentelemetry-nestjs` is a NestJS module that wires OpenTelemetry tracing and metrics into framework primitives, pairing auto-instrumentation with SDK helpers for Node environments (see `README.md`). +- **Key SDK helpers:** `src/open-telemetry-nestjs-sdk.ts` exports `startNestJsOpenTelemetrySDK` (bootstraps the NodeSDK with Nest-friendly defaults), `nodeAutoInstrumentationReduceNoise` (central place to merge low-noise auto-instrumentation settings), and `nestjsContextManager` (AsyncLocalStorage-backed context manager to keep spans aligned with Nest request scope). - **Tech stack:** TypeScript (NestJS module + decorators), OpenTelemetry SDK, Jest for unit tests, ESLint/Prettier for linting, and semantic-release for automated publishing. - **Distribution:** Built via `nest build` and published from `dist/` (configured in `package.json`, `tsconfig.json`, and `tsconfig.build.json`). @@ -73,7 +74,7 @@ - **Versioning:** Managed exclusively by semantic-release; do not hand-edit `version` except inside the manual beta workflow. ## Documentation Guidance -- **README pattern:** The root `README.md` mixes marketing (badges, description) with practical sections (Installation, Setup, decorator usage, instrumentation table, TIP callouts, code fences, and image embeds like `![Example trace output](./docs/log.png)`). Match this tone—include inline links to NestJS/OpenTelemetry docs, highlight decorators, and use `[!TIP]` blocks for caveats. +- **README pattern:** The root `README.md` mixes marketing (badges, description) with practical sections (Installation, Setup, decorator usage, instrumentation table, TIP callouts, code fences, and image embeds like `![Example trace output](./docs/log.png)`). Match this tone—include inline links to NestJS/OpenTelemetry docs, highlight decorators, and use `[!TIP]` blocks for caveats, plus keep the manual tracing helper walkthrough (`TraceWrapper`), metrics guidance (Prometheus exporter steps), and external integration examples (Prometheus scraping, OTLP exporters, AWS X-Ray/CloudWatch) up to date. - **Migration guides:** `docs/migration-5-to-6.md` illustrates preferred structure—table of contents, before/after TypeScript snippets, checklists, and bold "Key Changes" callouts. Follow its format when documenting future breaking changes. - **Assets:** Store diagrams/screenshots inside `docs/` (existing `log.png` and `trace-flow.jpeg`) and reference them with relative paths to keep README portable. @@ -86,6 +87,26 @@ npm run test:cov npm run build # Nest CLI build ``` +### Bootstrap SDK helpers for tracing +1. Add a `tracing.ts` (or similar) file that imports `startNestJsOpenTelemetrySDK`, `nodeAutoInstrumentationReduceNoise`, and `nestjsContextManager` from `@amplication/opentelemetry-nestjs` (bring in `nodeAutoInstrumentationHttpReduceIncoming` if you need extra filters). +2. Call `startNestJsOpenTelemetrySDK` with merged instrumentation config, for example: + ```ts + startNestJsOpenTelemetrySDK({ + instrumentations: [ + getNodeAutoInstrumentations( + mergeInstrumentationConfigMap( + nodeAutoInstrumentationReduceNoise(), + nodeAutoInstrumentationHttpReduceIncoming(), + ), + ), + ], + contextManager: nestjsContextManager(), + }); + ``` + This keeps noisy spans out while ensuring the Nest context manager is active for request-scoped spans. +3. Import the tracing file at the very top of `main.ts` so the SDK (and its context manager) boots before Nest constructs modules. +4. Run `npm run lint`, `npm run test:cov`, and `npm run build` to verify tracing boots cleanly alongside the rest of the validation pipeline. + ### Adding or updating instrumentation 1. Create a new file in `src/trace/instrumentation/` (kebab-case) that extends `BaseTraceInstrumentation` or implements `Instrumentation`. 2. Add a matching `*.spec.ts` next to it; reuse existing specs (e.g., `guard.instrumentation.spec.ts`) as templates. @@ -102,7 +123,7 @@ npm run build # Nest CLI build - `src/trace/decorators/span.ts` – Minimal decorator implementation showcasing metadata keys from `src/constants.ts`. - `src/trace/noop.trace-exporter.ts` – Lightweight helper for logging/testing scenarios when you need a no-op exporter. - `src/open-telemetry.module.ts` – Central module wiring that registers the default instrumentation array and exposes the tracing services. -- `src/open-telemetry-nestjs-sdk.ts` – NodeSDK bootstrap, auto-instrumentation config (`nodeAutoInstrumentationReduceNoise`, `nestjsTextMapPropagator`, etc.). +- `src/open-telemetry-nestjs-sdk.ts` – Canonical reference for `startNestJsOpenTelemetrySDK` (bootstraps the NodeSDK with Nest defaults), `nodeAutoInstrumentationReduceNoise` (curated instrumentation config), and `nestjsContextManager` (AsyncLocalStorage-backed context propagation). - `src/trace/instrumentation/controller.instrumentation.ts` + `.spec.ts` – Full instrumentation pipeline (metadata scanning, wrapping) and companion tests validating controller behavior. - `src/trace/instrumentation/guard.instrumentation.spec.ts` – Canonical Jest template for instrumentation tests; copy this when adding new providers. - `src/trace/instrumentation/base-trace.instrumentation.ts` – Shared logic for scanning modules/providers and applying wrappers.