Inspect an app

See everything an app is made of as one tree, with the health and sync of each machine and container, and compare what a machine runs with what it was asked to run.

Last updated 18 November 2026View as Markdown

Replace app-id with the app's id and instance-id with a machine's instance id.

Prerequisites

  • Permission for deploy:DescribeApp on the app.
  • A bound database, cache or broker appears only if your policies let you describe that service. A container's log lines also need monitoring:FilterLogEvents. Environment variables are compared only for someone with deploy:ManageEnv.

Open the resource tree

  1. Open the app's Resources tab. It shows the deployment the machines should run, the load balancer (when there is one), each machine, the containers on each machine, the names that reach the app with their certificates, and the databases, caches and brokers it is bound to. Each row has its health; a machine and its containers also their sync and how long ago the machine last reported.
  2. Select a row. A side panel opens with its Health, Sync (machines and containers), Details, Last report, Events and, for a container, Last log lines (the last 24 hours).
  3. For a machine, the panel also has Desired vs live: Matches, Differs or Unknown (the machine has not sent a summary yet), with each difference listed.

Machine health

A running machine's health in the tree comes from its last report:

Health Reason shown
healthy The app answers its health check.
degraded The app does not answer its health check.
progressing The machine has not reported yet.
unknown The machine stopped reporting (over a minute ago).

A machine that is not running reads suspended (stopped), missing (terminated or deleted) or the state it is in. In GET /deploy/api/apps/app-id, each target's health is pending, healthy, unhealthy or stale instead.

Machine sync

Beside health, each machine has a sync answer: whether it runs the deployment it should. The deployment it should run is the newest one that is rolling out or live. Health and sync are separate: a machine can serve an older generation perfectly well (healthy, out of sync), or run the right image and fail its health check (in sync, unhealthy).

Sync Meaning
in sync the machine's last report names the desired generation and its image (or compose file digest)
out of sync it names something else, e.g. "Runs generation 6; should run 7."; while the desired deployment is still rolling out, the console shows Updating
sync unknown the machine has not reported, has not reported for over a minute, or the app has no deployment yet

A machine is briefly out of sync during every rollout. Once the desired deployment is live, a machine that stays out of sync for over a minute is written to the app's and the machine's events (phase drift), and so is its return to sync. GET /deploy/api/apps/app-id returns sync, syncReason, expected, running and driftSince on each target. It returns the environment only to a caller with deploy:ManageEnv, and the compose file only to one with deploy:UpdateApp; the response says when either was withheld.

Result

You see what the app runs, where, and whether each machine runs what it should. How the comparison with what it was asked to run works is in What runs on your machines.

Did this page help you?