[Synthetics] Detect and display missing/corrupted Synthetics integrations in monitor UIs

[miguelmartin-elastic]

Release note

Synthetics monitor integration health detection and self-healing

Synthetics now automatically detects when private location monitors have broken Fleet integrations — such as deleted agent or package policies and missing locations — and surfaces per-location health status directly in the monitor management list, monitor edit page, and private locations settings. Users can reset affected monitors individually or in bulk to recreate the missing Fleet resources and restore monitoring.

Summary

Closes #256397
Closes #256398
Closes #256399

Adds a new Monitor Integration Health API for Synthetics that detects and reports unhealthy monitor/private-location configurations, and surfaces these health statuses in the UI with actionable per-location details and reset capabilities.

Problem

When a Synthetics monitor uses a private location, several Fleet-level resources (package policies, agent policies, the synthetics package itself) must be in place for the monitor to run. If any of these resources are missing or misconfigured, the monitor silently fails to collect data. Users have no clear signal about what went wrong or which location is affected.

Solution

Backend: MonitorIntegrationHealthApi service

A new MonitorIntegrationHealthApi service class that evaluates the health of monitors across their private locations. It detects 5 distinct failure scenarios, evaluated in intentional priority order (most fundamental issue first):

Priority	Status	Description
1	missing_location	The monitor references a private location that no longer exists
2	missing_agent_policy	The agent policy referenced by the private location was deleted
3	missing_package_policy	The Fleet package policy for this monitor/location pair is missing

Only the first matching status is reported per location, since the higher-priority issue is the root cause (e.g., if the agent policy is deleted, reporting missing_package_policy on its package policies would be misleading — the fix is the same regardless).

The service supports both new ({configId}-{locationId}) and legacy ({configId}-{locationId}-{spaceId}) policy ID formats using getPolicyIdFormatInfo, preventing false-positive missing_package_policy reports for monitors created before the space-agnostic migration.

Two new internal endpoints expose this:

