@webex/contact-center 3.13.0-next.1 → 3.13.0-next.10
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.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1065 -339
- package/AGENTS.md +935 -60
- package/dist/webex.js +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +10 -9
- package/schemas/repo-context.schema.json +796 -0
- package/src/docs/README.md +727 -0
- package/src/metrics/docs/README.md +710 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/docs/README.md +530 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/docs/README.md +765 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/utils/AGENTS.md +6 -4
- package/src/utils/docs/README.md +413 -0
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/ai-docs/ARCHITECTURE.md +0 -168
- package/ai-docs/CONTRACTS.md +0 -64
- package/ai-docs/GETTING_STARTED.md +0 -168
- package/ai-docs/GLOSSARY.md +0 -43
- package/ai-docs/README.md +0 -138
- package/ai-docs/REVIEW_CHECKLIST.md +0 -41
- package/ai-docs/RULES.md +0 -444
- package/ai-docs/SECURITY.md +0 -52
- package/ai-docs/SERVICE_STATE.md +0 -52
- package/ai-docs/SPEC_INDEX.md +0 -65
- package/ai-docs/adr/0001-spec-source-policy.md +0 -55
- package/ai-docs/adr/README.md +0 -8
- package/ai-docs/adr/_adr-template.md +0 -31
- package/ai-docs/contact-center-spec.md +0 -388
- package/ai-docs/features/contact-owner-change-refactor.md +0 -78
- package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
- package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
- package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
- package/ai-docs/patterns/event-driven-patterns.md +0 -485
- package/ai-docs/patterns/testing-patterns.md +0 -480
- package/ai-docs/patterns/typescript-patterns.md +0 -365
- package/ai-docs/templates/README.md +0 -102
- package/ai-docs/templates/documentation/create-agents-md.md +0 -240
- package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
- package/ai-docs/templates/existing-service/bug-fix.md +0 -254
- package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
- package/ai-docs/templates/new-method/00-master.md +0 -80
- package/ai-docs/templates/new-method/01-requirements.md +0 -232
- package/ai-docs/templates/new-method/02-implementation.md +0 -295
- package/ai-docs/templates/new-method/03-tests.md +0 -201
- package/ai-docs/templates/new-method/04-validation.md +0 -141
- package/ai-docs/templates/new-service/00-master.md +0 -109
- package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
- package/ai-docs/templates/new-service/02-code-generation.md +0 -346
- package/ai-docs/templates/new-service/03-integration.md +0 -178
- package/ai-docs/templates/new-service/04-test-generation.md +0 -205
- package/ai-docs/templates/new-service/05-validation.md +0 -145
- package/src/metrics/ai-docs/AGENTS.md +0 -350
- package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
- package/src/metrics/ai-docs/metrics-spec.md +0 -971
- package/src/services/agent/ai-docs/AGENTS.md +0 -240
- package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
- package/src/services/agent/ai-docs/agent-spec.md +0 -505
- package/src/services/ai-docs/AGENTS.md +0 -386
- package/src/services/ai-docs/services-spec.md +0 -512
- package/src/services/config/ai-docs/AGENTS.md +0 -250
- package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
- package/src/services/config/ai-docs/config-spec.md +0 -669
- package/src/services/core/ai-docs/AGENTS.md +0 -381
- package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
- package/src/services/core/ai-docs/core-spec.md +0 -797
- package/src/services/task/ai-docs/AGENTS.md +0 -457
- package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
- package/src/services/task/ai-docs/task-spec.md +0 -1501
- package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
- 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.
|