Agent Polling Mode

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

By default, the Agent maintains a persistent outbound TLS connection, or tunnel, to Alation Cloud Service. Jobs such as metadata extraction, query log ingestion, and test connections are pushed over that tunnel as soon as they’re queued. Polling mode is an alternative connection model: instead of holding a connection open, the Agent periodically opens a short-lived outbound connection, asks whether jobs are waiting, executes them, returns the results, and closes the connection, waiting for the polling interval before asking again. Polling mode exists for organizations whose InfoSec policy prohibits long-lived outbound connections from inside the network perimeter. If that isn’t a requirement for your organization, Alation recommends the default tunneling mode: it’s faster, and it’s the mode all Alation features are tested against first.

What Stays the Same

  • Connection direction is unchanged. The Agent always initiates the connection outbound, and Alation Cloud Service never initiates an inbound connection. Neither mode requires inbound firewall rules.

  • The certificate model is unchanged. The Agent uses the same Agent certificate issued by the AWS Certificate Manager (ACM) Private Certificate Authority, and the same mutual authentication, in both modes. See the Security section of Alation Agent.

  • The connector set is unchanged. Polling mode works with RDBMS, BI, and file system OCF connectors.

What Changes

In polling mode, every request waits for the next poll. In the worst case, a request can take one polling interval on the outbound leg, plus execution time, plus up to one more polling interval on the return leg. With the default 30-second polling interval, an operation that takes under a second in tunneling mode can take 30 to 60 seconds in polling mode. This added latency is expected behavior, not a fault.

Operation

Effect in Polling Mode

Test connection

Noticeably slower, and may approach or exceed default timeouts. See Known Limitations below.

Metadata extraction (MDE)

Adds per-job startup latency. Extraction throughput itself is unaffected once the job is running.

Query log ingestion (QLI)

Adds per-job startup latency.

Connector list and Agent detail page loads

Slower to populate.

Compose and query execution

Noticeably slower. See Known Limitations below.

Sampling and profiling

Adds per-job startup latency.

Alation surfaces a UI indicator wherever a polling Agent sits in the data path. See Identify an Agent in Polling Mode below.

Requirements

Requirement

Value

Minimum Agent version

1.6.1.3288

Configuration location

Agent host only (/etc/hydra/hydra.toml)

Configurable from the Alation UI or API

No

The UI indicators described below have their own minimum versions. Most are delivered by Alation Cloud Service rather than the Agent, so version numbers differ by indicator. Polling mode is an Agent-side-only setting: there’s nothing to configure in Alation Cloud Service, and it can’t be set through the Agent API. Alation Cloud Service detects the connection mode from the Agent’s behavior and reflects it in the UI.

Identify an Agent in Polling Mode

You don’t need shell access to the Agent host to tell which connection mode an Agent is using. Alation surfaces the mode in several places in the UI.

  1. Agents Dashboard – navigate to the Agents Dashboard:

    1. Click on the Settings icon in the top right corner.

      ../../_images/TopNavigationBar_Gear_Neo.png ../../_images/TopNavigationBar_Gear.png

    2. The Admin Settings page appears. Under the Platform Settings section, click Agents.

      Under the Server Admin section, click Manage Connectors. Then click the Agents tab. The Agents Dashboard appears.

    The dashboard indicates whether each Agent is in polling mode. (Agent 1.6.1.3465 and later.)

  2. Connector Dashboard – when you view a connector’s details on the Connector Dashboard, Alation shows whether the connector is on an Agent that’s in polling mode. (Agent 1.6.1.3465 and later.)

  3. RDBMS data source settings – running a test connection shows a banner indicating that the data source is reached through a polling-mode Agent, and that the response may be delayed. (Agent 1.6.1.3465 and later.)

  4. BI data source settings – the test connection dialog shows the same informational message.

  5. ETL and add-on (ELT) data source settings – the test connection dialog shows the same indicator. (Agent 1.7.0.4045 and later.)

Note

The polling indicator doesn’t appear on the Compose connection settings screen, and it isn’t implemented for file system data sources. If you’re troubleshooting either surface, confirm the Agent’s mode from the Agents Dashboard instead.

On the Agent host itself, you can check the [proxy.polling] block in /etc/hydra/hydra.toml. If the block is absent, or enabled is false, the Agent is in the default tunneling mode.

Advanced: Enable or Disable Polling Mode

Note

Use polling mode only if your organization’s security policy prohibits persistent outbound connections. Tunneling mode is the default, and Alation recommends it for all other deployments. Switching modes requires shell access to the Agent host and an Agent restart, which briefly interrupts running jobs.