• POST /internal/synthetics/monitors/_health — Bulk health check (up to 500 monitor IDs)
• GET /internal/synthetics/monitors/{monitorId}/_health — Single monitor health check (returns 404 if the monitor doesn't exist)

You can check the OAS here api.yml

The service uses Promise.allSettled for partial error handling: if some monitors fail to load, the response includes both the successful health results and per-monitor errors with proper statusCode propagation.

Frontend: useMonitorIntegrationHealth hook + Redux slice

A new monitor_health Redux slice fetches health data from the bulk API. The saga uses debounce(50ms) to aggregate rapid dispatches from multiple hook instances into a single API call. The useMonitorIntegrationHealth hook provides:

• isUnhealthy(configId) — boolean check for a specific monitor
• getUnhealthyLocationStatuses(configId) — per-location details with translated reasons
• getUnhealthyMonitorCountForLocation(locationId) — count of unhealthy monitors per location
• getUnhealthyConfigIdsForLocation(locationId) — config IDs of unhealthy monitors at a location
• resetMonitor(configId) — triggers a single monitor reset via the reset API
• resetMonitors(configIds) — triggers a bulk monitor reset via the bulk reset API

UI changes

• Monitor management list table: Warning icon with tooltip showing per-location health reasons
• Monitor edit page: Warning callout listing affected locations with a "Reset monitor" button
• Private locations settings: Badge showing count of unhealthy monitors per location, with a "Reset monitors" button per location
• Bulk operations: Bulk reset action for selected unhealthy monitors (both in monitor list and private locations table)
• Reset confirmation modal: ResetMonitorModal component with confirmation dialog, loading state, and success/error toast notifications
• Toast notifications: Success and error feedback after individual and bulk reset operations

API response examples

Bulk endpoint (POST /internal/synthetics/monitors/_health):

{
  "monitors": [
    {
      "configId": "a04dd21...",
      "monitorName": "https://www.elastic.co",
      "isUnhealthy": false,
      "locations": [
        {
          "locationId": "80ad4fda...",
          "locationLabel": "My Private Location",
          "status": "healthy",
          "policyId": "a04dd21...-80ad4fda..."
        }
      ]
    },
    {
      "configId": "6249a8b4...",
      "monitorName": "Test Unhealthy Monitor",
      "isUnhealthy": true,
      "locations": [
        {
          "locationId": "80ad4fda...",
          "locationLabel": "My Private Location",
          "status": "missing_package_policy",
          "policyId": "6249a8b4...-80ad4fda...",
          "reason": "The Fleet package policy for this monitor/location pair does not exist."
        }
      ]
    }
  ],
  "errors": []
}

Single endpoint (GET /internal/synthetics/monitors/{monitorId}/_health):

{
  "configId": "6249a8b4...",
  "monitorName": "Test Unhealthy Monitor",
  "isUnhealthy": true,
  "locations": [
    {
      "locationId": "80ad4fda...",
      "locationLabel": "My Private Location",
      "status": "missing_package_policy",
      "policyId": "6249a8b4...-80ad4fda...",
      "reason": "The Fleet package policy for this monitor/location pair does not exist."
    }
  ]
}

Some screenshots may be outdated!

Screenshots

Monitor List (unhealthy warning icon)	Private Locations (unhealthy count badge)

Monitor Edit (missing integration callout)

Test plan

You can use this script for creating unhealthy monitor locally: break_monitors.sh, just replace the location id and kibana url

Prerequisites

1. Start Elasticsearch and Kibana locally
2. Navigate to Observability > Synthetics > Settings > Private Locations and create a private location (requires a Fleet agent policy)
3. Create at least one Synthetics monitor (HTTP or browser) assigned to the private location

Scenario 1: Verify healthy monitor

• Open the monitor list page — the monitor should not show a warning icon
• Call GET /internal/synthetics/monitors/{monitorId}/_health — all locations should be "status": "healthy"

Scenario 2: Simulate missing_package_policy

• Go to Fleet > Agent policies, find the agent policy used by the private location
• Expand the policy, find the synthetics package policy for your monitor, and delete it (use POST /api/fleet/package_policies/delete with force: true if needed)
• Refresh the monitor list — a warning icon should appear next to the affected monitor
• Hover the icon — tooltip should show the location name and reason ("The Fleet package policy for this monitor/location pair does not exist.")
• Navigate to the monitor edit page — a warning callout should appear with per-location details and a "Reset monitor" button
• Call the bulk API: POST /internal/synthetics/monitors/_health with {"monitorIds": ["<configId>"]} — response should show "status": "missing_package_policy" with a reason

Scenario 3: Simulate missing_agent_policy

• Delete the agent policy referenced by the private location via Fleet API
• Refresh the monitor list — warning icon should appear
• Call the health API — response should show "status": "missing_agent_policy"

Scenario 4: Verify private locations settings page

• Navigate to Synthetics > Settings > Private Locations
• If any monitor is unhealthy, the location row should display a badge like "1 unhealthy"
• The location should also show a "Reset monitors" button

Scenario 5: Reset a single monitor (edit page)

• On the monitor edit page, click "Reset monitor" in the warning callout
• Verify the success callout appears: "Monitor reset successfully"
• Refresh the page — the warning callout should be gone (if the reset resolved the issue)

Scenario 6: Bulk reset monitors (monitor list)

• Select multiple unhealthy monitors using the checkboxes in the monitor list
• Click the "Reset N monitors" button in the bulk actions bar
• A confirmation modal should appear listing the number of monitors to reset
• Click "Reset" — verify a success toast appears ("N monitors reset successfully")
• Refresh the page — the warning icons should be gone for reset monitors

Scenario 7: Reset monitors from private locations page

• Navigate to Synthetics > Settings > Private Locations
• Click "Reset monitors" on a location with unhealthy monitors
• A confirmation modal should appear
• Click "Reset" — verify a success toast appears
• The unhealthy count badge should update

Scenario 8: Legacy policy ID format

• If you have monitors created before the space-agnostic policy ID migration (with format {configId}-{locationId}-{spaceId}), verify they are not falsely reported as missing_package_policy
• Call the health API for such a monitor — it should return "status": "healthy"

Scenario 9: Partial errors

• Call the bulk API with a mix of valid and invalid monitor IDs: {"monitorIds": ["valid-id", "nonexistent-id"]}
• Verify the response includes both a monitors entry for the valid ID and an errors entry with statusCode: 404 for the invalid one

Scenario 10: Verify the single endpoint 404 handling

• Call GET /internal/synthetics/monitors/nonexistent/_health
• Verify it returns HTTP 404 with a message

Risk assessment

Low — this is an additive feature. No existing API contracts or data models are modified. The new endpoints are internal-only and the UI changes are isolated to the Synthetics management pages.

[miguelmartin-elastic]

/ci

[miguelmartin-elastic]

/ci

[miguelmartin-elastic]

/ci

[miguelmartin-elastic]

@benakansara

Re: layout issue in the private locations table:

The root cause is that the Delete
action uses a render-based approach in the EUI actions column, which EUI
treats differently from standard type: 'icon' actions — they end up in
separate DOM containers and stack vertically. Fixing it cleanly would
require restructuring the actions column (separating the Delete modal from
its trigger and reworking the isPrimary setup across all three actions).
Since this is a pre-existing layout issue unrelated to the core changes in
this PR, I'd prefer to address it in a follow-up to keep this one focused

The rest of comments have been addressed 😃

[benakansara]

@benakansara

Re: layout issue in the private locations table:

The root cause is that the Delete
action uses a render-based approach in the EUI actions column, which EUI
treats differently from standard type: 'icon' actions — they end up in
separate DOM containers and stack vertically. Fixing it cleanly would
require restructuring the actions column (separating the Delete modal from
its trigger and reworking the isPrimary setup across all three actions).
Since this is a pre-existing layout issue unrelated to the core changes in
this PR, I'd prefer to address it in a follow-up to keep this one focused

The rest of comments have been addressed 😃

@miguelmartin-elastic Thanks for the explanation. Upon closer look, it seems that the layout issue happens when there are more than 2 actions. Since in this PR, we are adding a third action, it overflows and creates layout issue. Below is the screenshot from main. I think its ok to restructure the delete action from render to icon format and using same pattern as reset modal for delete modal.

[miguelmartin-elastic]

I think its ok to restructure the delete action from render to icon format and using same pattern as reset modal for delete modal.

@benakansara fixed 🚀

[benakansara]

LGTM! 🚀 Just one comment about using JSON.stringify

[benakansara]

do we need JSON.stringify?

Suggested change

	// eslint-disable-next-line react-hooks/exhaustive-deps
	}, [dispatch, JSON.stringify(configIds)]);
	}, [dispatch, configIds]);

