Support for telemetry diagnostics
Overview
Telemetry Diagnostics helps administrators identify and troubleshoot issues that prevent telemetry data from being successfully collected and uploaded from managed NetScaler® instances.
The feature provides visibility into:
-
Telemetry execution status across all managed instances.
-
Device-level diagnostics — per-instance state, SSH status, and error details.
-
Agent-level diagnostics — execution time, package version, and service reachability.
-
Live connectivity validation against telemetry-related endpoints.
Note:
In NetScaler Console Service, telemetry collection is fully automated. The mode is always set to Automated — telemetry data collection occurs automatically without requiring manual intervention.
Benefits
Using Telemetry Diagnostics, administrators can:
-
Verify whether telemetry collection is running successfully across the managed estate.
-
Identify specific NetScaler devices or agents experiencing telemetry failures.
-
View diagnostic error codes and associated error messages.
-
Determine whether failures stem from NetScaler device connectivity, SSH communication, agent connectivity, or telemetry upload issues.
-
Validate live connectivity to telemetry-related services and endpoints.
-
Access a complete error code reference with recommended mitigation actions.
Accessing Telemetry Diagnostics
Prerequisites
Before accessing the telemetry diagnostics interface, ensure that:
-
You have administrative credentials to log into NetScaler Console Service.
-
At least one NetScaler instance is added and managed through a NetScaler Agent.
Telemetry mode
| Setting | Description |
|---|---|
| Automated | Telemetry data collection occurs automatically in NetScaler Console Service. No manual configuration or triggering is required. |
Execution details
The Execution Details section displays the last known telemetry execution status and provides action items for further investigation and validation.
| Element | Description |
|---|---|
| Last Execution Status | Displays the consolidated telemetry status across all managed instances and agents (Success or Needs Attention). |
| View Details | Opens the Telemetry Execution Details panel, providing per-instance and per-agent diagnostic information. |
| Check Connectivity | Runs a live, two-phase connectivity check — first against agent endpoints, then against SSH connectivity to managed instances. This helps determine whether failures originate from the managed device or from the agent infrastructure itself. |
Tip:
Use the search bar to filter results using the Key:Value format.
Telemetry execution details
Select View Details on the NetScaler Telemetry page to open the Telemetry Execution Details panel. This panel contains two primary tabs:
-
NetScaler Telemetry Details — per-instance telemetry status.
-
Agent Telemetry Status — per-agent execution and connectivity status.
NetScaler Telemetry Details tab
This tab displays telemetry execution results for each managed NetScaler instance. Use the search bar to filter results in Key:Value format.
| Column | Description |
|---|---|
| NetScaler Instance | IP address of the managed NetScaler instance. |
| Hostname | NetScaler host name (if available). |
| Agent IP | IP address of the agent managing this instance. A superscript S or P indicates whether the agent is acting as Secondary or Primary for this instance. |
| Instance Type | Type of NetScaler instance (for example, VPX). |
| Instance State | Current reachability state of the NetScaler instance (Up or Down). |
| SSH State | SSH connectivity status between the agent and the instance (Up or Down). |
| Telemetry Status | Result of the last telemetry execution for this instance (Success, Failure, or Internal Error). |
| Error Code | Diagnostic error code associated with a failure. Select View Mitigation Table for the full reference. |
| Error Message | Short description of the failure. Hover over or expand to read the full message. |
Internal error condition: Displayed when telemetry execution insights have not been received for a device within the expected 24-hour time window. The information icon tooltip displays: "Telemetry not received from agent/device in last 24 hours." This condition indicates that NetScaler Console Service did not receive a telemetry execution report from the associated agent. Administrators must review agent health and connectivity to determine the root cause.
Agent Telemetry Status tab
This tab provides telemetry execution and health information at the agent level.
| Column | Description |
|---|---|
| Agent IP | IP address of the NetScaler agent. |
| Agent Type | Type of agent: External (deployed in customer network) or Internal (built into Console Service infrastructure). |
| Execution Time | Timestamp of the last reported telemetry execution for this agent. |
| Package Version | Version of the telemetry package used during the last execution (for example, 15.1-8.51). |
| Evergreen Download Status | Status of automatic telemetry package updates from the download service. Success indicates the latest package was downloaded; Failure indicates the update could not be retrieved. |
| Download Service | Reachability status of the telemetry package download endpoint (download.citrixnetworkapi.net): Reachable or Unreachable. |
| Auto-Enabled Channel | Reachability status of the telemetry upload endpoint (safehaven.adm.cloud.com): Reachable or Unreachable. |
Live connectivity check
Select Check Connectivity on the NetScaler Telemetry page to run a live, two-phase connectivity check.
Note:
The Connectivity Results panel is read-only and reflects the live state at the time the check was triggered. Run Check Connectivity again after applying a fix to verify resolution.
Phase 1 — Agent connectivity
Examines connectivity from each registered agent to the required telemetry cloud endpoints.
| Column | Description |
|---|---|
| Agent IP | IP address of the agent. |
| Agent Type | External or Internal. |
| Agent State | Current state of the agent: Up (green) or Down (red). |
| Download Service | Reachability of download.citrixnetworkapi.net from this agent (Reachable or Unreachable). |
| Auto-Enabled Channel | Reachability of safehaven.adm.cloud.com from this agent (Reachable or Unreachable). |
Action required banner: If one or more agents are in a Down state or show Unreachable for Download Service or Auto-Enabled Channel, an "Action required!" warning banner displays along with an option to View prerequisites.
Phase 2 — SSH connectivity
Examines SSH connectivity between each agent and its managed NetScaler instances.
| Column | Description |
|---|---|
| NetScaler Instance | IP address of the managed NetScaler instance. |
| Hostname | NetScaler host name (if available). |
| Instance Type | Type of NetScaler instance (for example, VPX). |
| Instance State | Current reachability state of the instance. |
| SSH State | SSH connectivity status between the agent and this instance. |
| Agent IP | IP address of the managing agent. |
| Error Details | SSH connectivity result: Success or the specific error encountered. |
Troubleshooting telemetry failures
Follow this procedure when telemetry data is missing or when the Last Execution Status displays Needs Attention:
-
Review execution status: Check the Last Execution Status on the main NetScaler Telemetry page.
-
Open diagnostics: Select View Details to open the Telemetry Execution Details panel.
-
Identify instance failures: In the NetScaler Telemetry Details tab, locate instances displaying a Failure or Internal Error status.
-
Note error information: Note the Error Code and Error Message for each affected instance.
-
Locate mitigation steps: Select View Mitigation Table to open the Error Code Details panel and find the recommended action for the reported error code.
-
Check agent status: Switch to the Agent Telemetry Status tab and review the Evergreen Download Status, Download Service, and Auto-Enabled Channel columns for the managing agent.
-
Review endpoint errors: If any agent shows Unreachable for Download Service or Auto-Enabled Channel, hover over the information icon for detailed error information.
-
Run live connectivity check: Return to the NetScaler Telemetry page and select Check Connectivity to run a live validation of agent and SSH connectivity.
-
Apply fixes: Run the recommended remediation steps based on the error code and connectivity results.
-
Verify resolution: Run Check Connectivity again to verify that the issue has been resolved.
Proxy support
NetScaler Agents support telemetry communication through authenticated proxy servers. During agent registration, administrators can configure proxy settings if required by their network environment.
Proxy-related connectivity issues surface during diagnostics through error codes 1165, 1166, 1265, 1266, and related codes. Refer to the Error Code Reference section for mitigation guidance.
Error code reference
Download service errors (1161–1173)
These errors occur when the agent cannot reach download.citrixnetworkapi.net to download or update the telemetry package.
| Error Code | Error Message | Recommended Mitigation |
|---|---|---|
| 1161 | Failed to resolve the server hostname. | Unable to resolve the server address. Check the DNS server configuration in your network and NetScaler Console server/agent. |
| 1162 | Request Connection Timeout to download.citrixnetworkapi.net | Unable to connect to the server. Check your firewall, proxy settings, and network connection. Verify that download.citrixnetworkapi.net is accessible from your network or proxy. |
| 1165 | Proxy Error. | Check your proxy configuration and ensure network connectivity is working through the proxy. |
Telemetry upload errors (1261–1273)
These errors occur when the agent cannot connect to safehaven.adm.cloud.com to upload telemetry data.
| Error Code | Error Message | Recommended Mitigation |
|---|---|---|
| 1261 | Failed to resolve the server hostname. | Unable to resolve the server address. Check the DNS server configuration in your network and NetScaler Console server/agent. |
| 1262 | Request Connection Timeout. | Unable to connect to the server. Check firewall, proxy settings, and network connections. Verify both URLs (download.citrixnetworkapi.net, safehaven.adm.cloud.com) are accessible. |
| 1265 | Proxy Error. | Check your proxy configuration and ensure network connectivity is working through the proxy. |
| 1266 | Proxy Authentication Failed. | Check proxy credentials and ensure proper authentication configuration on the NetScaler Agent. |
Device state errors (2000–2103)
These errors occur when the agent cannot collect telemetry from a managed NetScaler instance due to instance state or configuration.
| Error Code | Error Message | Recommended Mitigation |
|---|---|---|
| 2000 | Telemetry skipped on this device. | Device might be managed by another NetScaler Console/Service/Agent. Ensure the other collector is sending telemetry data successfully. |
| 2100 | Instance state is down or not reachable. | Ensure that the instance is running and reachable on the network. |
| 2101 | Instance state is Down. | Device is reported as Down in NetScaler Console. Ensure the instance is running and reachable. |
| 2102 | Instance is Out of Service. | Verify the operational and administrative status of the instance in NetScaler Console. |
SSH and authentication errors (2252–2351)
These errors occur during SSH communication between the agent and managed NetScaler instances.
| Error Code | Error Message | Recommended Mitigation |
|---|---|---|
| 2252 | Host key verification failed. | Verify server identity with admin, then remove old key: ssh-keygen -R <server_address> |
| 2350 | SSH Authentication error. | Ensure that the device profile is properly configured in NetScaler Console for the device. |
| 2351 | SSH Failed to connect to device. | Connection might be temporarily blocked by a firewall or network policy, or the device is unreachable. Verify network connectivity and ensure SSH port is accessible. |
Agent and diagnostics errors (2500–2800)
These errors relate to agent availability and telemetry diagnostics capability.
| Error Code | Error Message | Recommended Mitigation |
|---|---|---|
| 2500 | Agent status is down. | Check the agent's connection to NetScaler Console and ensure that the agent service is running properly. |
| 2700 | Telemetry not received from agent/device in last 24 hours. | Check the agent's connection to NetScaler Console and ensure that the agent is running properly. |
| 2800 | Telemetry diagnostics not supported on this version. | Upgrade the agent/mastools to the latest version to enable telemetry diagnostics. |
Python environment errors (3100–3105)
These errors occur when the telemetry collection script cannot execute correctly on the managed NetScaler instance due to Python environment issues on the device.
| Error Code | Error Message | Recommended Mitigation |
|---|---|---|
| 3100 | Python environment check failed on the device. | The Python environment required for telemetry could not be validated on the device. Ensure the device is running a supported version and the Python stack is intact. |