@webex/internal-plugin-metrics 3.12.0-webex-services-ready.4 → 3.13.0

package/AGENTS.md

@@ -0,0 +1,208 @@
+<!-- sdd-generated-metadata
+doc_kind: agent-entry
+generated_from: agents@0.3.0
+generated_by: claude-code
+approved_by: rarajes2@cisco.com
+updated_at: 2026-10-07T04:50:31Z
+validation_status: pass
+-->
+
+# AI Agent Instructions
+
+Agent entry for the `@webex/internal-plugin-metrics` package inside the `webex-js-sdk` monorepo.
+Commands in this file are run from the monorepo root unless stated otherwise.
+
+## Working Method
+
+- Read the relevant repository files before editing. Do not edit blind.
+- Understand the task and affected surfaces before writing code.
+- Prefer focused edits over rewriting whole files.
+- Do not invent commands, paths, exports, or behavior. Verify them from repository-local source.
+- Test or validate before declaring done.
+- Keep output concise. If something is uncertain, say so instead of guessing.
+
+## Canonical Repository Documentation
+
+Before changing code or documentation, start with:
+
+- `docs/index.md` for repository documentation navigation;
+- `docs/architecture.md` for repository boundaries and interactions;
+- `docs/specs/README.md` for the manifest-backed module and contract registry;
+- the affected module's manifest-routed `<module-path>/docs/README.md`; and
+- `docs/adr/index.md` plus applicable concrete ADRs for durable decisions.
+
+Follow `.sdd/manifest.json` for each contract's publication state and canonical source. Published
+repository-owned HTTP APIs use their linked OpenAPI document; internal HTTP surfaces may link route
+code, and published SDKs use their ecosystem-native API artifact. The manifest remains authoritative
+for canonical paths and artifact decisions.
+
+This package owns no HTTP surface. Every HTTP contract it touches belongs to the upstream Webex
+metrics or unified telemetry service, and its own published surface is the SDK export declared in
+`package.json` and `src/index.ts`.
+
+## 1. Commands (Run First)
+
+Use only documented commands. Do not invent alternatives when a command is missing.
+
+| Task                   | Command                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| Install dependencies   | `yarn install` (monorepo root)                                                    |
+| Start dev environment  | Not applicable — this package is a library plugin with no runnable dev server      |
+| Run tests              | `yarn workspace @webex/internal-plugin-metrics test:unit`                          |
+| Run linters            | `yarn workspace @webex/internal-plugin-metrics test:style`                         |
+| Build/release artifact | `yarn workspace @webex/internal-plugin-metrics build:src`                          |
+| Format code            | No dedicated command; `test:style` runs `eslint ./src/**/*.*` without `--fix`      |
+
+Run a single unit spec with `--targets` relative to `test/unit/spec/`, for example
+`yarn workspace @webex/internal-plugin-metrics test:unit --targets network-telemetry.ts`.
+
+There is no runnable full build-with-tests command. The `test` script in `package.json` chains
+`test:integration` and `test:browser`, which this package does not define, and no `test/integration`
+directory exists. `.sdd/manifest.json` records `commands.build` as an unresolved owner decision for that
+reason. Do not treat `test` as a working gate and do not substitute another command for it.
+
+If a required command is unknown, stop and ask for the exact command.
+
+## 2. Agent Persona and Scope
+
+You are the Webex JS SDK telemetry engineering assistant for `@webex/internal-plugin-metrics`.
+
+Primary outcomes:
+
+- Deliver production-safe changes with passing tests.
+- Preserve existing behavior unless a change request explicitly requires a behavior change.
+- Keep docs and configuration aligned with code changes.
+
+Definition of done:
+
+1. Requested change is implemented.
+2. Relevant tests/lint/build checks pass locally.
+3. Updated docs/config cover new behavior.
+4. PR summary includes risks and rollback notes.
+
+## 3. Repository Knowledge
+
+### Tech Stack
+
+Document concrete versions so assistants choose compatible APIs.
+
+| Area             | Tooling                                                      | Version                        |
+| ---------------- | ------------------------------------------------------------ | ------------------------------ |
+| Language runtime | Node.js; `engines` in `package.json` sets the consumer floor, and the owner-declared manifest `toolchain` sets the build and test version | `22.14` to build and test; `>=18` floor |
+| Build tool       | `@webex/legacy-tools` plus `tsc`, per `package.json` scripts   | workspace package              |
+| Test framework   | Mocha, selected by `webex-legacy-tools test --runner mocha`    | workspace runner               |
+| Lint/format      | ESLint with `@webex/eslint-config-legacy`, per `.eslintrc.js`  | `eslint ^8.24.0`, `prettier ^2.7.1` |
+
+### Project Map
+
+- `src/index.ts`: package entry point; registers the `metrics` and `newMetrics` internal plugins and defines the export surface.
+- `src/metrics.js`: the legacy `webex.internal.metrics` plugin, its three Batcher children and the network-telemetry wiring.
+- `src/new-metrics.ts`: the `webex.internal.newMetrics` façade over every current event family.
+- `src/network-telemetry.ts`: the SDK request-outcome collector and its summary payload.
+- `src/call-diagnostic/`: Call Analyzer client, feature and media-quality events, the latency ledger and error-code mapping.
+- `src/privacy-and-security-permission-enricher/`: permission-change enrichment policy for client events.
+- `src/rtcMetrics/`: WebRTC stats reporting to the unified telemetry service.
+- `src/unhandled-exception-telemetry/`: browser uncaught-error and rejection reporter.
+- `test/unit/spec/`: the unit suite; its subtree mirrors `src/`.
+
+### Critical Constraints
+
+- The Call Analyzer event schema is owned externally by `@webex/event-dictionary-ts`, pinned in `package.json`. Do not hand-declare event names or payload fields in `src/metrics.types.ts`; derive them from that package.
+- Telemetry must never affect the requests it observes. Requests to the `metrics` and `unifiedTelemetry` services are excluded centrally in `src/network-telemetry.ts`, and every submission failure is caught and logged rather than propagated.
+- Personal data must not reach telemetry. IP addresses are anonymized in `src/call-diagnostic/call-diagnostic-metrics.util.ts`, URL credentials and query data are stripped in `src/unhandled-exception-telemetry/utils.ts`, and endpoint path segments are redacted in `src/network-telemetry.ts`.
+- `webex.internal.metrics` and `webex.internal.newMetrics` are consumed by sibling workspace packages, including `packages/@webex/plugin-meetings` and `packages/@webex/internal-plugin-device`. Treat both surfaces as stable and additive.
+- `src/metrics.js` must tolerate being constructed standalone and before `webex.config` is populated. Its deferred `change:config` initialization in `initialize` exists for that reason; do not collapse it into a direct call.
+
+## 4. Testing Workflow
+
+Run checks in this order:
+
+1. `yarn workspace @webex/internal-plugin-metrics test:unit`
+2. `yarn workspace @webex/internal-plugin-metrics test:style`
+3. Not applicable — this package defines no integration or end-to-end tier.
+
+Testing rules:
+
+- Add or update tests for every behavior change.
+- Cover failure paths and edge cases, not only happy paths.
+- Do not remove tests to make CI pass.
+- Use `sinon` for stubs and `assert` from `@webex/test-helper-chai` for assertions, matching the existing specs.
+- Control time with `sinon.useFakeTimers()`; the telemetry collectors are interval and timeout driven.
+
+## 5. Code Style and Patterns
+
+Coding expectations:
+
+- Follow repository style rules and static analysis output.
+- Prefer small, composable functions over large procedural blocks.
+- Make error handling explicit at system boundaries.
+- Keep public interfaces stable unless a breaking change is requested.
+- Before adding a literal path, filename, command, workflow identifier, status,
+  or other policy value, search the repository for exact and semantically
+  equivalent uses. When repeated production values represent one shared
+  contract, move them to the narrowest owning shared module or catalog as one
+  canonical named constant, enum, or type and update consumers. Keep incidental
+  similarities, one-off implementation details, and independent test fixtures
+  local.
+- Do not import a default, named, object, or namespace binding and immediately
+  re-export it. Consumers should import from the owning module; package barrels
+  should use direct named re-exports.
+- Do not write inline runtime `typeof` checks outside descriptively named guard
+  implementations. Import and reuse the owning guard instead; TypeScript
+  type-position `typeof` queries remain allowed.
+
+Pattern example:
+
+```text
+Preferred:
+- Validate external input close to the boundary.
+- Return typed/structured results.
+- Include actionable error messages.
+
+Avoid:
+- Passing unvalidated payloads deep into the system.
+- Swallowing exceptions or returning ambiguous null values.
+```
+
+New code in this package is TypeScript. `src/metrics.js`, `src/batcher.js`,
+`src/client-metrics-batcher.js` and `src/config.js` remain JavaScript because they extend the
+Ampersand-based `WebexPlugin` and `Batcher` classes from `@webex/webex-core`; keep edits there
+in-style rather than converting the file as a side effect.
+
+## 6. Git Workflow
+
+- Branch naming: `[feature|fix|chore]/[short-description]`
+- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
+- Keep commits focused and reversible.
+- Rebase on the target branch before opening PR.
+
+PR checklist:
+
+- What changed and why.
+- Tests run and results.
+- Risk/impact areas.
+- Rollback approach.
+
+## 7. Boundaries and Escalation
+
+### Always
+
+- Prefer existing patterns over introducing new architecture.
+- Keep changes minimal for the requested scope.
+- Call out assumptions and unknowns explicitly.
+
+### Ask First
+
+- Adding new dependencies or external services.
+- Large refactors or schema migrations.
+- Security-sensitive changes (auth, encryption, secrets handling).
+- Any destructive data or infrastructure operation.
+- Changing a submitted payload shape, metric name or event name, because downstream ingestion and dashboards depend on them.
+
+### Never
+
+- Commit secrets, keys, or credentials.
+- Bypass required checks by disabling tests or linters.
+- Rewrite history on shared branches.
+- Change unrelated files "while here" without clear need.
+- Add personally identifiable information, credentials or raw IP addresses to any telemetry payload.

