Explain Endpoint Agent Health with Explainability Logging - Open Beta
Endpoint Agent Explainability Logging helps you understand whether an Endpoint Agent can collect telemetry and run tests. Instead of showing only that an agent is registered, the ThousandEyes platform reports the agent's health state, the reason for that state, the impact, and the recommended action.
Explainability information is available in Endpoint Experience > Agent Settings. You can also export the information for support and access the same fields through external APIs.
Prerequisites
To view Endpoint Agent settings and generate support bundles, you need a ThousandEyes account with the required admin permissions.
Understanding Explainability Logging
For each agent, Explainability Logging reports the following information:
State
The current health state of the agent. Supported states include Active, Inactive, Degraded, and DeploymentFailed.
Reason
A human-readable explanation and, where available, a stable reason code for the blocker.
Impact
The telemetry or agent function that might be unavailable, such as test scheduling, telemetry collection, or network context.
Recommended action
The remediation that addresses the reported blocker.
Evidence
Bounded, timestamped checks and key fields that support the reported state. Explainability Logging does not expose unrestricted device logs.
Health history
A per-agent record of health-state changes that helps you identify when an issue started.
The state describes the overall condition, while the reason and impact explain what needs attention. An agent can be registered with the ThousandEyes platform and still report an issue that prevents it from running tests or collecting some telemetry.
Viewing Agent Health
In the ThousandEyes platform, go to Endpoint Experience > Agent Settings.
Select an agent.
The agent details panel opens. Any current Explainability Logging findings appear at the top of the panel. Each finding includes the state, the reason, the impact, and an action.
Review the reported action and correct the relevant device, operating system, mobile device management (MDM), or original equipment manufacturer (OEM) configuration.
Return to the agent details panel and confirm that the current findings and state reflect the change.
Reviewing Common Health Reasons
Explainability Logging uses stable reason codes for common blockers. The following reason codes are included in the current feature definition:
ACCESS_BACKGROUND_LOCATION_PERMISSION_MISSING
Degraded
Background location permission is missing.
ACCESS_FINE_LOCATION_PERMISSION_MISSING
Degraded
Precise location permission is missing.
APP_IN_STANDBY_BUCKET_RESTRICTED
Degraded
App activity is restricted in standby.
BACKGROUND_EXECUTION_RESTRICTED
Degraded
Background activity is restricted.
BATTERY_OPTIMIZATION_ENABLED
Degraded
Battery optimization is enabled.
CHROME_OS_FOREGROUND_SERVICE_NOT_RUNNING
Degraded
The ChromeOS foreground service is not running.
DEVICE_NOT_FULLY_MANAGED
Degraded
The device is not fully managed.
LOCATION_SERVICES_DISABLED
Degraded
Location services are turned off.
MDM_POLICY_RESTRICTING_AGENT
Degraded
An MDM policy might be restricting the agent.
MISSING_REQUIRED_PERMISSIONS
Degraded
Required permissions are missing.
OEMCONFIG_APPLY_FAILED
Degraded
OEMConfig settings could not be applied.
OEMCONFIG_INCOMPATIBLE_VERSION
Degraded
The device manufacturer's OEMConfig configuration does not support application auto-launch on Android 13 or earlier.
OEMCONFIG_INCOMPATIBLE_VERSION
Incompatible
The device manufacturer's OEMConfig version is incompatible.
OEMCONFIG_NOT_INSTALLED
Degraded
The device manufacturer's OEMConfig application is not installed.
READ_PHONE_STATE_PERMISSION_MISSING
Degraded
Phone state permission is missing.
SCHEDULE_EXACT_ALARM_NOT_ALLOWED
Degraded
Exact alarm scheduling is not granted.
SCHEDULER_NOT_RUNNING
Degraded
Agent check-in is overdue.
SERVICE_THROTTLED_OR_KILLED
Degraded
The agent service was limited or stopped.
UNKNOWN
Degraded
A diagnostic check failed unexpectedly.
The OEMCONFIG_INCOMPATIBLE_VERSION reason code currently has two definitions with different states. Confirm the final product payload before publishing this article if these definitions are consolidated or renamed.
The platform might report a different reason when evidence changes. Use the current reason, impact, and recommended action as the source of truth for the agent's current condition.
Reviewing Deployment and Enrollment Details
For Mobile Endpoint Agents on Android, the agent details panel can include deployment and enrollment information such as:
Install method.
Install source.
Management mode.
MDM vendor.
Whether OEMConfig is installed.
Whether OEMConfig is applied.
This information helps you distinguish a registration problem from a device-management or OEM configuration problem. For example, an agent might register successfully while OEMConfig is not installed or has not been applied.
Viewing Onboarding Health History
Onboarding Health History records changes to an agent's onboarding health state.
Open the agent details panel from Endpoint Experience > Agent Settings.
Scroll to Device Details.
Select View Onboarding Health History.
The dialog lists health findings with their state, reason, timestamp, summary, impact, and action. Expand a finding to view its details.
Use the history to determine when a permission, scheduling, battery, OEMConfig, or other configuration issue first appeared. The history reports the agent's observed changes; it does not change the device configuration.
Using Explainability Information for Troubleshooting
Use the following workflow when an agent is registered but does not behave as expected:
Confirm that the agent runs a supported version.
Open the agent in Endpoint Experience > Agent Settings.
Read the current state and reason before collecting raw device logs.
Review the impact to determine whether the issue affects test scheduling, telemetry collection, location or Wi-Fi context, service execution, or another supported capability.
Apply the recommended action on the device or in the relevant MDM, OEM, firewall, or operating system configuration.
Review the agent's current state and Onboarding Health History to confirm whether the finding changes.
If the issue persists, include the Explainability Report in the support bundle or provide the explainability fields through your external API workflow.
Explainability Logging reduces the need to infer the cause from an agent's registered status or from unstructured logs. It does not remove the need to check the device or its management configuration when the recommended action requires a device-side change.
Exporting Explainability Information
Explainability information is available through the following support workflows:
Support bundles can include an Explainability Report with the state, reason, impact, and health history.
External APIs expose the same explainability fields for downstream troubleshooting and automation.
The available fields depend on the agent platform and the evidence that the agent can collect. Treat unavailable fields as unavailable data, not as proof that the corresponding device condition is clear.
Understanding Platform Differences
Mobile Endpoint Agents collect a different set of telemetry from desktop Endpoint Agents. Explainability Logging identifies platform limitations and missing signals where they affect agent health or the collected data.
For example, mobile agents might report missing permissions, blocked background execution, unavailable exact alarm scheduling, OEMConfig problems, or service termination. Desktop agents provide a different set of operating-system and service signals. The platform-specific data model does not mean that every health reason is available on every platform.
Related Articles
Last updated