Enable Polling Mode

  1. On the Agent host machine, open the Agent configuration file at /etc/hydra/hydra.toml.

  2. Add the following section to enable polling mode:

    [proxy.polling]
enabled = true

    The [proxy.polling] section is a subsection of the existing [proxy] block, which must be present and uncommented. The polling interval is controlled by a period key and defaults to 30 seconds. Alation sets this value and uses the same interval across all deployments; don’t change it unless directed to by Alation Support.

  3. Restart the Agent for the change to take effect:

    sudo hydra restart

  4. Go to the Agents Dashboard and confirm the Agent shows as connected and marked as being in polling mode.

    1. Click on the Settings icon in the top right corner.

      ../../_images/TopNavigationBar_Gear_Neo.png ../../_images/TopNavigationBar_Gear.png

    2. The Admin Settings page appears. Under the Platform Settings section, click Agents.

      Under the Server Admin section, click Manage Connectors. Then click the Agents tab. The Agents Dashboard appears.

Disable Polling Mode

  1. On the Agent host machine, open /etc/hydra/hydra.toml.

  2. Either remove the [proxy.polling] section, or set enabled = false.

  3. Restart the Agent for the change to take effect:

    sudo hydra restart

  4. Confirm on the Agents Dashboard that the polling indicator is gone.

You can switch between modes at any time after initial setup. Because switching requires an Agent restart, schedule the change outside extraction windows. Any job interrupted by the restart may need to be started again manually.

Polling Mode and Zero Data

Polling mode and Zero Data address different concerns, and you can use them together. Polling mode governs how the Agent talks to Alation Cloud Service, using short-lived polled connections instead of a persistent tunnel. Zero Data governs where query results live: execution, sampling, and profiling run on-premises, and results are written to your own object store instead of traversing or being stored in Alation Cloud Service. Organizations that adopt polling mode for InfoSec reasons frequently have the data-residency requirements that Zero Data addresses, so the combination is common.

  • The Zero Data support matrix still applies in full. Polling mode doesn’t relax any Zero Data requirement. See the Zero Data Support Matrix on the Agent overview page.

  • The user’s browser must still reach the Agent’s Zero Data ingress endpoint directly, independent of the Agent’s connection mode.

  • Zero Data restrictions are unchanged. Export and download of query results remain unsupported in Zero Data mode, regardless of connection mode. See Zero Data Query Results.

  • To install the Query Service Add-on on an Agent that’s already in polling mode, follow the standard procedure in Manage the Query Service Add-on. No polling-specific installation steps are required.

Known Limitations

Compose Connections May Time Out with the Default Database Connection Timeout

Alation’s default db_connect RPC timeout is 17 seconds. On a polling Agent, the combined poll-wait, execution, and return-leg poll-wait regularly exceeds that budget, even when the underlying database connects quickly. The result is a connection failure in Compose that isn’t caused by the database or its credentials.

Establishing a Compose connection through a polling Agent fails. On Alation Cloud Service versions before 2026.5.1, the error is misleadingly reported as Credentials Incorrect. On 2026.5.1 and later, the error correctly reads Connection Timeout, with a message noting the polling delay. Because the polling indicator banner doesn’t render on the Compose connection settings screen, there’s nothing on that screen suggesting polling is the cause on earlier versions.

As a workaround, in Compose admin settings, increase the database connection timeout from the default to 60 seconds. Connections that failed at 17 seconds typically complete in roughly 40 seconds.

This limitation applies to any Agent-backed OCF connector in polling mode. It isn’t specific to any one data source. (AL-189602)

Other Operations May Need Longer Timeouts

The same arithmetic applies to any synchronous operation with a fixed timeout. If you see timeouts on a polling Agent that don’t reproduce on a tunneling Agent, check the polling interval before investigating the data source.

Troubleshooting

Symptom

Check

Agent shows as Disconnected shortly after enabling polling

Alation marks a polling Agent disconnected if no poll is received for roughly 10x the configured interval. Confirm the Agent host can reach Alation Cloud Service outbound, and that the Agent (hydra) is running.

Everything is slow but nothing fails

This is expected. Confirm the polling indicator is present on the Agents Dashboard, and set expectations with users accordingly.

Compose connection fails immediately

See Known Limitations above, and raise the Compose database connection timeout.

TOML syntax error on restart

[proxy.polling] is a subsection of [proxy]. Confirm the [proxy] block exists and isn’t commented out, and that the section header is spelled exactly [proxy.polling].

For general Agent troubleshooting, see Troubleshoot the Agent.