package/README.md

@@ -8,6 +8,8 @@ This is an internal Cisco Webex plugin. As such, it does not strictly adhere to
 
 - [Install](#install)
 - [Usage](#usage)
+- [Unhandled exception telemetry](#unhandled-exception-telemetry)
+- [Network request telemetry](#network-request-telemetry)
 - [Contribute](#contribute)
 - [Maintainers](#maintainers)
 - [License](#license)
@@ -29,6 +31,278 @@ const webex = new WebexCore();
 webex.internal.metrics.WHATEVER;
 ```
 
+## Unhandled exception telemetry
+
+Unhandled exception telemetry is currently supported only in browser environments. It starts after
+the Webex SDK emits `ready`. It does not install a standalone collector, capture errors before SDK
+initialization, persist events, or retry failed telemetry submissions.
+
+The reporter captures uncaught errors, unhandled promise rejections, and resource load failures.
+Matching failures captured in the same one-second in-memory window are submitted once with an
+`occurrenceCount`. Non-HTTP(S) URLs are redacted; URL credentials, query parameters, and fragments
+are stripped; and error names, messages, and stacks are truncated before submission.
+
+Telemetry is disabled by default. Enable it with
+`metrics.unhandledExceptionTelemetry.enabled: true`. Applications may provide a synchronous
+`getMetadata` callback in the same configuration object. It must return an object whose fields can
+include application context such as `orgId` and `dataCenter`. Metadata must not contain personally
+identifiable information or credentials.
+
+````js
+import Webex from 'webex';
+
+const webex = Webex.init({
+  config: {
+    metrics: {
+      unhandledExceptionTelemetry: {
+        enabled: true,
+        getMetadata: () => ({
+          orgId: 'your-organization-id',
+          dataCenter: 'your-data-center',
+        }),
+      },
+    },
+  },
+});
+## Network request telemetry
+
+Network request telemetry is disabled by default. Enable it with
+`metrics.networkTelemetry.enabled: true`. When enabled, the metrics plugin summarizes requests
+made through the Webex SDK request pipeline. The reporting interval is configurable with
+`metrics.networkTelemetry.intervalMs` and defaults to ten minutes. It listens to the SDK-wide `request:start`,
+`request:success`, and `request:failure` events, so individual plugins do not need to wrap or
+replace `webex.request()`.
+
+For example, to collect one-minute windows:
+
+```js
+const webex = Webex.init({
+  config: {
+    metrics: {
+      networkTelemetry: {
+        enabled: true,
+        intervalMs: 60 * 1_000,
+      },
+    },
+  },
+});
+```
+
+The listeners are installed once for each Webex instance when `webex.internal.metrics` is
+constructed and the feature is enabled. The metrics package must be imported before constructing
+the Webex instance. Standard Webex SDK bundles already import and register the metrics plugin.
+
+### Scope
+
+The collector counts request and response outcomes that pass through `webex.request()` and its interceptors. For failures, it also records aggregated error details covering:
+
+- HTTP responses rejected by the SDK, such as `4xx` and `5xx` responses.
+- Network or CORS failures where no HTTP response is available.
+- Aborted and timed-out SDK requests when the error exposes that information.
+- Request preparation failures that emit `request:failure`.
+
+It does not monitor arbitrary application `fetch()`, `XMLHttpRequest`, WebSocket, or other traffic outside the SDK request pipeline. It also does not use `PerformanceObserver` or browser-wide request interception.
+
+### Event flow
+
+```text
+webex.request()
+  -> SDK request interceptors
+  -> request:start(options)
+  -> request:success(options, response) or request:failure(options, reason)
+  -> metrics request outcome listeners
+  -> aggregate host, endpoint, response, and error counts
+  -> every configured interval, submit JS_SDK_NETWORK_REQUEST_SUMMARY
+````
+
+The listeners and ten-minute accumulator are registered during metrics plugin initialization:
+
+```js
+initialize(...args) {
+  WebexPlugin.prototype.initialize.call(this, ...args);
+  if (this.webex.config.metrics.networkTelemetry.enabled !== true) {
+    return;
+  }
+  this.networkTelemetry = createNetworkTelemetryCollector(/* submission callbacks */);
+  this.listenTo(this.webex, 'request:start', this.recordNetworkRequestStart);
+  this.listenTo(this.webex, 'request:success', this.recordNetworkRequestSuccess);
+  this.listenTo(this.webex, 'request:failure', this.recordNetworkRequestFailure);
+}
+```
+
+The metrics plugin exposes `flushNetworkTelemetry()` for callers that need to submit the current
+non-empty window immediately, such as after an early call failure. When the metrics plugin is
+stopped, any non-empty partial window is submitted once before the collector is disposed. Empty
+windows are not submitted during shutdown, and the shutdown hook waits for the submission attempt
+to settle.
+
+```js
+await webex.internal.metrics.flushNetworkTelemetry();
+```
+
+### Metric schema
+
+One operational client metric named `JS_SDK_NETWORK_REQUEST_SUMMARY` is submitted at the configured
+interval. Its `eventPayload` has this shape:
+
+```ts
+type NetworkTelemetry = {
+  metricsSummary: {
+    totalSendRequest: number;
+    totalFailedRequest: number;
+    totalRecvdResponse: number;
+    totalFailedResponse: number;
+  };
+  metrics: Array<{
+    host: string;
+    endPoint: string;
+    countSendRequest: number;
+    countFailedRequest: number;
+    countRecvdResponse: number;
+    countFailedResponse: number;
+    averageNetworkDurationMs: number;
+    maxNetworkDurationP90Ms: number;
+    maxNetworkDurationP99Ms: number;
+  }>;
+  errorMetrics: Array<{
+    host: string;
+    endPoint: string;
+    statusCode: number;
+    errorCode: string;
+    method: string;
+    errorType: string;
+    errorMessage: string;
+    trackingIds: string[];
+    countError: number;
+  }>;
+  errorMetricsSummary: Record<string, {count: number}>;
+};
+```
+
+The SDK adds application metadata to the outer client metric when it wraps this `eventPayload`:
+
+| Property             | Source                                                                      |
+| -------------------- | --------------------------------------------------------------------------- |
+| `tags.app_name`      | `webex.config.appName`, or `unknown`                                        |
+| `tags.app_version`   | `webex.config.appVersion`, or `unknown`                                     |
+| `tags.app_url`       | Browser origin without path/query data, hostname fallback, or `non-browser` |
+| `fields.sdk_version` | `webex.version`                                                             |
+
+Counter mapping:
+
+| Event or outcome                                    | Summary and endpoint counters                                               |
+| --------------------------------------------------- | --------------------------------------------------------------------------- |
+| `request:start`                                     | `totalSendRequest`, `countSendRequest`                                      |
+| `request:success`                                   | `totalRecvdResponse`, `countRecvdResponse`                                  |
+| `request:failure` without an HTTP response          | `totalFailedRequest`, `countFailedRequest`                                  |
+| `request:failure` with an HTTP status (`4xx`/`5xx`) | Received-response counters plus `totalFailedResponse`/`countFailedResponse` |
+
+The `metrics` array is grouped by `host` and `endPoint`. For service-based SDK requests, `host` is the normalized logical service name. Direct-URI requests use the URI host. `endPoint` is a sanitized resource or URI path. `averageNetworkDurationMs` is the average measured network duration for completed requests in the group, while `maxNetworkDurationP90Ms` and `maxNetworkDurationP99Ms` are the maximum durations at the nearest-rank 90th and 99th percentiles. All values are in milliseconds.
+
+The `errorMetrics` array groups identical failures by host, endpoint, status code, error code, method, error type, and error message. `countError` records the number of occurrences, while `trackingIds` retains at most ten unique identifiers. `errorMetricsSummary` counts errors by status code; status `0` means no HTTP response was available.
+
+Example:
+
+```js
+{
+  metricName: 'JS_SDK_NETWORK_REQUEST_SUMMARY',
+  type: 'operational',
+  fields: {
+    totalSendRequest: 14,
+    totalFailedRequest: 1,
+    totalRecvdResponse: 13,
+    totalFailedResponse: 1
+  },
+  eventPayload: {
+    metricsSummary: {
+      totalSendRequest: 14,
+      totalFailedRequest: 1,
+      totalRecvdResponse: 13,
+      totalFailedResponse: 1
+    },
+    metrics: [{
+      host: 'hydra',
+      endPoint: 'rooms/:id/messages',
+      countSendRequest: 2,
+      countFailedRequest: 0,
+      countRecvdResponse: 2,
+      countFailedResponse: 1,
+      averageNetworkDurationMs: 410,
+      maxNetworkDurationP90Ms: 510,
+      maxNetworkDurationP99Ms: 640
+    }],
+    errorMetrics: [{
+      host: 'hydra',
+      endPoint: 'rooms/:id/messages',
+      statusCode: 503,
+      errorCode: 'SERVICE_UNAVAILABLE',
+      method: 'POST',
+      errorType: 'server_error',
+      errorMessage: 'Service unavailable',
+      trackingIds: ['example-tracking-id'],
+      countError: 1
+    }],
+    errorMetricsSummary: {
+      503: {count: 1}
+    }
+  }
+}
+```
+
+### Failure classification
+
+Classification is evaluated in the following order:
+
+| Condition                                                                                                 | `errorType`     |
+| --------------------------------------------------------------------------------------------------------- | --------------- |
+| Error name is `AbortError`                                                                                | `aborted`       |
+| Status is `408` or `504`, timeout appears in the error details, or the configured request timeout elapsed | `timeout`       |
+| Status is `429`                                                                                           | `rate_limited`  |
+| Status is `5xx`                                                                                           | `server_error`  |
+| Status is `4xx`                                                                                           | `client_error`  |
+| No response status is available, or the error name contains `network`                                     | `network_error` |
+| Any other SDK request failure                                                                             | `request_error` |
+
+### Telemetry request exclusion
+
+Requests to the `metrics` and `unifiedTelemetry` services are excluded from both success and failure collection. The exclusion also covers the legacy `api: 'metrics'` request option. This prevents a telemetry upload from affecting its own summary.
+
+The exclusion is centralized in the collector; telemetry request call sites do not require special flags.
+
+### Endpoint normalization and cardinality
+
+The `endPoint` value is derived from `options.resource`, or from the URI path for a direct-URI request:
+
+- Query parameters and fragments are removed.
+- Numeric, percent-encoded, uppercase, and otherwise non-route-looking segments are replaced with `:id`.
+
+For example:
+
+```text
+rooms/Y2lzY29zcGFyazovL3VzL1JPT00/messages?personId=secret
+```
+
+becomes:
+
+```text
+rooms/:id/messages
+```
+
+Endpoint normalization is heuristic. A short lowercase alphabetic identifier can resemble a static route segment. Do not place sensitive values directly in a resource path; use normal SDK resource identifiers and avoid embedding credentials or personal data in route names. Error messages are included because they are part of the requested error aggregate schema; callers should not put credentials or personal data in thrown error messages.
+
+### Submission behavior
+
+Each ten-minute summary uses the existing `submitClientMetrics()` batching and transport path. The accumulator resets at the reporting boundary before asynchronous submission, so requests received while a summary is being sent belong to the next window. A telemetry submission failure is caught and logged.
+
+### Tests
+
+Run the focused unit tests with Node.js 22.14:
+
+```bash
+nvm use 22.14
+yarn workspace @webex/internal-plugin-metrics test:unit --targets network-telemetry.ts
+```
+
 ## Maintainers
 
 This package is maintained by [Cisco Webex for Developers](https://developer.webex.com/).