EasyDCIM Documentation
Back Home
Free Trial Request Get Started

Remote Agent Polling

Troubleshooting Center

# Remote Agent Polling

This guide helps you diagnose and resolve connectivity and polling issues between the EasyDCIM Control Plane and your Remote Agents.

# Overview

Remote Agents periodically pull the list of devices from the EasyDCIM master panel through an internal API endpoint:

/internal/api/app/{APP_ID}/polling/devices

By default, the timeout for this operation is set to 60 seconds.

If you have a large number of devices or your master panel is under heavy load, the API might not respond within this timeframe. When this happens, the Remote Agent logs a timeout error (often cURL error 28) and stops collecting data for that polling cycle.

# Remote Agent API Connectivity

The Remote Agent communicates with the master panel through the internal API. For polling, the most important request is the device list request shown above.

The request requires:

  • APP ID - the Remote Agent application ID.
  • Master Panel URL/IP - the URL or IP address of the EasyDCIM master panel reachable from the Remote Agent.
  • Local API Key - sent in the X-Authorization header.

WARNING

The X-Authorization header contains a secret key. Never share this key in public tickets, screenshots, logs, or command output.

# Quick API test

Run this command from the Remote Agent server:

curl -k -sS -o /tmp/polling-devices.json -w \
  "http_code=%{http_code} time_total=%{time_total}s\n" \
  -H "Accept: application/json" \
  -H "X-Authorization: [YOUR_API_KEY]" \
  "https://[MASTER_IP]/internal/api/app/[APP_ID]/polling/devices"

This saves the response body to /tmp/polling-devices.json and prints only the HTTP code and total request time.

To inspect the response body:

less /tmp/polling-devices.json

Redact the X-Authorization key and any sensitive response data before sharing logs with support.

# How to interpret the result

  • HTTP 200 and a valid JSON response - the API is reachable.
  • HTTP 401 / 403 - authentication problem. Check the Local API Key and X-Authorization header.
  • HTTP 404 - wrong URL, wrong APP ID, or routing problem on the master panel.
  • HTTP 5xx - server-side error on the EasyDCIM master panel. Check EasyDCIM logs.
  • cURL error 28 - timeout. The agent waited too long for the master panel response.
  • HTTP 200 with JSON status=error - the network request succeeded, but EasyDCIM returned an application-level error.

# Polling Execution Time

The polling execution time indicates how long it takes for the remote agent to process and collect data (via SNMP, Redfish, Ping, etc.) for all the devices assigned to it. You can monitor this metric directly in the Remote Agent's Polling Status widget.

If the execution time exceeds 600 seconds (10 minutes), the agent is overloaded. When this happens, EasyDCIM will display the following warning:

Execution time over 600 seconds, consider adding another remote agent!

How to resolve this:

  • Scale Horizontally: Deploy an additional Remote Agent and distribute your device locations across multiple agents. This is the most effective way to parallelize the workload and reduce execution times.
  • Review Polling Types: Disable unnecessary polling modules (like Redfish or SNMP) for devices that don't support them to avoid slow, unanswerable queries.

# Internal API Timeout

The internal_api_timeout parameter allows you to control how long the Remote Agent will wait for the EasyDCIM master panel to respond.

# When to increase the timeout

You should increase the timeout if your polling widget shows an API Timeout error or API Slow warning, especially if you have hundreds or thousands of devices assigned to a single agent.

Recommended range: 15 – 120 seconds.

# When NOT to increase the timeout

Do not increase the timeout indefinitely. If the API takes more than 120 seconds to return the list of devices, the problem lies in the server's performance or database bottlenecks, not the agent. A massive timeout will cause polling processes to overlap and queue up, severely delaying data collection.

# Diagnosing Polling Errors

You can check the health of the connection directly in the EasyDCIM panel:

  1. Navigate to Remote Agents -> select your Agent -> Summary.
  2. Locate the Polling Freshness section.

Possible Statuses:

  • API OK: The polling process finished correctly.
  • API Slow: The response took more than 80% of the configured timeout. Consider increasing the timeout slightly or optimizing your server.
  • API Timeout: The connection dropped before the panel could respond. Increase the internal_api_timeout or optimize the master panel response time.
  • API Error: The panel returned an HTTP or application error. Check EasyDCIM logs for exceptions.

# Understanding cURL Error 28

cURL error 28 means that the request timed out. In this case, the Remote Agent gave up waiting for the master panel response.

Most common causes:

  • the master panel needs too much time to generate /polling/devices,
  • too many devices are assigned to a single Remote Agent,
  • the master panel database or storage is slow,
  • network latency or packet loss between the agent and the master panel,
  • the configured internal_api_timeout is too low for the current scale.

If the endpoint is consistently slow, do not only increase the timeout. Also check the EasyDCIM server performance and consider splitting devices between more Remote Agents.

If the API test is successful but polling data is still stale, check the Remote Agent workers and logs. See Remote Agent Logs and Diagnostics.