[miguelmartin-elastic]

Nope. Fixed now :)

[macroscopeapp]

🟢 Low monitor_filters/use_filters.ts:67

The useEffect for configIds only dispatches to updateManagementPageStateAction but not setOverviewPageStateAction, while the useLogicalAndFor effect immediately after it dispatches to both. Since MonitorOverviewPageState extends MonitorFilterState which includes configIds, the overview page state won't receive configIds updates from URL params, causing the overview page filtering to be out of sync with the URL.

-  useEffect(() => {
-    dispatch(updateManagementPageStateAction({ configIds }));    
-  }, [dispatch, configIds]);
+  useEffect(() => {
+    dispatch(updateManagementPageStateAction({ configIds }));
+    dispatch(setOverviewPageStateAction({ configIds }));
+  }, [dispatch, configIds]);

🤖 Copy this AI Prompt to have your agent fix this:

In file x-pack/solutions/observability/plugins/synthetics/public/apps/synthetics/components/monitors_page/common/monitor_filters/use_filters.ts around lines 67-69:

The `useEffect` for `configIds` only dispatches to `updateManagementPageStateAction` but not `setOverviewPageStateAction`, while the `useLogicalAndFor` effect immediately after it dispatches to both. Since `MonitorOverviewPageState` extends `MonitorFilterState` which includes `configIds`, the overview page state won't receive `configIds` updates from URL params, causing the overview page filtering to be out of sync with the URL.

Evidence trail:
1. x-pack/solutions/observability/plugins/synthetics/public/apps/synthetics/components/monitors_page/common/monitor_filters/use_filters.ts lines 62-64: configIds effect only dispatches updateManagementPageStateAction
2. use_filters.ts lines 66-76: useLogicalAndFor effect dispatches to both setOverviewPageStateAction and updateManagementPageStateAction
3. x-pack/solutions/observability/plugins/synthetics/public/apps/synthetics/state/monitor_list/models.ts line 27: MonitorFilterState includes configIds
4. x-pack/solutions/observability/plugins/synthetics/public/apps/synthetics/state/overview/models.ts line 15: MonitorOverviewPageState extends MonitorFilterState
5. x-pack/solutions/observability/plugins/synthetics/public/apps/synthetics/utils/filters/filter_fields.ts line 29: getMonitorFilterFields() does NOT include configIds

[elasticmachine]

💛 Build succeeded, but was flaky

• Buildkite Build
• Commit: c96927e

Failed CI Steps

• Jest Tests #2

Test Failures

• [job] [logs] Jest Tests #2 / should call onSelectionChange on user selection

Metrics [docs]

Module Count

Fewer modules leads to a faster build time

id	before	after	diff
synthetics	1264	1276	+12

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
synthetics	1.1MB	1.1MB	+13.3KB

History

• 💔 Build #422597 failed 8f981fe
• 💔 Build #422549 failed f0159d3
• 💔 Build #422523 failed 9d0640b
• 💔 Build #420971 failed c3e738f
• 💔 Build #420964 failed a072b11