Skip to content

My collector deployed but no data is landing

Applies to: every collector deployed through deploy_collector or the webapp Deploy panel · First check: collector_health

The single most common surprise: deploy_collector does not run a collector. It registers the service and mints an agent JWT — nothing streams until you run the agent with that token. This page explains that step and the states you see while data starts (or fails) to land.

Bring-your-own, by design

deploy_collector is remote bring-your-own only. It returns a service_id, a binding_id, a gateway_url, and a token (the agent JWT). The overseer never spawns a platform-managed container from this tool. See deploy_collector and Worked examples → Flow 1.

Run the agent

The collector produces data only once the aetelier-agent process is running against the gateway with the JWT from your deploy result. The two load-bearing variables:

Env var From Notes
AETELIER_GATEWAY_URL the gateway_url in the deploy result Match the scheme exactly — see TLS vs plaintext
AETELIER_TOKEN the token in the deploy result The agent JWT. Required — the agent does not self-sign

The token's claims already carry binding_id, service_id, and session_id, so you do not set those as separate variables — the agent extracts them at startup. Full contract: aetelier-agent → Environment variables.

The webapp shows the exact command for your binding, on the Deploy panel or from the fleet's COMMAND button:

docker run -d --pull always --restart unless-stopped --name aetelier-agent-<exchange>-<datatype>-<binding4> \
  -v "$HOME/aetelier-data:/home/agent" \
  -e AETELIER_GATEWAY_URL="<gateway_url>" \
  -e AETELIER_TOKEN=<token> \
  -e RUST_LOG=info \
  ghcr.io/aetelierxyz/aetelier-agent:latest

The container name is aetelier-agent- plus the exchange id, the datatype, and the first four characters of the binding_id; see aetelier-agent → Deployment.

Treat the JWT like a password — keep it out of shared configs and version control.

Starting vs silent — read the verdict

Once the agent is up, collector_health returns a top-line verdict. A fresh, working deploy reads starting, not a failure, until the first rows land:

Verdict Means Do this
starting Connected; still inside the first-data grace, no rows yet Wait out the grace, then re-check
healthy Connected and fresh rows are landing Nothing — data is flowing
degraded Connected but rows stalled past the grace Check the venue/symbol and the agent logs
silent Not connected, or no data and past grace The agent is not running or cannot register — see below

liveness.connected: false means the agent never registered with the gateway. liveness.connected: true with landing.rows_last_5m: 0 past the grace means it registered but is not producing — usually a wrong symbol or a paused task.

The first-data grace (~180s)

A new deploy has no lake rows for the first few minutes, so health leads with liveness and reads starting rather than reporting a problem. The window is the platform's first-data lag, 180 seconds; it is what separates starting from degraded. The health result reports landing.expected_first_data_by — do not conclude failure before that timestamp.

The binding stays pending

If the binding never leaves pending and the agent seems stuck connecting, the agent is not registering with the gateway. Common causes:

  • TLS vs plaintext mismatch. The most frequent cause. A gateway served behind a TLS-terminating origin needs an https:// AETELIER_GATEWAY_URL; a plaintext h2c gateway needs http://. Pointing a plaintext agent at a TLS origin (or the reverse) leaves the agent connecting with the binding never activating. Match the scheme to how the gateway is actually served.
  • Expired or wrong-key token. A JWT that has expired, or was minted against a signing key the gateway no longer uses, is rejected at registration. Mint a fresh token from the webapp Deploy panel.
  • Binding already in use. The same binding_id is already held by another active agent. Stop the other agent or deploy a new collector.

The agent's own diagnostics for these are in aetelier-agent → Common operational issues.

One collector, one symbol

A collector carries exactly one symbol. Deploying with more than one symbol is rejected at admission — deploy a separate collector per symbol. If a deploy you expected to accept several symbols came back refused, this is why.

Quick checklist

  1. Did you actually run the agent? deploy_collector alone mints only a JWT.
  2. Is AETELIER_TOKEN the exact token from the deploy result, unexpired?
  3. Does AETELIER_GATEWAY_URL match the gateway's scheme (http:// vs https://)?
  4. Are you inside the ~180s grace? Check landing.expected_first_data_by.
  5. Is the symbol the venue-native form? Confirm with list_cex_options.
  6. One symbol per collector.