Add Genesys Cloud MOS integration by edferron-dd · Pull Request #3057 · DataDog/integrations-extras

edferron-dd · 2026-07-10T02:57:40Z

What does this PR do?

Adds a new Genesys Cloud MOS Agent integration to integrations-extras.

The check reports Genesys Cloud conversation call quality — the Mean Opinion Score (MOS) — to Datadog. It queries ended conversations on a trailing interval via the Analytics Conversation Detail Query API (mediaStatsMinConversationMos dimension) using an OAuth client-credentials grant, and emits:

genesys_mos.conversation.mos.avg / genesys_mos.conversation.mos.min (gauge)
genesys_mos.conversation.count (gauge)
genesys_mos.conversation.below_threshold.count (gauge)
genesys_mos.can_connect (service check)

Motivation

Give voice/contact-center teams visibility into perceived call quality directly in Datadog, with dashboards and a monitor for low average MOS.

Agent check (datadog_checks/genesys_mos/) with config models and conf.yaml.example
manifest.json, metadata.csv, assets/ (dashboard, monitor, service_checks), config spec.yaml
README with setup, secrets-management (Agent file.json backend), and troubleshooting
Unit tests and integration tests — the integration tests replay documented Genesys API payloads through the real PureCloudPlatformClientV2 SDK deserializer, covering pagination, cross-page dedupe, the outgoing query contract, and threshold math
CODEOWNERS and CI test-matrix entries

Review checklist

Unit tests pass (ddev test genesys_mos)
Integration tests pass
ddev validate all genesys_mos passes for all integration-specific validators
README, manifest, spec.yaml, and service check definitions complete

🤖 Generated with Claude Code

New extras integration that reports Genesys Cloud conversation call quality (Mean Opinion Score) to Datadog. The Agent check queries ended conversations through the Analytics Conversation Detail Query API and emits average/min MOS, conversation counts, a below-threshold count, and a can_connect service check. Includes unit and integration tests (documented API payloads replayed through the Genesys SDK deserializer), dashboard, monitor, metadata, and config spec. Registers the integration in CODEOWNERS and the CI test matrix. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- manifest.json: add required internal owner field (integrations-developer-platform) - assets/monitors/low_average_mos.json: use date (YYYY-MM-DD) for created_at/last_updated_at - CHANGELOG.md: use asterisk bullet per changelog guidelines - apply ruff format/lint (line-length 120) across check and tests Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Sort imports with datadog_checks as first-party, matching the ruff config ruff runs from within the integration directory in CI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CI always runs 'ddev env test' (the e2e phase). With no dd_environment fixture it errors 'NO E2E FIXTURE AVAILABLE' (exit 2). This integration has no self-hostable dependency, so add a no-op session fixture; the e2e phase then collects zero tests and exits cleanly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The minimum-base-package CI job installs the declared floor. At 32.0.0 its pinned transitive pyyaml==6.0 fails to build on py3.12 (cython_sources error). 37.20.0 is the current new-integration baseline and builds cleanly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add a unit test that loads InstanceConfig/SharedConfig via the base check_initializations path. The generated config_models were previously unexercised (0%), pulling project coverage under the 75% target; total coverage is now ~96%. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

validate-monitors requires the integration tag value to be a valid app_id. Use 'integration:genesys-mos' (matching manifest app_id) instead of the metric-namespace form 'genesys_mos'. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- README: sentence-case 'Data collected' / 'Service checks' headings - README: drop em-dashes and spell out 'approximately' in the overview - README: point Support at the community maintainer, not Datadog support - Monitor: expand MOS acronym and explain why the alert matters Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

validate-monitors caps the description at <300 chars. Shorten while keeping the MOS explanation and alert rationale. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-authored-by: jeff-morgan-dd <jeff.morgan@datadoghq.com>

Review from jeff-morgan-dd is dismissed. Related teams and files:

documentation
- genesys_mos/README.md
- genesys_mos/assets/monitors/low_average_mos.json

edferron-dd · 2026-07-17T18:16:36Z

@DataDog/alerting-product what needs to be done to move this forward?

Rename the dashboard key to 'genesys-cloud-mos-overview' so it already matches the normalized short name used for the built-in dashboard URL. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Review from jeff-morgan-dd is dismissed. Related teams and files:

documentation
- genesys_mos/manifest.json

Per review, the dashboard key should be lowercase snake_case: genesys_cloud_mos_overview. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

sarah-witt

Thanks for the PR!

sarah-witt · 2026-07-17T18:46:21Z

+        """Authenticate with the client-credentials grant and return an AnalyticsApi.
+        A fresh token is fetched each run, so no long-lived refresh logic is needed.
+        Isolated for testability (patched in unit tests)."""
+        import PureCloudPlatformClientV2 as genesys


