Skip to main content

Use the Privacy Agent's local status page

Status: in development (#560). The status page ships with the Privacy Agent image; see Deploy the Privacy Agent.

Goal​

You'll open the Privacy Agent's built-in status page to check, from inside your own network, whether the agent can reach Measured Cloud, what it's working on, and which connections it holds. You can also run network diagnostics and test a connection from the page.

The page is for your IT team, and it's most useful when the agent can't reach Measured Cloud. When the agent is online, Settings → Privacy Agents in Measured Cloud shows the same status and recent jobs.

Prereqs​

  • A running v2 Privacy Agent.
  • A shell or browser on the agent's host. To reach the page from another machine, you also need a password for the page (step 3).

What the page shows​

The page is read-only. It refreshes every 5 seconds and has no JavaScript.

  • Connection to Measured Cloud: the URL, the proxy in use, the CA bundle, the last successful call, the last heartbeat and recent errors.
  • Agent: its name and ID, your organisation, the version (and whether an update is available), the key fingerprint and how many jobs it runs at once. Compare the fingerprint with the one in Settings → Privacy Agents.
  • Jobs: the jobs running now, and the last 100 jobs with their kind, data source, duration, outcome and error.
  • Connections: each connection the agent holds, with its non-secret details, where its credentials are kept, and the last test result.
  • Policy and privacy level: your local policy.yaml settings and the privacy level Measured Cloud sent.
  • Local audit log: every job the agent ran for Measured Cloud.
  • Recent log lines: the last 200 lines of the agent's log.

The page never shows passwords, keys, tokens or row data. Error messages and log lines are scrubbed before they're shown, and connection fields that look secret are hidden.

Until a part of the agent is available, its section reads Not configured yet.

Steps​

1. Open the page on the agent's host​

By default the page listens on 127.0.0.1:8765, so only the host itself can reach it:

curl -s http://127.0.0.1:8765/ | head

Or open http://127.0.0.1:8765/ in a browser on that host. To reach it from your laptop without exposing it, use an SSH tunnel:

ssh -L 8765:127.0.0.1:8765 you@agent-host
# then open http://127.0.0.1:8765/ locally

2. Run diagnostics or test a connection​

These are the page's only two actions. Neither changes anything.

  • Run diagnostics checks each step from the agent to Measured Cloud: the proxy it uses, DNS, the TCP connection, the proxy tunnel (if any), the TLS handshake and GET /api/version. It also checks that each database driver loads. Each step shows ok, warn, fail or skip. Steps after a failed one are skipped, so the first fail is the step to fix.
  • Test connection (on a connection's row) connects to that database from the agent and shows the result.

Common failures:

StepLikely cause
DNSThe host can't resolve Measured Cloud (or your proxy). Check the host's DNS settings.
TCP connectA firewall blocks outbound HTTPS. Allow port 443 to Measured Cloud, or set a proxy.
Proxy tunnel: 407The proxy needs credentials. Put them in the proxy URL.
TLS handshake: certificate not trustedA TLS-inspecting proxy re-signs traffic. Set DQ_AGENT_CA_BUNDLE to its CA certificate.

3. (Optional) Reach the page from another machine​

Set a bind address and a password. The agent won't serve the page on a non-loopback address without a password: it logs an error, leaves the page off and keeps running.

docker run ... \
  -e DQ_AGENT_STATUS_BIND=0.0.0.0 \
  -e DQ_AGENT_STATUS_PASSWORD_FILE=/run/secrets/status-password \
  -p 127.0.0.1:8765:8765 \
  ...

Your browser asks for a user name and password. Any user name works; the password is the one you set.

The page is plain HTTP. On a shared network, put it behind your own TLS reverse proxy or use an SSH tunnel (step 1) rather than publishing the port widely. In a container, DQ_AGENT_STATUS_BIND=0.0.0.0 is needed for the port mapping to work, so a password is required there too.

Configuration​

VariableDefaultDescription
DQ_AGENT_STATUS_ENABLEDtrueSet to false to turn the page off.
DQ_AGENT_STATUS_BIND127.0.0.1Address to listen on. Anything other than a loopback address needs a password.
DQ_AGENT_STATUS_PORT8765Port to listen on.
DQ_AGENT_STATUS_PASSWORD(none)Password for the page (HTTP Basic auth).
DQ_AGENT_STATUS_PASSWORD_FILE(none)A file holding the password, for example a mounted Kubernetes secret. Used when DQ_AGENT_STATUS_PASSWORD is unset.

Verify​

  • The page loads and the badge next to the agent's name reads Connected. Degraded means there were errors in the last 5 minutes; Not connected means no heartbeat for 2 minutes.
  • Run diagnostics reports all checks passed, or names the step that failed.
  • With a non-loopback bind, the page asks for a password.

See also​