@webex/contact-center 3.13.0-next.1 → 3.13.0-next.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1065 -339
  3. package/AGENTS.md +935 -60
  4. package/dist/webex.js +1 -1
  5. package/docs/adr/0001-spec-source-policy.md +97 -0
  6. package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
  7. package/docs/adr/0003-repo-standards-migration.md +104 -0
  8. package/docs/adr/index.md +35 -0
  9. package/docs/architecture.md +460 -0
  10. package/docs/getting-started.md +142 -0
  11. package/docs/index.md +53 -0
  12. package/docs/specs/README.md +98 -0
  13. package/package.json +10 -9
  14. package/schemas/repo-context.schema.json +796 -0
  15. package/src/docs/README.md +727 -0
  16. package/src/metrics/docs/README.md +710 -0
  17. package/src/services/agent/docs/README.md +673 -0
  18. package/src/services/config/docs/README.md +530 -0
  19. package/src/services/core/docs/README.md +993 -0
  20. package/src/services/docs/README.md +765 -0
  21. package/src/services/task/docs/README.md +1569 -0
  22. package/src/services/task/state-machine/docs/README.md +1388 -0
  23. package/src/utils/AGENTS.md +6 -4
  24. package/src/utils/docs/README.md +413 -0
  25. package/umd/contact-center.min.js +2 -2
  26. package/umd/contact-center.min.js.map +1 -1
  27. package/ai-docs/ARCHITECTURE.md +0 -168
  28. package/ai-docs/CONTRACTS.md +0 -64
  29. package/ai-docs/GETTING_STARTED.md +0 -168
  30. package/ai-docs/GLOSSARY.md +0 -43
  31. package/ai-docs/README.md +0 -138
  32. package/ai-docs/REVIEW_CHECKLIST.md +0 -41
  33. package/ai-docs/RULES.md +0 -444
  34. package/ai-docs/SECURITY.md +0 -52
  35. package/ai-docs/SERVICE_STATE.md +0 -52
  36. package/ai-docs/SPEC_INDEX.md +0 -65
  37. package/ai-docs/adr/0001-spec-source-policy.md +0 -55
  38. package/ai-docs/adr/README.md +0 -8
  39. package/ai-docs/adr/_adr-template.md +0 -31
  40. package/ai-docs/contact-center-spec.md +0 -388
  41. package/ai-docs/features/contact-owner-change-refactor.md +0 -78
  42. package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
  43. package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
  44. package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
  45. package/ai-docs/patterns/event-driven-patterns.md +0 -485
  46. package/ai-docs/patterns/testing-patterns.md +0 -480
  47. package/ai-docs/patterns/typescript-patterns.md +0 -365
  48. package/ai-docs/templates/README.md +0 -102
  49. package/ai-docs/templates/documentation/create-agents-md.md +0 -240
  50. package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
  51. package/ai-docs/templates/existing-service/bug-fix.md +0 -254
  52. package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
  53. package/ai-docs/templates/new-method/00-master.md +0 -80
  54. package/ai-docs/templates/new-method/01-requirements.md +0 -232
  55. package/ai-docs/templates/new-method/02-implementation.md +0 -295
  56. package/ai-docs/templates/new-method/03-tests.md +0 -201
  57. package/ai-docs/templates/new-method/04-validation.md +0 -141
  58. package/ai-docs/templates/new-service/00-master.md +0 -109
  59. package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
  60. package/ai-docs/templates/new-service/02-code-generation.md +0 -346
  61. package/ai-docs/templates/new-service/03-integration.md +0 -178
  62. package/ai-docs/templates/new-service/04-test-generation.md +0 -205
  63. package/ai-docs/templates/new-service/05-validation.md +0 -145
  64. package/src/metrics/ai-docs/AGENTS.md +0 -350
  65. package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
  66. package/src/metrics/ai-docs/metrics-spec.md +0 -971
  67. package/src/services/agent/ai-docs/AGENTS.md +0 -240
  68. package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
  69. package/src/services/agent/ai-docs/agent-spec.md +0 -505
  70. package/src/services/ai-docs/AGENTS.md +0 -386
  71. package/src/services/ai-docs/services-spec.md +0 -512
  72. package/src/services/config/ai-docs/AGENTS.md +0 -250
  73. package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
  74. package/src/services/config/ai-docs/config-spec.md +0 -669
  75. package/src/services/core/ai-docs/AGENTS.md +0 -381
  76. package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
  77. package/src/services/core/ai-docs/core-spec.md +0 -797
  78. package/src/services/task/ai-docs/AGENTS.md +0 -457
  79. package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
  80. package/src/services/task/ai-docs/task-spec.md +0 -1501
  81. package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
  82. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
  83. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
  84. package/src/utils/ai-docs/utils-spec.md +0 -391
@@ -0,0 +1,710 @@
1
+ ---
2
+ type: Module Spec
3
+ title: 'Metrics specification'
4
+ description: Responsibilities, boundaries, design, state, invariants, and verification for the Contact Center metrics module (MetricsManager, METRIC_EVENT_NAMES, and the behavioral event taxonomy).
5
+ tags: [module, specification]
6
+ ---
7
+ <!-- sdd-generated-metadata
8
+ doc_kind: module-spec
9
+ generated_from: module-spec@0.3.0
10
+ generated_by: claude-code
11
+ approved_by: rarajes2@cisco.com
12
+ updated_at: 2026-11-17T03:03:58Z
13
+ validation_status: pass-with-warnings
14
+ -->
15
+
16
+ # Metrics
17
+
18
+ This source-local document at `src/metrics/docs/README.md` owns the stable specification for
19
+ **the Contact Center metrics module**: the `MetricsManager` singleton, the `METRIC_EVENT_NAMES`
20
+ catalog, and the behavioral event taxonomy that every other Contact Center module uses to report
21
+ telemetry through `webex.internal.newMetrics`. Ground every claim in repository evidence and link to
22
+ the [package architecture](../../../docs/architecture.md) instead of repeating broader facts. No
23
+ service specification exists because this package is a library. The parent specification is the
24
+ [`src` package spec](../../docs/README.md).
25
+
26
+ Related context: [documentation index](../../../docs/index.md) ·
27
+ [package agent instructions](../../../AGENTS.md)
28
+
29
+ ## Metadata
30
+
31
+ | Field | Value |
32
+ |---|---|
33
+ | Owner | @webex/web-sdk |
34
+ | Source path | `src/metrics` |
35
+ | Resource kind | module |
36
+ | Status | Active |
37
+ | Last verified | 2026-11-16 at `0b8c34db7f` |
38
+ | Module id | `metrics` |
39
+ | Parent spec | [src/docs/README.md](../../docs/README.md) |
40
+ | Doc kind | Module spec |
41
+ | Coverage score | Pending coverage assessment |
42
+ | Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
43
+
44
+ ## Applicability
45
+
46
+ | Condition ID | Status | Evidence or reason | Owned section |
47
+ | --- | --- | --- | --- |
48
+ | `module.has_tiers` | N/A | No tier policy exists in `package.json` or the manifest profile | Tier |
49
+ | `module.has_ui` | N/A | `src/metrics/MetricsManager.ts` renders nothing; it only queues and submits telemetry | UI use-case flow |
50
+ | `module.crosses_service_boundaries` | Applicable | `src/metrics/MetricsManager.ts` hands every event to the host webex.internal.newMetrics client, which sends it to the Webex metrics backend | Cross-boundary use-case flow |
51
+ | `module.holds_client_state` | Applicable | `src/metrics/MetricsManager.ts` keeps the singleton, three pending queues, running timers, and the ready, lock, and disabled flags in memory | Client state model |
52
+ | `module.enforces_domain_rules` | Applicable | Name and taxonomy rules in `src/metrics/constants.ts` and `src/metrics/behavioral-events.ts`; the disabled and readiness guards in `src/metrics/MetricsManager.ts` | Business rules and invariants |
53
+ | `module.is_concurrent_async` | Applicable | `src/metrics/MetricsManager.ts` defers submission until the host ready event and drains queues from async methods behind a lock | Concurrency and reactive flow |
54
+ | `module.owns_persistence` | N/A | Nothing in `src/metrics/MetricsManager.ts` writes storage; queues live in memory only | Data, schema, and migration discipline |
55
+ | `module.stateful_transitions` | Applicable | `src/metrics/MetricsManager.ts` moves between buffering, ready, submitting, and disabled through setWebex, the ready event, submitPendingEvents, and setMetricsDisabled | State machine |
56
+ | `module.exposes_wire_protocol` | N/A | The wire format to the metrics backend belongs to @webex/internal-plugin-metrics; this module only builds names and payload objects | Protocol and wire format |
57
+ | `module.ui_multi_screen` | N/A | No UI | UI flow |
58
+ | `module.large_data_model` | N/A | The only types are the taxonomy and queue entry shapes in `src/metrics/behavioral-events.ts` and `src/metrics/MetricsManager.ts` | Data model |
59
+ | `module.returns_caller_errors` | N/A | No method in `src/metrics/MetricsManager.ts` throws to its caller; invalid input is logged and ignored | Caller-visible failure modes |
60
+ | `module.module_specific_conventions` | Applicable | The timer-pairing, category-submitter, and taxonomy rules every caller of `src/metrics/MetricsManager.ts` follows | Module-specific rules |
61
+ | `module.published_package` | N/A | `src/index.ts` does not export the metrics module; the manifest records contract contact-center-metrics as internal | Export stability |
62
+ | `module.embedded_in_host` | N/A | No host mount, theme, or embed API | Host integration and theming |
63
+ | `module.has_design_tradeoff` | Applicable | `src/metrics/MetricsManager.ts` queues and drops telemetry rather than blocking or failing product calls | Key design trade-off |
64
+ | `module.has_submodules` | N/A | The manifest has no module under src/metrics (computed by the plugin's module_tree.py) | Sub-modules |
65
+
66
+ ## Evidence register
67
+
68
+ | Evidence | What it establishes |
69
+ | --- | --- |
70
+ | `src/metrics/MetricsManager.ts` | The `MetricsManager` singleton: private constructor, `getInstance`, `resetInstance`, `setWebex` readiness wiring, the three pending queues, `timeEvent`, `cancelTimedEvent`, `addDurationIfTimed`, `preparePayload`, `spacesToUnderscore`, the `track*` methods, `setMetricsDisabled`, the `submittingEvents` lock, and the two AQM field helpers; its JSDoc is the recorded rationale |
71
+ | `src/metrics/constants.ts` | The `METRIC_EVENT_NAMES` const object (121 names) and the derived `METRIC_EVENT_NAMES` type |
72
+ | `src/metrics/behavioral-events.ts` | `BehavioralEventTaxonomy`, the private `eventTaxonomyMap` (97 names), `getEventTaxonomy`, and the comment asking authors to add new metrics to the Cypher CC metrics wiki |
73
+ | `src/constants.ts` | `PRODUCT_NAME` (`'wxcc_sdk'`), the behavioral product and the operational and business name prefix |
74
+ | `src/services/core/GlobalTypes.ts` | The `Failure` type read by `getCommonTrackingFieldForAQMResponseFailed` |
75
+ | `package.json` | Declares `@webex/internal-plugin-metrics`, whose `metrics.types` supply `EventPayload` and the taxonomy enums |
76
+ | `src/cc.ts` | Primary consumer: binds the singleton with `getInstance({webex})` in the READY callback, times and tracks station, state, WebSocket, Webex Together session, and wellness metrics |
77
+ | `src/services/ApiAiAssistant.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/Queue.ts`, `src/services/UserPreference.ts` | Service consumers that also call `getInstance({webex})`; AI Assistant and wellness actions are tracked as operational-only |
78
+ | `src/services/WebexCrossClientService.ts` | Usersub publish metrics, the `usersubPublishMetricsId` guard, preflight `skipReason` failures, and the only `cancelTimedEvent` caller |
79
+ | `src/services/WxAppTelephonyMercurySync.ts` | Mercury subscribe success and failure metrics |
80
+ | `src/services/task/voice/wxAppVoiceMethods.ts`, `src/services/task/voice/Voice.ts`, `src/services/task/voice/wxAppOfferObservability.ts`, `src/services/task/TaskManager.ts` | Webex Together task metrics, their payload helpers, the per-task tail promise chains, the 500 ms participant-field grace timer, and the participant drop metric |
81
+ | `src/services/wxAppDiagnosticLogging.ts` | The `[CC wxApp]` log prefix, the diagnostic messages, and the accept-reason and skip-reason enums that appear in metric payloads |
82
+ | `test/unit/spec/metrics/MetricsManager.ts` | 32 jest cases: category submission and wire names, invalid type, disabled behavior, queue clearing, the lock, singleton creation, readiness, timers, cancellation, duration, and both AQM helpers |
83
+ | `test/unit/spec/metrics/behavioral-events.ts` | One jest case asserting the taxonomy of 31 mapped names |
84
+ | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts`, `test/unit/spec/services/WebexCrossClientService.ts` | Consumer-level assertions on wellness, usersub, and other tracked metrics |
85
+ | `jest.config.js` | Jest with an 85% global coverage threshold; the shared config runs in the `node` environment, so the browser-only `tabHidden` branch is not exercised |
86
+ | `src/metrics/MetricsManager.ts`, `src/services/wxAppDiagnosticLogging.ts` (extension subsections) | Justify the extension subsections: MetricsManager API, Metric event catalog, Webex Together behavioral taxonomy, and WxApp metric payload fields under Public surface; one subsection per operation group under Data flow and sequence coverage; Customer console log triage under Use cases and flows. The two Webex Together subsections are kept here on purpose (see Purpose and boundary): they are the payload-field and wire-name contract of `METRIC_EVENT_NAMES` values that the code in `src/services/task/voice/wxAppVoiceMethods.ts`, `src/services/WebexCrossClientService.ts`, and `src/cc.ts` emits, and the triage table maps those wire names to the diagnostic lines of `src/services/wxAppDiagnosticLogging.ts` |
87
+
88
+ ## Purpose and boundary
89
+
90
+ - Responsibility: Track behavioral, operational, and business metrics for Contact Center SDK operations using a singleton `MetricsManager`. Provides event timing, behavioral taxonomy, in-memory queuing until the host Webex SDK is ready, payload preparation, and submission to the Webex metrics backend.
91
+ - In scope: the `METRIC_EVENT_NAMES` catalog, the behavioral taxonomy map, timers, the three pending queues, payload cleanup, name transforms, the readiness and disabled gates, and the AQM tracking-field helpers.
92
+ - Also in scope, as the telemetry contract dashboards and support read: the payload fields of the Webex Together (`WXAPP_*`) metrics and the console search terms that pair their `WXCC_SDK_WXAPP_*` wire names with `[CC wxApp]` diagnostic lines. The calling modules own the call sites; this spec owns what the emitted names and fields mean.
93
+ - Out of scope: the call sites that decide when an operation emits a metric (the calling modules), transport, batching, and authentication to the metrics backend (`@webex/internal-plugin-metrics` and the host Webex SDK), and the implementation of the `[CC wxApp]` diagnostic logging helpers (`src/services/wxAppDiagnosticLogging.ts`, specified with the services layer in [the services spec](../../services/docs/README.md)).
94
+ - Consumers: `src/cc.ts` (main plugin class, primary consumer), the services under `src/services`, `Task`, `Voice`, `WebRTC`, `Digital`, and the Webex Together helpers. Applications never reach this module directly.
95
+ - Stack: TypeScript 5.4 singleton service, Webex internal metrics APIs, LoggerProxy, Jest 27.
96
+
97
+ ## Structure and key files
98
+
99
+ | Path | Responsibility |
100
+ | --- | --- |
101
+ | `src/metrics/MetricsManager.ts` | `MetricsManager`: singleton that manages event queuing, timing, payload preparation, and submission, plus the AQM helpers |
102
+ | `src/metrics/behavioral-events.ts` | `BehavioralEventTaxonomy`, `eventTaxonomyMap`, and `getEventTaxonomy`: maps metric event names to structured taxonomy for behavioral analytics |
103
+ | `src/metrics/constants.ts` | `METRIC_EVENT_NAMES`: canonical constant object of all tracked metric event names |
104
+ | `src/metrics/docs/README.md` | This module specification |
105
+ | `test/unit/spec/metrics/MetricsManager.ts` | Unit cases for `MetricsManager` |
106
+ | `test/unit/spec/metrics/behavioral-events.ts` | Unit case for `getEventTaxonomy` |
107
+
108
+ ## Public surface
109
+
110
+ | Surface | Consumer | Compatibility commitment | Source |
111
+ | --- | --- | --- | --- |
112
+ | Contract `contact-center-metrics`: `METRIC_EVENT_NAMES` values and the `METRIC_EVENT_NAMES` type | Every Contact Center module that tracks a metric; backend dashboards read the emitted names | Internal (not exported by the package entry). Names are a telemetry contract: additive by default; renaming or removing a value changes the wire name dashboards query | `src/metrics/constants.ts` |
113
+ | `MetricsManager.getInstance`, `resetInstance`, `timeEvent`, `cancelTimedEvent`, `trackEvent`, `trackBehavioralEvent`, `trackOperationalEvent`, `trackBusinessEvent`, `setMetricsDisabled` | Contact Center modules; tests | Internal API under the same contract; synchronous, returns `void` (except `getInstance`), never throws to callers | `src/metrics/MetricsManager.ts` |
114
+ | Static helpers `getCommonTrackingFieldForAQMResponse`, `getCommonTrackingFieldForAQMResponseFailed`, `spacesToUnderscore` | Contact Center modules building metric payloads | Internal; field names are part of the payload contract | `src/metrics/MetricsManager.ts` |
115
+ | Type `MetricsType`: behavioral, operational, or business | Callers of `trackEvent` | Internal | `src/metrics/MetricsManager.ts` |
116
+ | `getEventTaxonomy` and type `BehavioralEventTaxonomy` | `MetricsManager`; tests | Internal; the map itself is private | `src/metrics/behavioral-events.ts` |
117
+
118
+ Compatibility notes:
119
+
120
+ - Do not remove or reinterpret exported symbols/events without a documented consumer migration.
121
+
122
+ ### MetricsManager API
123
+
124
+ - `MetricsManager.getInstance(options?)`: Returns the singleton instance. On first call with `{webex}`, binds to the Webex SDK and begins listening for the `ready` event.
125
+ - **Parameters**: `options` (object, optional): `{webex: WebexSDK}` - The Webex SDK instance
126
+ - **Returns**: `MetricsManager`
127
+ - `metrics.timeEvent(keys)`: Starts a timer for one or more event keys. When a matching `trackEvent` / `trackBehavioralEvent` / `trackOperationalEvent` / `trackBusinessEvent` is called, `duration_ms` is automatically added to the payload.
128
+ - `keys` (string | string[]): One or more `METRIC_EVENT_NAMES` values. The first key is the tracking key; all keys in the array will resolve the same timer.
129
+ - **Returns**: `void`
130
+ - `metrics.cancelTimedEvent(keys)`: Clears a running timed event without emitting a metric. Takes the same `keys` as `timeEvent` and deletes the timer stored under the first key; an empty array, or disabled metrics, is a no-op. **Returns**: `void`
131
+ - `metrics.trackEvent(name, payload?, metricServices?)`: Tracks an event across one or more metric services.
132
+ - `name` (METRIC_EVENT_NAMES): The event name constant
133
+ - `payload` (EventPayload, optional): Key-value pairs of event data
134
+ - `metricServices` (MetricsType[], optional): Array of `'behavioral'` | `'operational'` | `'business'` (default: `['behavioral']`)
135
+ - **Returns**: `void`
136
+ - `metrics.trackBehavioralEvent(name, options?)`: Tracks a single behavioral event. Looks up the event taxonomy from `behavioral-events.ts` and submits via `webex.internal.newMetrics.submitBehavioralEvent`.
137
+ - `metrics.trackOperationalEvent(name, options?)`: Tracks a single operational event and submits via `webex.internal.newMetrics.submitOperationalEvent` (wire name per METRICS-R-008).
138
+ - `metrics.trackBusinessEvent(name, options?)`: Tracks a single business event and submits via `webex.internal.newMetrics.submitBusinessEvent` (wire name and `appType` metadata per METRICS-R-008).
139
+ - For all three `track*` methods: `name` (METRIC_EVENT_NAMES): The event name; `options` (EventPayload, optional): Additional payload data; **Returns**: `void`
140
+ - `metrics.setMetricsDisabled(disabled)`: Enables or disables metrics collection. When disabled, all pending events are cleared and new events are dropped.
141
+ - `disabled` (boolean): `true` to disable, `false` to enable
142
+ - **Returns**: `void`
143
+ - Two static helpers extract standardized fields from AQM responses for metric payloads. `MetricsManager.getCommonTrackingFieldForAQMResponse(response)`: Static helper that extracts common tracking fields from an AQM success response.
144
+ - `response` (any): The AQM response object
145
+ - **Returns**: `Record<string, any>` with fields: `agentId`, `agentSessionId`, `teamId`, `siteId`, `orgId`, `eventType`, `trackingId`, `notifTrackingId`
146
+ - `agentId`, `agentSessionId`, `siteId`, and `orgId` prefer `response.data` over the top-level field; `teamId` prefers the top-level field; `eventType` is `response.type`, `trackingId` is `response.data.trackingId`, and `notifTrackingId` is the top-level `response.trackingId`.
147
+ - `MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failureResponse)`: Static helper that extracts common tracking fields from an AQM failure response.
148
+ - `failureResponse` (Failure): The AQM failure response object
149
+ - **Returns**: `Record<string, any>` with fields: `agentId`, `trackingId`, `notifTrackingId`, `orgId`, `failureType`, `failureReason`, `reasonCode`
150
+ - `agentId`, `failureReason` (`data.reason`), and `reasonCode` come from `failureResponse.data`; `trackingId` and `notifTrackingId` are both the top-level `trackingId`; `failureType` is `failureResponse.type`.
151
+ - `MetricsManager.spacesToUnderscore(str)`: Static helper that replaces every space with an underscore; used for payload keys and operational and business names.
152
+ - `MetricsManager.resetInstance()`: Resets the singleton instance. Used for testing only. It sets the singleton to `undefined`, allowing a fresh instance to be created. **Returns**: `void`
153
+
154
+ **Example**:
155
+
156
+ ```typescript
157
+ // During initialization (called internally from the ContactCenter READY callback)
158
+ const metrics = MetricsManager.getInstance({webex});
159
+
160
+ // Subsequent calls (no webex needed)
161
+ const metrics = MetricsManager.getInstance();
162
+ ```
163
+
164
+ ```typescript
165
+ // Single key
166
+ metrics.timeEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS);
167
+
168
+ // Multiple keys (success/failure share one timer)
169
+ metrics.timeEvent([
170
+ METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
171
+ METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
172
+ ]);
173
+ ```
174
+
175
+ ```typescript
176
+ // Behavioral only (default)
177
+ metrics.trackEvent(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS, {agentId: '123'});
178
+
179
+ // Multiple services
180
+ metrics.trackEvent(
181
+ METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
182
+ {interactionId: 'abc'},
183
+ ['behavioral', 'operational']
184
+ );
185
+ ```
186
+
187
+ ```typescript
188
+ const fields = MetricsManager.getCommonTrackingFieldForAQMResponse(aqmResponse);
189
+ metrics.trackEvent(METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS, {
190
+ ...fields,
191
+ interactionId: task.interactionId,
192
+ });
193
+ ```
194
+
195
+ ### Metric event catalog
196
+
197
+ All event names are defined in `constants.ts` as `METRIC_EVENT_NAMES`. Events follow a `{Domain} {Action} {Success|Failed}` naming convention; the exceptions are `Agent RONA`, `Websocket Event Received`, `WxApp Session Skipped`, `WxApp Offer Participant Fields Missing`, `AI Assistant Wellness Action Accepted`, `AI Assistant Wellness Event Invalid`, and the `AI_SUMMARY_*` values, whose text starts with `Post Call Summary` or `Mid Call Summary`.
198
+
199
+ `STATION_RELOGIN_*` report the silent relogin. `AI_ASSISTANT_WELLNESS_ACTION_*` record the direct wellness custom-event result, `AI_ASSISTANT_WELLNESS_EVENT_INVALID` a malformed or mismatched wellness notification that was ignored, and `WELLBEING_BREAK_IDLE_CODE_FETCH_*` the system wellness idle-code lookup result.
200
+
201
+ This table contains all 121 names from `src/metrics/constants.ts`; taxonomy presence is checked against `src/metrics/behavioral-events.ts`: 97 mapped and 24 unmapped.
202
+
203
+ | Constant | Emitted name | Behavioral taxonomy? |
204
+ |---|---|---|
205
+ | `STATION_LOGIN_SUCCESS` | `Station Login Success` | yes |
206
+ | `STATION_LOGIN_FAILED` | `Station Login Failed` | yes |
207
+ | `STATION_LOGOUT_SUCCESS` | `Station Logout Success` | yes |
208
+ | `STATION_LOGOUT_FAILED` | `Station Logout Failed` | yes |
209
+ | `STATION_RELOGIN_SUCCESS` | `Station Relogin Success` | yes |
210
+ | `STATION_RELOGIN_FAILED` | `Station Relogin Failed` | yes |
211
+ | `AGENT_STATE_CHANGE_SUCCESS` | `Agent State Change Success` | yes |
212
+ | `AGENT_STATE_CHANGE_FAILED` | `Agent State Change Failed` | yes |
213
+ | `FETCH_BUDDY_AGENTS_SUCCESS` | `Fetch Buddy Agents Success` | yes |
214
+ | `FETCH_BUDDY_AGENTS_FAILED` | `Fetch Buddy Agents Failed` | yes |
215
+ | `WEBSOCKET_REGISTER_SUCCESS` | `Websocket Register Success` | yes |
216
+ | `WEBSOCKET_REGISTER_FAILED` | `Websocket Register Failed` | yes |
217
+ | `AGENT_RONA` | `Agent RONA` | yes |
218
+ | `AGENT_CONTACT_ASSIGN_FAILED` | `Agent Contact Assign Failed` | yes |
219
+ | `AGENT_INVITE_FAILED` | `Agent Invite Failed` | yes |
220
+ | `TASK_ACCEPT_SUCCESS` | `Task Accept Success` | yes |
221
+ | `TASK_ACCEPT_FAILED` | `Task Accept Failed` | yes |
222
+ | `TASK_DECLINE_SUCCESS` | `Task Decline Success` | yes |
223
+ | `TASK_DECLINE_FAILED` | `Task Decline Failed` | yes |
224
+ | `TASK_END_SUCCESS` | `Task End Success` | yes |
225
+ | `TASK_END_FAILED` | `Task End Failed` | yes |
226
+ | `TASK_WRAPUP_SUCCESS` | `Task Wrapup Success` | yes |
227
+ | `TASK_WRAPUP_FAILED` | `Task Wrapup Failed` | yes |
228
+ | `TASK_HOLD_SUCCESS` | `Task Hold Success` | yes |
229
+ | `TASK_HOLD_FAILED` | `Task Hold Failed` | yes |
230
+ | `TASK_RESUME_SUCCESS` | `Task Resume Success` | yes |
231
+ | `TASK_RESUME_FAILED` | `Task Resume Failed` | yes |
232
+ | `TASK_CONSULT_START_SUCCESS` | `Task Consult Start Success` | yes |
233
+ | `TASK_CONSULT_START_FAILED` | `Task Consult Start Failed` | yes |
234
+ | `TASK_CONSULT_END_SUCCESS` | `Task Consult End Success` | yes |
235
+ | `TASK_CONSULT_END_FAILED` | `Task Consult End Failed` | yes |
236
+ | `TASK_TRANSFER_SUCCESS` | `Task Transfer Success` | yes |
237
+ | `TASK_TRANSFER_FAILED` | `Task Transfer Failed` | yes |
238
+ | `TASK_RESUME_RECORDING_SUCCESS` | `Task Resume Recording Success` | yes |
239
+ | `TASK_RESUME_RECORDING_FAILED` | `Task Resume Recording Failed` | yes |
240
+ | `TASK_PAUSE_RECORDING_SUCCESS` | `Task Pause Recording Success` | yes |
241
+ | `TASK_PAUSE_RECORDING_FAILED` | `Task Pause Recording Failed` | yes |
242
+ | `TASK_ACCEPT_CONSULT_SUCCESS` | `Task Accept Consult Success` | yes |
243
+ | `TASK_ACCEPT_CONSULT_FAILED` | `Task Accept Consult Failed` | yes |
244
+ | `TASK_AUTO_ANSWER_SUCCESS` | `Task Auto Answer Success` | yes |
245
+ | `TASK_AUTO_ANSWER_FAILED` | `Task Auto Answer Failed` | yes |
246
+ | `TASK_CONFERENCE_START_SUCCESS` | `Task Conference Start Success` | yes |
247
+ | `TASK_CONFERENCE_START_FAILED` | `Task Conference Start Failed` | yes |
248
+ | `TASK_CONFERENCE_END_SUCCESS` | `Task Conference End Success` | yes |
249
+ | `TASK_CONFERENCE_END_FAILED` | `Task Conference End Failed` | yes |
250
+ | `TASK_CONFERENCE_TRANSFER_SUCCESS` | `Task Conference Transfer Success` | yes |
251
+ | `TASK_CONFERENCE_TRANSFER_FAILED` | `Task Conference Transfer Failed` | yes |
252
+ | `TASK_CONFERENCE_EXIT_SUCCESS` | `Task Conference Exit Success` | yes |
253
+ | `TASK_CONFERENCE_EXIT_FAILED` | `Task Conference Exit Failed` | yes |
254
+ | `TASK_CONFERENCE_PARTICIPANT_DROP_SUCCESS` | `Task Conference Participant Drop Success` | yes |
255
+ | `TASK_CONFERENCE_PARTICIPANT_DROP_FAILED` | `Task Conference Participant Drop Failed` | yes |
256
+ | `TASK_SWITCH_CALL_SUCCESS` | `Task Switch Call Success` | yes |
257
+ | `TASK_SWITCH_CALL_FAILED` | `Task Switch Call Failed` | yes |
258
+ | `TASK_OUTDIAL_SUCCESS` | `Task Outdial Success` | yes |
259
+ | `TASK_OUTDIAL_FAILED` | `Task Outdial Failed` | yes |
260
+ | `WXAPP_TASK_MUTE_SUCCESS` | `WxApp Task Mute Success` | yes |
261
+ | `WXAPP_TASK_MUTE_FAILED` | `WxApp Task Mute Failed` | yes |
262
+ | `WXAPP_TASK_DTMF_SUCCESS` | `WxApp Task Dtmf Success` | yes |
263
+ | `WXAPP_TASK_DTMF_FAILED` | `WxApp Task Dtmf Failed` | yes |
264
+ | `WXAPP_TASK_ACCEPT_SUCCESS` | `WxApp Task Accept Success` | yes |
265
+ | `WXAPP_TASK_ACCEPT_FAILED` | `WxApp Task Accept Failed` | yes |
266
+ | `WXAPP_TASK_DECLINE_SUCCESS` | `WxApp Task Decline Success` | yes |
267
+ | `WXAPP_TASK_DECLINE_FAILED` | `WxApp Task Decline Failed` | yes |
268
+ | `WXAPP_SESSION_INIT_SUCCESS` | `WxApp Session Init Success` | yes |
269
+ | `WXAPP_SESSION_INIT_FAILED` | `WxApp Session Init Failed` | yes |
270
+ | `WXAPP_SESSION_SKIPPED` | `WxApp Session Skipped` | yes |
271
+ | `WXAPP_USERSUB_PUBLISH_SUCCESS` | `WxApp Usersub Publish Success` | yes |
272
+ | `WXAPP_USERSUB_PUBLISH_FAILED` | `WxApp Usersub Publish Failed` | yes |
273
+ | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` | `WxApp Mercury Subscribe Success` | yes |
274
+ | `WXAPP_MERCURY_SUBSCRIBE_FAILED` | `WxApp Mercury Subscribe Failed` | yes |
275
+ | `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `WxApp Offer Participant Fields Missing` | yes |
276
+ | `UPLOAD_LOGS_SUCCESS` | `Upload Logs Success` | yes |
277
+ | `UPLOAD_LOGS_FAILED` | `Upload Logs Failed` | yes |
278
+ | `WEBSOCKET_DEREGISTER_SUCCESS` | `Websocket Deregister Success` | no |
279
+ | `WEBSOCKET_DEREGISTER_FAIL` | `Websocket Deregister Failed` | no |
280
+ | `AGENT_DEVICE_TYPE_UPDATE_SUCCESS` | `Agent Device Type Update Success` | yes |
281
+ | `AGENT_DEVICE_TYPE_UPDATE_FAILED` | `Agent Device Type Update Failed` | yes |
282
+ | `WEBSOCKET_EVENT_RECEIVED` | `Websocket Event Received` | no |
283
+ | `ENTRYPOINT_FETCH_SUCCESS` | `Entrypoint Fetch Success` | yes |
284
+ | `ENTRYPOINT_FETCH_FAILED` | `Entrypoint Fetch Failed` | yes |
285
+ | `ADDRESSBOOK_FETCH_SUCCESS` | `AddressBook Fetch Success` | yes |
286
+ | `ADDRESSBOOK_FETCH_FAILED` | `AddressBook Fetch Failed` | yes |
287
+ | `QUEUE_FETCH_SUCCESS` | `Queue Fetch Success` | yes |
288
+ | `QUEUE_FETCH_FAILED` | `Queue Fetch Failed` | yes |
289
+ | `OUTDIAL_ANI_EP_FETCH_SUCCESS` | `Outdial ANI Entries Fetch Success` | yes |
290
+ | `OUTDIAL_ANI_EP_FETCH_FAILED` | `Outdial ANI Entries Fetch Failed` | yes |
291
+ | `CAMPAIGN_PREVIEW_ACCEPT_SUCCESS` | `Campaign Preview Accept Success` | yes |
292
+ | `CAMPAIGN_PREVIEW_ACCEPT_FAILED` | `Campaign Preview Accept Failed` | yes |
293
+ | `CAMPAIGN_PREVIEW_SKIP_SUCCESS` | `Campaign Preview Skip Success` | yes |
294
+ | `CAMPAIGN_PREVIEW_SKIP_FAILED` | `Campaign Preview Skip Failed` | yes |
295
+ | `CAMPAIGN_PREVIEW_REMOVE_SUCCESS` | `Campaign Preview Remove Success` | yes |
296
+ | `CAMPAIGN_PREVIEW_REMOVE_FAILED` | `Campaign Preview Remove Failed` | yes |
297
+ | `AI_ASSISTANT_SEND_EVENT_SUCCESS` | `AI Assistant Send Event Success` | no |
298
+ | `AI_ASSISTANT_SEND_EVENT_FAILED` | `AI Assistant Send Event Failed` | no |
299
+ | `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_SUCCESS` | `AI Assistant Get Real Time Assistance Success` | no |
300
+ | `AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_FAILED` | `AI Assistant Get Real Time Assistance Failed` | no |
301
+ | `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_SUCCESS` | `AI Assistant Send Real Time Assistance User Action Success` | no |
302
+ | `AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_FAILED` | `AI Assistant Send Real Time Assistance User Action Failed` | no |
303
+ | `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS` | `AI Assistant Fetch Historic Transcripts Success` | no |
304
+ | `AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED` | `AI Assistant Fetch Historic Transcripts Failed` | no |
305
+ | `AI_ASSISTANT_WELLNESS_ACTION_ACCEPTED` | `AI Assistant Wellness Action Accepted` | no |
306
+ | `AI_ASSISTANT_WELLNESS_ACTION_FAILED` | `AI Assistant Wellness Action Failed` | no |
307
+ | `AI_ASSISTANT_WELLNESS_EVENT_INVALID` | `AI Assistant Wellness Event Invalid` | no |
308
+ | `WELLBEING_BREAK_IDLE_CODE_FETCH_SUCCESS` | `Wellbeing Break Idle Code Fetch Success` | no |
309
+ | `WELLBEING_BREAK_IDLE_CODE_FETCH_FAILED` | `Wellbeing Break Idle Code Fetch Failed` | no |
310
+ | `AI_SUMMARY_GET_POST_CALL_SUCCESS` | `Post Call Summary Get Success` | no |
311
+ | `AI_SUMMARY_GET_POST_CALL_FAILED` | `Post Call Summary Get Failed` | no |
312
+ | `AI_SUMMARY_GET_MID_CALL_SUCCESS` | `Mid Call Summary Get Success` | no |
313
+ | `AI_SUMMARY_GET_MID_CALL_FAILED` | `Mid Call Summary Get Failed` | no |
314
+ | `AI_SUMMARY_POST_CALL_RESPONSE_SUCCESS` | `Post Call Summary Response Success` | no |
315
+ | `AI_SUMMARY_POST_CALL_RESPONSE_FAILED` | `Post Call Summary Response Failed` | no |
316
+ | `AI_SUMMARY_MID_CALL_RESPONSE_SUCCESS` | `Mid Call Summary Response Success` | no |
317
+ | `AI_SUMMARY_MID_CALL_RESPONSE_FAILED` | `Mid Call Summary Response Failed` | no |
318
+ | `USER_PREFERENCE_GET_SUCCESS` | `User Preference Get Success` | yes |
319
+ | `USER_PREFERENCE_GET_FAILED` | `User Preference Get Failed` | yes |
320
+ | `USER_PREFERENCE_CREATE_SUCCESS` | `User Preference Create Success` | yes |
321
+ | `USER_PREFERENCE_CREATE_FAILED` | `User Preference Create Failed` | yes |
322
+ | `USER_PREFERENCE_UPDATE_SUCCESS` | `User Preference Update Success` | yes |
323
+ | `USER_PREFERENCE_UPDATE_FAILED` | `User Preference Update Failed` | yes |
324
+ | `USER_PREFERENCE_DELETE_SUCCESS` | `User Preference Delete Success` | yes |
325
+ | `USER_PREFERENCE_DELETE_FAILED` | `User Preference Delete Failed` | yes |
326
+
327
+ Special events (no success/failure pair):
328
+
329
+ - `AGENT_RONA` — has behavioral taxonomy (`service.agent_rona.set`); Agent Ring-On-No-Answer triggered
330
+ - `AGENT_CONTACT_ASSIGN_FAILED` — has behavioral taxonomy (`service.agent_contact_assign.fail`)
331
+ - `AGENT_INVITE_FAILED` — has behavioral taxonomy (`service.agent_invite.fail`)
332
+ - `WEBSOCKET_EVENT_RECEIVED` — **no** behavioral taxonomy (not in `eventTaxonomyMap`)
333
+ - `WXAPP_SESSION_SKIPPED` — has behavioral taxonomy (`wxcc_sdk.user.webex_together_session_init.ignore`)
334
+
335
+ The 24 unmapped names are the eight original `AI_ASSISTANT_*` names, three Agent Wellness Break `AI_ASSISTANT_WELLNESS_*` names, two `WELLBEING_BREAK_IDLE_CODE_FETCH_*` names, eight `AI_SUMMARY_*` names, and three WebSocket names (`WEBSOCKET_DEREGISTER_SUCCESS`, `WEBSOCKET_DEREGISTER_FAIL`, and `WEBSOCKET_EVENT_RECEIVED`). Agent Wellness Break and AI summary metrics are intentionally operational-only.
336
+
337
+ ### Webex Together behavioral taxonomy
338
+
339
+ Webex Together events (`WXAPP_*` constants) use `*_webex_together` compound targets. Assembled Amplitude names follow `wxcc_sdk.user.{target}.{verb}` (e.g. `wxcc_sdk.user.task_accept_webex_together.complete`). Operational and business wire names are unchanged (`WXCC_SDK_WXAPP_*`).
340
+
341
+ | Feature | Behavioral target | Success name | Failure name | Skip name |
342
+ |---|---|---|---|---|
343
+ | Task accept / answer | `task_accept_webex_together` | `wxcc_sdk.user.task_accept_webex_together.complete` | `wxcc_sdk.user.task_accept_webex_together.fail` | — |
344
+ | Task reject / decline | `task_reject_webex_together` | `wxcc_sdk.user.task_reject_webex_together.complete` | `wxcc_sdk.user.task_reject_webex_together.fail` | — |
345
+ | Task mute / unmute toggle | `task_mute_webex_together` | `wxcc_sdk.user.task_mute_webex_together.complete` | `wxcc_sdk.user.task_mute_webex_together.fail` | — |
346
+ | Task DTMF / keypad | `task_dtmf_webex_together` | `wxcc_sdk.user.task_dtmf_webex_together.complete` | `wxcc_sdk.user.task_dtmf_webex_together.fail` | — |
347
+ | Usersub publish | `webex_together_usersub_publish` | `wxcc_sdk.user.webex_together_usersub_publish.complete` | `wxcc_sdk.user.webex_together_usersub_publish.fail` | — |
348
+ | Mercury subscribe | `webex_together_mercury_subscribe` | `wxcc_sdk.user.webex_together_mercury_subscribe.complete` | `wxcc_sdk.user.webex_together_mercury_subscribe.fail` | — |
349
+ | Session init | `webex_together_session_init` | `wxcc_sdk.user.webex_together_session_init.complete` | `wxcc_sdk.user.webex_together_session_init.fail` | `wxcc_sdk.user.webex_together_session_init.ignore` |
350
+ | Offer participant fields | `webex_together_offer_participant_fields` | — | `wxcc_sdk.user.webex_together_offer_participant_fields.fail` | — |
351
+
352
+ What each Webex Together metric records, and the ordering rules its callers keep:
353
+
354
+ | Constant | Value | Description |
355
+ |---|---|---|
356
+ | `WXAPP_TASK_MUTE_SUCCESS` / `FAILED` | `'WxApp Task Mute ...'` | Webex Together task mute/unmute toggle (`wxcc_sdk.user.task_mute_webex_together.complete\|fail`). Mute telephony is queued per task via tail promise chain (`Voice.wxAppMuteToggleTail`) so concurrent toggles do not overwrite the shared `timeEvent` timer or reorder requests. |
357
+ | `WXAPP_TASK_DTMF_SUCCESS` / `FAILED` | `'WxApp Task Dtmf ...'` | Webex Together DTMF/keypad (`wxcc_sdk.user.task_dtmf_webex_together.complete\|fail`). DTMF telephony is queued per task via tail promise chain (`Voice.wxAppDtmfTail`) so concurrent keypad input does not overwrite the shared `timeEvent` timer or reorder digits. |
358
+ | `WXAPP_TASK_ACCEPT_SUCCESS` / `FAILED` | `'WxApp Task Accept ...'` | Webex Together accept/answer (`wxcc_sdk.user.task_accept_webex_together.complete\|fail`) |
359
+ | `WXAPP_TASK_DECLINE_SUCCESS` / `FAILED` | `'WxApp Task Decline ...'` | Webex Together reject/decline (`wxcc_sdk.user.task_reject_webex_together.complete\|fail`). Inbound offers: telephony `rejectCall` via `runWxAppReject`. wxApp outdial cancellations: CC `cancelTask` via `runWxAppOutdialDecline` (additive with `TASK_DECLINE_*`). Outdial failure payloads merge AQM `error.details` via `getCommonTrackingFieldForAQMResponseFailed` so wxApp metrics and diagnostic logs preserve `trackingId` / structured failure reason. |
360
+ | `WXAPP_SESSION_INIT_SUCCESS` / `FAILED` | `'WxApp Session Init ...'` | Webex Together session orchestration (`wxcc_sdk.user.webex_together_session_init.complete\|fail`) |
361
+ | `WXAPP_SESSION_SKIPPED` | `'WxApp Session Skipped'` | Webex Together session skipped (`wxcc_sdk.user.webex_together_session_init.ignore`) |
362
+ | `WXAPP_USERSUB_PUBLISH_SUCCESS` / `FAILED` | `'WxApp Usersub Publish ...'` | Cross-client usersub publish (`wxcc_sdk.user.webex_together_usersub_publish.complete\|fail`). Preflight failures (missing `userId` or device URL before HTTP publish) emit `WXAPP_USERSUB_PUBLISH_FAILED` with `skipReason` (`user_id_unavailable` / `device_url_unavailable`) and no `timeEvent` timer. Stale-generation discards (teardown or concurrent disable while HTTP publish is in flight) call `cancelTimedEvent` without emitting success/fail only when the completing publish still owns the active timer (`usersubPublishMetricsId` guard — a newer overlapping publish must not have its timer cleared). |
363
+ | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` / `FAILED` | `'WxApp Mercury Subscribe ...'` | Telephony Mercury mute-sync subscribe (`wxcc_sdk.user.webex_together_mercury_subscribe.complete\|fail`) |
364
+ | `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `'WxApp Offer Participant Fields Missing'` | Read-only observability when usersub is active but inbound OFFERED participant **still** lacks valid wxApp fields after a **500 ms grace period** (orchestrated in `voice/wxAppOfferObservability.ts`; avoids false alarms from transient WS ordering). After usersub publish, `TaskManager.refreshWxAppOfferObservabilityForAllTasks()` re-runs the observer so a pre-publish OFFERED task can still schedule grace. Task removal calls `disposeWxAppOfferObservability()` so a pending timer cannot emit after `CONTACT_MERGED` / collection drop. Emitted with matching `[CC wxApp] participant fields mismatch` WARN (`wxcc_sdk.user.webex_together_offer_participant_fields.fail`) |
365
+
366
+ ### WxApp metric payload fields (operational / behavioral tags)
367
+
368
+ Every Webex Together metric is tracked with `['operational', 'behavioral']`.
369
+
370
+ | Event | Payload fields (booleans/enums; no raw IDs) |
371
+ |---|---|
372
+ | `WXAPP_SESSION_INIT_SUCCESS` | `loginOption`, `enableWxBetterTogether`, `usersubPublished`, `mercurySubscribed`, `telephonyTaskType` |
373
+ | `WXAPP_SESSION_INIT_FAILED` | above + `skipReason` (`usersub_not_published`, `mercury_not_subscribed`, `mercury_subscribe_failed`, `publish_failed`) + optional `error`. `usersubPublished` reflects **retained session state** (`isAnswerCallsStateActive()` / `answerCallsState`), including on catch-path failures — not gated on the current init attempt's `publishedEnable`. |
374
+ | `WXAPP_SESSION_SKIPPED` | `loginOption`, `enableWxBetterTogether`, `skipReason` (`unsupported_browser_login` or `flag_disabled`) |
375
+ | `WXAPP_USERSUB_PUBLISH_SUCCESS` | `enableWxBetterTogether`, `usersubPublished` |
376
+ | `WXAPP_USERSUB_PUBLISH_FAILED` | `enableWxBetterTogether`, `usersubPublished`, optional `skipReason`, `error`. `usersubPublished` reflects **retained session state** (`answerCallsState`), not the requested enable value — a failed disable/refresh while usersub remains active reports `true`. |
377
+ | `WXAPP_MERCURY_SUBSCRIBE_SUCCESS` | `mercurySubscribed: true` |
378
+ | `WXAPP_MERCURY_SUBSCRIBE_FAILED` | `mercurySubscribed: false`, `error` |
379
+ | `WXAPP_TASK_ACCEPT_*` / `DECLINE_*` | `taskId`, `hasDeviceCallId`, `hasDeviceId`, optional `acceptReason`; failures add `trackingId` when available. `acceptReason` is captured **before** the telephony REST call (not hard-coded `wxApp_offer_ready`) so success and failure both retain `wxApp_answer_pending` / `wxApp_accept_in_flight` when those flags were already set. Outdial-cancel AQM failures (`error.details`) include the same participant context fields via `getWxAppTelephonyMetricContext` merged with AQM correlation fields. Outdial cancel during post-accept pending phase may report `acceptReason: wxApp_answer_pending`. |
380
+ | `WXAPP_TASK_MUTE_*` / `DTMF_*` | `taskId`, `hasDeviceCallId`, `hasDeviceId`; success adds `targetMuted` (mute) or `dtmfLength` (DTMF); failures add `error`, and `trackingId` when available |
381
+ | `WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING` | `taskId`, `usersubPublished`, `hasDeviceCallId`, `hasDeviceId`, `acceptReason` |
382
+
383
+ ## Dependencies
384
+
385
+ | Dependency | Why it is required | Failure behavior |
386
+ | --- | --- | --- |
387
+ | `@webex/internal-plugin-metrics` | Provides `webex.internal.newMetrics` for actual metric submission (`submitBehavioralEvent`, `submitOperationalEvent`, `submitBusinessEvent`); its `metrics.types` supply `EventPayload` and the taxonomy enums (contract `webex-internal-metrics`) | Calls are fire-and-forget: the module does not await, retry, or requeue after handing an event over |
388
+ | Host Webex SDK ready lifecycle (contract `webex-core-plugin-runtime`) | Webex ready lifecycle: `webex.ready` and `webex.once('ready')` open the submission gate | Until ready, events stay queued in memory |
389
+ | `LoggerProxy` | Used for error logging within the metrics module (`src/logger-proxy.ts`) | Logs an invalid metric type or an empty `timeEvent` key array; never throws |
390
+ | `Failure` type (from `services/core/GlobalTypes`) | Used in `getCommonTrackingFieldForAQMResponseFailed` | Type only; missing fields become `undefined` and are then stripped by payload preparation |
391
+ | `PRODUCT_NAME` (from `constants.ts`) | Set to `'wxcc_sdk'`, used as the product identifier in behavioral taxonomy and as prefix for operational/business event names | Compile-time constant |
392
+ | Browser `window` and `document` | Browser visibility metadata: `tabHidden` is read from `document.hidden` | Skipped when `window` is undefined (Node) |
393
+
394
+ ## Requirements
395
+
396
+ | ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
397
+ |---|---|---|---|---|---|---|
398
+ | METRICS-R-001 | Track only names defined by METRIC_EVENT_NAMES and keep the canonical catalog synchronized with the const object. | Telemetry queries and dashboards depend on exact stable event names. | `src/metrics/constants.ts` | None found (compile-time type check only) | No test compares this catalog with the const object; the `METRIC_EVENT_NAMES` parameter type of every `track*` method enforces the first half at compile time. | PRESENT |
399
+ | METRICS-R-002 | Map behavioral events through eventTaxonomyMap and explicitly identify defined names without taxonomy. | Undefined taxonomy must not be mistaken for an emitted or classified behavioral event. | `src/metrics/behavioral-events.ts` | `test/unit/spec/metrics/behavioral-events.ts` | The unit case asserts 31 of the 97 mapped names and none of the 24 unmapped names. | PRESENT |
400
+ | METRICS-R-003 | When metrics are disabled, clear pending events and make `timeEvent` plus all tracking methods return without recording/submitting. | Telemetry must never block or alter product behavior and disablement must be comprehensive. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | `cancelTimedEvent` also returns early while disabled. No module in `src` calls `setMetricsDisabled`; disabling metrics in development mode is not implemented (code comment SPARK-637285). | PRESENT |
401
+ | METRICS-R-004 | Queue submissions until the host SDK is ready and flush through the correct behavioral/operational/business service. | Early lifecycle telemetry must not be lost solely because the host is not ready. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None. | PRESENT |
402
+ | METRICS-R-005 | Submit through the host SDK's `webex.internal.newMetrics` client without storing credentials or implementing authorization policy in MetricsManager. | Host-owned authentication keeps telemetry credential handling outside the Contact Center metrics module. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None; authentication is inherited and credential ownership is explicitly N/A. | PRESENT |
403
+ | METRICS-R-006 | Track wellness action, invalid notification, and system idle-code lookup outcomes as operational metrics using fixed names and reason-only/context-minimized payloads. | The feature needs diagnosable lifecycle signals without logging wellness payloads or agent PII. | `src/metrics/constants.ts`, `src/cc.ts`, `src/services/ApiAiAssistant.ts` | `test/unit/spec/cc.ts` | These names intentionally have no behavioral taxonomy. Only `AI_ASSISTANT_WELLNESS_EVENT_INVALID` is asserted by name; the action and idle-code metrics are not asserted. | PRESENT |
404
+ | METRICS-R-007 | `timeEvent(keys)` stores `{startTime, keys}` under the first key; tracking any key in that set adds `duration_ms` (now minus start) and deletes the whole entry; an empty key array logs `[MetricsManager] No keys provided for timeEvent` and is ignored; `cancelTimedEvent(keys)` deletes the entry under the first key without emitting. | Success and failure outcomes of one operation share one timer, so either outcome clears it; a discarded operation (a stale usersub publish) must not leave a timer that a later event would consume. | `src/metrics/MetricsManager.ts`, `src/services/WebexCrossClientService.ts` | `test/unit/spec/metrics/MetricsManager.ts`, `test/unit/spec/services/WebexCrossClientService.ts` | None. | PRESENT |
405
+ | METRICS-R-008 | Behavioral events submit `{product, agent, target, verb, payload}` from `getEventTaxonomy(name)`; operational and business events submit `name` as `WXCC_SDK_` plus the value with spaces replaced by underscores and upper-cased; business events also carry `metadata: {appType: 'wxcc_sdk'}`. | Each backend category keys on its own naming scheme; `PRODUCT_NAME` keeps the product identity in one constant. | `src/metrics/MetricsManager.ts`, `src/constants.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None. | PRESENT |
406
+ | METRICS-R-009 | `preparePayload()` processes every event payload before submission: it removes empty/null/undefined fields (strips keys with `undefined`, `null`, `''`, any arrays, or empty objects), converts spaces to underscores (`spacesToUnderscore()` applied to all key names), and adds common metadata (appends `tabHidden: document.hidden` in browser environments, that is when `window` exists). | Backends reject or mis-index empty and nested values; `tabHidden` lets analysts separate background-tab activity. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | The `tabHidden` branch is not exercised because jest runs in the `node` environment. | PRESENT |
407
+ | METRICS-R-010 | `trackEvent` defaults to `['behavioral']`, tracks each requested category in order, and logs `[MetricsManager] Invalid metric type:` followed by the category for an unknown category without throwing. | Callers choose the categories per event; a typo must not break the product call. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None. | PRESENT |
408
+ | METRICS-R-011 | `getCommonTrackingFieldForAQMResponse` and `getCommonTrackingFieldForAQMResponseFailed` return the fixed field sets listed under MetricsManager API, reading nested and flat AQM shapes. | AQM success and failure shapes differ; one helper per shape keeps correlation fields (`trackingId`, `notifTrackingId`) consistent across every metric. | `src/metrics/MetricsManager.ts`, `src/services/core/GlobalTypes.ts` | `test/unit/spec/metrics/MetricsManager.ts` | None. | PRESENT |
409
+
410
+ ## Design overview
411
+
412
+ Metrics separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit. Telemetry is deliberately non-blocking and queue-backed so product behavior never waits for metrics; failures are logged rather than propagated (Key design trade-off records the cost).
413
+
414
+ - **Singleton Pattern**: Single `MetricsManager` instance shared across the entire SDK
415
+ - **Three Metric Types**: Behavioral (user actions), operational (system events), business (business-level analytics)
416
+ - **Event Timing**: `timeEvent` + `trackEvent` pattern automatically calculates `duration_ms`
417
+ - **Queued Submission**: Events are queued until the Webex SDK is ready, then submitted in order
418
+ - **Behavioral Taxonomy**: Structured `product.agent.target.verb` naming convention for behavioral events
419
+ - **Payload Preparation**: Automatic cleanup of empty fields, space-to-underscore conversion, and `tabHidden` metadata
420
+ - **AQM Response Helpers**: Static methods to extract common tracking fields from AQM responses
421
+
422
+ Each behavioral event maps to a structured taxonomy in `behavioral-events.ts`:
423
+
424
+ ```text
425
+ {product}.{agent}.{target}.{verb}
426
+ ```
427
+
428
+ - **product**: Always `'wxcc_sdk'` (from `PRODUCT_NAME`)
429
+ - **agent**: `'user'` for user-initiated actions, `'service'` for system-generated events
430
+ - **target**: Snake_case description of the action (e.g., `'station_login'`, `'task_accept'`)
431
+ - **verb**: `'complete'` for success, `'fail'` for failure, `'set'` for RONA events, and `'ignore'` for `WXAPP_SESSION_SKIPPED`
432
+
433
+ **Example**: `STATION_LOGIN_SUCCESS` maps to `wxcc_sdk.user.station_login.complete`
434
+
435
+ Each metric event name maps to a `BehavioralEventTaxonomy` with four fields, declared in [behavioral-events.ts](../behavioral-events.ts) with the types `MetricEventProduct` (`product`), `MetricEventAgent` (`agent`), `string` (`target`), and `MetricEventVerb` (`verb`) from `@webex/internal-plugin-metrics`. The mapping is defined in `behavioral-events.ts` via `eventTaxonomyMap` and accessed through `getEventTaxonomy(name)`.
436
+
437
+ > **Note**: The 24 names catalogued above as lacking `eventTaxonomyMap` entries, including the five wellness-related names, are operational-only; Pitfalls and constraints records what happens when one reaches the behavioral category.
438
+
439
+ Participant Drop uses target `task_conference_participant_drop` with `complete` for success and `fail` for failure. Its metric payload is limited to task/request correlation and standard AQM tracking fields; participant IDs, numbers, names, URLs, headers, and raw routing payloads are excluded.
440
+
441
+ ## Data flow and sequence coverage
442
+
443
+ Call style: synchronous in-process method calls on the `MetricsManager` singleton; each queued event is handed to `webex.internal.newMetrics` by a direct call, which owns the network transport.
444
+
445
+ | Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
446
+ | --- | --- | --- | --- |
447
+ | Time and track an event | `timeEvent` then `trackEvent`; the payload carries `duration_ms` | Timing and tracking subsection; `src/metrics/MetricsManager.ts` | Success/failure keys share one timer; missing timing data leaves the payload untimed. `cancelTimedEvent` drops a timer without emitting |
448
+ | Queue until SDK readiness | `getInstance({webex})`; queued events drain on ready | SDK readiness subsection; `src/metrics/MetricsManager.ts` | A not-ready SDK retains events; READY drains them through the configured metrics service. |
449
+ | Submit behavioral/operational/business events | `trackEvent(name, payload, metricServices)`; one `newMetrics` call per category | Category submission subsection; `src/metrics/MetricsManager.ts` | The module does not retry or requeue after handing an event to `newMetrics`. An unknown category is logged and skipped |
450
+ | Disable metrics | `setMetricsDisabled(true)` | Disablement subsection; `src/metrics/MetricsManager.ts` | Pending queues are cleared and future timing/tracking calls return immediately. |
451
+
452
+ ### Timing and tracking
453
+
454
+ ```mermaid
455
+ sequenceDiagram
456
+ participant CC as ContactCenter (cc.ts)
457
+ participant MM as MetricsManager
458
+
459
+ CC->>MM: timeEvent([SUCCESS_KEY, FAILURE_KEY])
460
+ Note over MM: Store startTime + key set in runningEvents
461
+ CC->>CC: Execute operation (e.g., stationLogin)
462
+ alt Success
463
+ CC->>MM: trackEvent(SUCCESS_KEY, payload, ['behavioral', 'operational', 'business'])
464
+ else Failure
465
+ CC->>MM: trackEvent(FAILURE_KEY, payload, ['behavioral', 'operational', 'business'])
466
+ end
467
+ MM->>MM: addDurationIfTimed → duration_ms = now - startTime, remove all keys for that operation
468
+ MM->>MM: preparePayload → clean empty fields, add tabHidden
469
+ MM->>MM: Push to each requested pending queue (see Category submission)
470
+ ```
471
+
472
+ ### SDK readiness
473
+
474
+ ```mermaid
475
+ sequenceDiagram
476
+ participant CC as ContactCenter
477
+ participant MM as MetricsManager
478
+ participant Webex as WebexSDK
479
+
480
+ CC->>MM: getInstance({webex})
481
+ MM->>MM: Create singleton (if needed)
482
+ MM->>MM: setWebex(webex)
483
+ opt webex.ready === true
484
+ MM->>MM: setReadyToSubmitEvents()
485
+ MM->>MM: submitPendingEvents()
486
+ end
487
+ MM->>Webex: webex.once('ready', callback)
488
+ Note over MM: 'ready' listener is always registered
489
+ Webex-->>MM: 'ready' event fires
490
+ MM->>MM: setReadyToSubmitEvents()
491
+ MM->>MM: submitPendingEvents()
492
+ ```
493
+
494
+ ### Category submission
495
+
496
+ ```mermaid
497
+ sequenceDiagram
498
+ participant Caller
499
+ participant MM as MetricsManager
500
+ participant NM as webex.internal.newMetrics
501
+ Caller->>MM: trackEvent(name, payload, metricServices)
502
+ loop each requested metric service
503
+ alt behavioral
504
+ MM->>NM: submitBehavioralEvent(taxonomy + payload)
505
+ else operational
506
+ MM->>NM: submitOperationalEvent(WXCC_SDK_* + payload)
507
+ else business
508
+ MM->>NM: submitBusinessEvent(WXCC_SDK_* + appType)
509
+ else invalid metric service
510
+ MM->>MM: LoggerProxy.error(invalid type)
511
+ end
512
+ end
513
+ Note over MM,NM: No module-level retry or requeue after submission handoff
514
+ ```
515
+
516
+ ### Disablement
517
+
518
+ ```mermaid
519
+ sequenceDiagram
520
+ participant Caller
521
+ participant MM as MetricsManager
522
+ Caller->>MM: setMetricsDisabled(true)
523
+ MM->>MM: clear pending behavioral/operational/business queues
524
+ Caller->>MM: timeEvent(...) / trackEvent(...)
525
+ alt metricsDisabled
526
+ MM-->>Caller: return without timing, queueing, or submission
527
+ else re-enabled
528
+ MM->>MM: use normal timing/queue flow
529
+ end
530
+ ```
531
+
532
+ ## Class and component relationships
533
+
534
+ ```mermaid
535
+ classDiagram
536
+ class ContactCenter
537
+ class MetricsManager
538
+ class METRIC_EVENT_NAMES
539
+ class eventTaxonomyMap
540
+ class NewMetrics
541
+ ContactCenter --> MetricsManager : timeEvent / trackEvent
542
+ MetricsManager --> METRIC_EVENT_NAMES : canonical names
543
+ MetricsManager --> eventTaxonomyMap : behavioral taxonomy lookup
544
+ MetricsManager --> NewMetrics : submit queued event types
545
+ ```
546
+
547
+ `MetricsManager` uses a private constructor with a static `getInstance` factory ([MetricsManager.ts](../MetricsManager.ts)): `getInstance(options?: {webex: WebexSDK})` creates the private static `instance` with `new MetricsManager()` when none exists, calls `setWebex(options.webex)` only while the instance has no `webex` and options carry one, and returns the instance.
548
+
549
+ ## Use cases and flows
550
+
551
+ | Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
552
+ | --- | --- | --- | --- | --- |
553
+ | `UC-001` | Contact Center module (for example `src/cc.ts` station login) | Time and track an event: `timeEvent` records the start against success/failure keys and `trackEvent` attaches `duration_ms` before preparing and queuing the payload. | Untimed events carry no `duration_ms`; disabled metrics drop the call | `src/metrics/MetricsManager.ts`, `test/unit/spec/metrics/MetricsManager.ts` |
554
+ | `UC-002` | `ContactCenter` READY callback and service constructors | Queue until SDK readiness: events remain in the behavioral/operational/business pending queues until the host is ready, then the ready callback drains them. | Events tracked before `getInstance({webex})` also wait; nothing is persisted across reloads | `src/metrics/MetricsManager.ts`, `test/unit/spec/metrics/MetricsManager.ts` |
555
+ | `UC-003` | Any tracking caller | Submit event categories: each requested metric service uses its matching `webex.internal.newMetrics` submission method; taxonomy is applied only where `eventTaxonomyMap` contains the name. | Unknown category logged; unmapped behavioral name breaks the drain (Pitfalls and constraints) | `src/metrics/MetricsManager.ts`, `src/metrics/behavioral-events.ts`, `test/unit/spec/metrics/MetricsManager.ts` |
556
+ | `UC-004` | `WebexCrossClientService` usersub publish | Times the publish, tracks success or failure, and cancels the timer when a newer teardown or disable makes the result stale | `cancelTimedEvent` runs only while the publish still owns the timer (`usersubPublishMetricsId`) | `src/services/WebexCrossClientService.ts`, `test/unit/spec/services/WebexCrossClientService.ts` |
557
+
558
+ The standard pattern used throughout the Contact Center SDK (as in `cc.ts` station login, which also adds `loginType` and other fields):
559
+
560
+ ```typescript
561
+ const metrics = MetricsManager.getInstance();
562
+
563
+ // 1. Start timing before the operation
564
+ metrics.timeEvent([
565
+ METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
566
+ METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
567
+ ]);
568
+
569
+ try {
570
+ const resp = await performLogin(params);
571
+
572
+ // 2a. Track success (duration_ms auto-added)
573
+ metrics.trackEvent(
574
+ METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS,
575
+ {...MetricsManager.getCommonTrackingFieldForAQMResponse(resp)},
576
+ ['behavioral', 'operational', 'business']
577
+ );
578
+ } catch (error) {
579
+ // 2b. Track failure (duration_ms auto-added); the AQM Failure is on error.details
580
+ const failure = error.details as Failure;
581
+ metrics.trackEvent(
582
+ METRIC_EVENT_NAMES.STATION_LOGIN_FAILED,
583
+ {...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure)},
584
+ ['behavioral', 'operational', 'business']
585
+ );
586
+ }
587
+ ```
588
+
589
+ ### Cross-boundary use-case flow
590
+
591
+ | Boundary | Transport and ordering | Compatibility | Timeout, retry, and recovery |
592
+ | --- | --- | --- | --- |
593
+ | `webex.internal.newMetrics` (`UC-001` to `UC-004`) | Direct in-process calls, one per queued event, in queue order per category; behavioral drains before operational before business in `submitPendingEvents` | Behavioral names come from the taxonomy; operational and business names are `WXCC_SDK_*` wire names | Delivery and its failure behavior belong to the internal metrics plugin (Dependencies) |
594
+ | Host Webex SDK `ready` event | `webex.once('ready')` registered on bind; `webex.ready` checked first | Contract `webex-core-plugin-runtime` | Until ready, events stay in memory; they are lost if the page unloads first |
595
+
596
+ ### Customer console log triage (MMT / support)
597
+
598
+ Customers often embed with `logger.level: 'log'`. wxApp diagnostics use **`LoggerProxy.log`** / **`warn`** / **`error`** with prefix **`[CC wxApp]`** and grep-friendly `key=value` suffixes on the message string (fields also appear in structured `data`).
599
+
600
+ | Search in browser console | Meaning |
601
+ |---|---|
602
+ | `[CC wxApp]` | All wxApp diagnostic lines (primary search) |
603
+ | `WXCC_SDK_WXAPP` | Operational metric wire names (name only in console; payloads go to backend) |
604
+ | `session readiness` | usersub + Mercury state after station login |
605
+ | `offer decision` | Why Accept is visible/enabled; includes `acceptReason`, `hasDeviceCallId`, `usersubPublished` |
606
+ | `participant fields mismatch` | usersub active but WS participant **still** missing wxApp triple after ~500 ms (transient gaps on first OFFERED tick are normal — look for `wxApp_offer_ready` within 1 s) |
607
+ | `telephony accept failed` | REST answer failure; includes `trackingId` when available |
608
+
609
+ Do **not** search `WXAPP` alone — it matches metric wire names but misses `[CC wxApp]` diagnostic lines.
610
+
611
+ Example lines at `logger.level: 'log'`:
612
+
613
+ ```text
614
+ PLUGIN_CC - [LOG]: ... [CC wxApp] session readiness usersubPublished=true mercurySubscribed=true loginOption=EXTENSION ...
615
+ PLUGIN_CC - [LOG]: ... [CC wxApp] offer decision acceptReason=wxApp_offer_ready hasDeviceCallId=true usersubPublished=true interactionId=...
616
+ PLUGIN_CC - [WARN]: ... [CC wxApp] participant fields mismatch usersubPublished=true hasDeviceCallId=false acceptReason=extension_non_wxApp_offer interactionId=...
617
+ PLUGIN_CC - [LOG]: ... operational-events -> @submitEvent. Submit event: WXCC_SDK_WXAPP_TASK_ACCEPT_SUCCESS
618
+ ```
619
+
620
+ ## Client state model
621
+
622
+ MetricsManager holds three pending queues, running timing entries, a readiness flag, a submission lock, and an independent disabled flag. Host READY enables draining; disabling metrics prevents both timing and tracking and clears pending events through the configured disable path.
623
+
624
+ | State or slice | Owner | Initial state | Transition triggers | Reset or persistence boundary |
625
+ | --- | --- | --- | --- | --- |
626
+ | Singleton `instance` | `MetricsManager` class | `undefined` | First `getInstance` creates it | `resetInstance()`; memory only |
627
+ | `webex` | Instance | unset | First `getInstance({webex})` calls `setWebex` | Never replaced while set; cleared only with the instance |
628
+ | `runningEvents` | Instance | `{}` | `timeEvent` adds; tracking a matching key or `cancelTimedEvent` deletes | Not cleared by `setMetricsDisabled`; memory only |
629
+ | `pendingBehavioralEvents`, `pendingOperationalEvents`, `pendingBusinessEvents` | Instance | `[]` | `track*` pushes; a ready drain empties | `setMetricsDisabled(true)` clears all three; memory only |
630
+ | `readyToSubmitEvents` | Instance | `false` | Set to `true` when `setWebex()` finds `webex.ready` already true or when `webex.once('ready')` fires; events queue until then | Never reset to `false` |
631
+ | `submittingEvents` | Instance | `false` | Lock flag to prevent concurrent `submitPendingEvents()` calls; set at its start | Released in `finally` |
632
+ | `metricsDisabled` | Instance | `false` | `setMetricsDisabled(disabled)`; `true` also runs `clearPendingEvents()`, which empties all queues | Independent of readiness |
633
+
634
+ ## Business rules and invariants
635
+
636
+ | ID | Invariant | WHY | Enforcement source | Test evidence |
637
+ | --- | --- | --- | --- | --- |
638
+ | `INV-001` | `timeEvent` and every tracking method return immediately while metrics are disabled. | Disablement must be comprehensive (METRICS-R-003). | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` |
639
+ | `INV-002` | Only names present in `eventTaxonomyMap` receive behavioral taxonomy; 97 of 121 names are mapped and all 24 exceptions are explicitly catalogued as unmapped. | Undefined taxonomy must not be mistaken for a classified behavioral event (METRICS-R-002). | `src/metrics/behavioral-events.ts` | `test/unit/spec/metrics/behavioral-events.ts` |
640
+ | `INV-003` | The `submittingEvents` lock prevents overlapping, concurrent `submitPendingEvents()` queue-drain executions; each `track*` call drains its own queue directly. | A ready callback and a direct track call must not submit the same queued event twice; each drain copies and empties the queue before submitting. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` |
641
+ | `INV-004` | Authentication is inherited from the host Webex SDK's metrics client; MetricsManager owns no credentials, tokens, or authorization policy. | METRICS-R-005. | `src/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` |
642
+
643
+ ## Concurrency and reactive flow
644
+
645
+ - Execution model: one JavaScript event loop. Queue insertion is synchronous. Submission is gated by host readiness; the submission lock serializes the full `submitPendingEvents()` drain, and each metric type drains through its own host method without propagating telemetry failures to product callers.
646
+ - Ordering guarantees: events of one category are submitted in the order they were queued; there is no ordering across categories for direct `track*` drains.
647
+ - Idempotency and retry: none in this module (Dependencies).
648
+ - Shared-state protection: the singleton owns all state; each drain copies the queue and empties it before submitting, so a re-entrant track call queues into a fresh array.
649
+ - Blocking restrictions: no method awaits the network or throws; product code must never wait on telemetry.
650
+
651
+ ## State machine
652
+
653
+ ```mermaid
654
+ stateDiagram-v2
655
+ [*] --> Buffering
656
+ Buffering --> ReadyToSubmit: host already ready / ready event
657
+ ReadyToSubmit --> Submitting: pending events and lock acquired
658
+ Submitting --> ReadyToSubmit: queues drained and lock released
659
+ Buffering --> Disabled: setMetricsDisabled(true)
660
+ ReadyToSubmit --> Disabled: setMetricsDisabled(true)
661
+ Disabled --> Buffering: enabled before host ready
662
+ Disabled --> ReadyToSubmit: enabled after host ready
663
+ ```
664
+
665
+ No terminal state exists; `resetInstance()` discards the whole instance instead.
666
+
667
+ ## Pitfalls and constraints
668
+
669
+ - Never send an unmapped name to the behavioral category. `trackBehavioralEvent` queues `{taxonomy: undefined}`, and the next drain reads `event.taxonomy.product`, throws a `TypeError` inside the un-awaited async drain (an unhandled rejection, not a caller error), and drops the rest of that batch because the queue was already emptied. Every current caller tracks the 24 unmapped names with `['operational']` only.
670
+ - `setMetricsDisabled(true)` clears pending queues but does not create a delivery receipt; callers must not infer that previously submitted events were accepted.
671
+ - `trackEvent` passes the same payload object to each category. With a payload object, the first category writes `duration_ms` into that caller-owned object, so every category carries it; with no payload, only the first category gets `duration_ms`, because the timer is consumed. Pass a payload object (even `{}`) when a timed event goes to several categories.
672
+ - Wire names come from the values, not the keys: `WEBSOCKET_DEREGISTER_FAIL` is sent as `WXCC_SDK_WEBSOCKET_DEREGISTER_FAILED`, and `AI_SUMMARY_GET_POST_CALL_SUCCESS` as `WXCC_SDK_POST_CALL_SUMMARY_GET_SUCCESS`.
673
+ - `resetInstance()` does not remove the `ready` listener the discarded instance registered on `webex`, so that listener still fires on the old instance.
674
+
675
+ ## Module-specific rules
676
+
677
+ - DO use `METRIC_EVENT_NAMES` and the matching category submitter instead of constructing event names manually.
678
+ - DO keep timing success/failure keys together so either outcome clears the same running timer.
679
+ - DO add a new name to `src/metrics/constants.ts`, to the catalog in this spec, and, for a behavioral name, to `eventTaxonomyMap`; the map's comment also asks authors to add new metrics to the Cypher CC metrics wiki.
680
+ - DO use `cancelTimedEvent` with the same keys when an operation is abandoned without an outcome.
681
+ - DON'T add a behavioral taxonomy entry unless the backend taxonomy contract exists.
682
+ - DON'T make product behavior depend on metrics delivery.
683
+ - DON'T put raw participant IDs, numbers, names, URLs, or wellness payloads in metric payloads; use booleans, enums, and correlation IDs.
684
+
685
+ ## Key design trade-off
686
+
687
+ | Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
688
+ | --- | --- | --- | --- |
689
+ | Buffer events in memory and hand them off without waiting, instead of awaiting delivery or surfacing telemetry errors | Product calls never fail or slow down because of metrics; early events survive until the host is ready | No delivery guarantee or receipt; queued events are lost on unload or when metrics are disabled | `src/metrics/MetricsManager.ts` |
690
+ | One process-wide singleton bound to the first `webex` | Every module shares timers and queues without passing the manager around | Tests must call `resetInstance()`; a second SDK instance in one page reports through the first | `src/metrics/MetricsManager.ts` |
691
+
692
+ ## Verification
693
+
694
+ Use `test/unit/spec/metrics/MetricsManager.ts` for readiness queues, timing/tracking, disabled behavior, submission categories, and failures. Use `test/unit/spec/metrics/behavioral-events.ts` to reconcile every taxonomy-backed name. Mechanically compare the complete constant catalog with taxonomy keys so newly defined events cannot disappear from the spec.
695
+
696
+ | Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
697
+ | --- | --- | --- | --- | --- |
698
+ | `METRICS-R-001` | None (compile-time type check only) | None found (compile-time type check only) | None found | Add a catalog parity assertion if constants change. |
699
+ | `METRICS-R-002`, `INV-002` | Unit | `test/unit/spec/metrics/behavioral-events.ts` | None found | Only 31 mapped names are asserted; add coverage for the 24 unmapped names. |
700
+ | `METRICS-R-003`, `INV-001` | Unit | `test/unit/spec/metrics/MetricsManager.ts` | `test/unit/spec/metrics/MetricsManager.ts` disabled cases for each track method, timeEvent, and cancelTimedEvent | None. |
701
+ | `METRICS-R-004` | Unit | `test/unit/spec/metrics/MetricsManager.ts` readiness and queue cases | `test/unit/spec/metrics/MetricsManager.ts` queue-without-webex case | None. |
702
+ | `METRICS-R-005`, `INV-004` | Unit | `test/unit/spec/metrics/MetricsManager.ts` | None found | Authentication ownership is verified indirectly through the host metrics client. |
703
+ | `METRICS-R-006` | Unit (consumer) | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` invalid wellness notification cases | Action and idle-code metrics are not asserted by name; `test/unit/spec/services/ApiAiAssistant.ts` only stubs `trackEvent`. |
704
+ | `METRICS-R-007` | Unit | `test/unit/spec/metrics/MetricsManager.ts` timer and duration cases | `test/unit/spec/metrics/MetricsManager.ts` cancel and untimed cases | The empty-array log is not asserted. |
705
+ | `METRICS-R-008`, `METRICS-R-010` | Unit | `test/unit/spec/metrics/MetricsManager.ts` three-category case | `test/unit/spec/metrics/MetricsManager.ts` invalid-type case | None. |
706
+ | `METRICS-R-009` | Unit (partial) | `test/unit/spec/metrics/MetricsManager.ts` | None found | Empty-value stripping, key rewriting, and `tabHidden` are not asserted. |
707
+ | `METRICS-R-011` | Unit | `test/unit/spec/metrics/MetricsManager.ts` nested and flat AQM cases | `test/unit/spec/metrics/MetricsManager.ts` missing-field cases | None. |
708
+ | `INV-003` | Unit | `test/unit/spec/metrics/MetricsManager.ts` lock case | None found | None. |
709
+
710
+ Run `yarn workspace @webex/contact-center build:src` and `yarn workspace @webex/contact-center test:unit` from the workspace root. On 2026-11-16 the two metrics test files passed 33 of 33 jest cases. A module specification is complete only when its public surface, invariants, failure modes, and test evidence agree with the implementation; this module stays Partial until a fresh coverage review and independent validation run.