Question- why do you import this inside the function?

It's a deliberate lazy import: the SDK is a third-party dependency that is not bundled with the wheel, so importing at module load would stop the check from loading at all when it is missing (and would prevent emitting can_connect=0). It also lets the unit tests inject a stub via sys.modules without the real SDK installed. Happy to move it to module scope if you'd prefer.

🤖 Addressed by Claude Code

- check.py: report connectivity as the genesys_mos.can_connect gauge (1/0) instead of a service check; add it to metadata.csv and empty service_checks.json - README: add a manual step to install the PureCloudPlatformClientV2 dependency into the Agent's embedded env (the wheel install does not pull deps); document can_connect under Service checks and Troubleshooting - spec.yaml: mark client_secret as secret so it is hidden from Agent output - tests: assert the can_connect metric and validate metrics against metadata.csv via assert_metrics_using_metadata(get_metadata_metrics()) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

stevenkline

LGTM

estherk15

Approved for documentation

jcmaunsell

As discussed offline, we should improve the existing Genesys integration in the integrations-core repo rather than adding a community integration here. Also, this PR's proposed integration dashboard is only four widgets that should probably be added to an existing Genesys integration dashboard instead.

edferron-dd · 2026-07-20T19:57:36Z

@jcmaunsell agreed on merging this into the main integration. Can I do that PR?

jcmaunsell · 2026-07-20T20:52:22Z

@edferron-dd Yes - but you should work with the saas-integrations team on this change, since they own the integration

edferron-dd requested review from a team as code owners July 10, 2026 02:57

edferron-dd and others added 6 commits July 9, 2026 22:14

Fix import sorting (ruff I001) in tests

4fa975a

Sort imports with datadog_checks as first-party, matching the ruff config ruff runs from within the integration directory in CI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Fix monitor integration tag to match app_id

6b9b8f2

validate-monitors requires the integration tag value to be a valid app_id. Use 'integration:genesys-mos' (matching manifest app_id) instead of the metric-namespace form 'genesys_mos'. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

estherk15 reviewed Jul 10, 2026

View reviewed changes

estherk15 self-assigned this Jul 10, 2026

edferron-dd and others added 2 commits July 10, 2026 09:40

Trim monitor description under 300-char limit

7b265e6

validate-monitors caps the description at <300 chars. Shorten while keeping the MOS explanation and alert rationale. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jeff-morgan-dd self-assigned this Jul 14, 2026

jeff-morgan-dd previously approved these changes Jul 14, 2026

View reviewed changes

Comment thread genesys_mos/README.md Outdated

Comment thread genesys_mos/assets/monitors/low_average_mos.json Outdated

Apply suggestions from code review

3be1f78

Co-authored-by: jeff-morgan-dd <jeff.morgan@datadoghq.com>

jeff-morgan-dd previously approved these changes Jul 14, 2026

View reviewed changes

Merge branch 'master' into add-genesys-mos-integration

a260154

jcmaunsell reviewed Jul 17, 2026

View reviewed changes

Comment thread genesys_mos/manifest.json Outdated

Normalize dashboard manifest key to kebab-case

a5bb3d6

Rename the dashboard key to 'genesys-cloud-mos-overview' so it already matches the normalized short name used for the built-in dashboard URL. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

jcmaunsell reviewed Jul 17, 2026

View reviewed changes

Comment thread genesys_mos/manifest.json Outdated

Use snake_case dashboard manifest key

842f705

Per review, the dashboard key should be lowercase snake_case: genesys_cloud_mos_overview. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

sarah-witt reviewed Jul 17, 2026

View reviewed changes

stevenkline approved these changes Jul 17, 2026

View reviewed changes

estherk15 approved these changes Jul 20, 2026

View reviewed changes

estherk15 unassigned estherk15 and jeff-morgan-dd Jul 20, 2026

estherk15 requested review from jcmaunsell and sarah-witt July 20, 2026 13:34

jcmaunsell requested changes Jul 20, 2026

View reviewed changes

Uh oh!

Conversation

edferron-dd commented Jul 10, 2026

What does this PR do?

Motivation

Contents

Review checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edferron-dd commented Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

sarah-witt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah-witt Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

edferron-dd Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stevenkline left a comment

Choose a reason for hiding this comment

Uh oh!

estherk15 left a comment

Choose a reason for hiding this comment

Uh oh!

jcmaunsell left a comment

Choose a reason for hiding this comment

Uh oh!

edferron-dd commented Jul 20, 2026

Uh oh!

jcmaunsell commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants