# 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.

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

**Console**
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](/docs/tags-and-projects#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.

**CLI**
```sh
dcloud deploy apps resources app-id
dcloud deploy apps resource-activity app-id --node container:i-0123456789example:web
dcloud deploy apps live-diff app-id --instance instance-id
```

`--node` is a key from the tree, such as `machine:<instance id>` or
`container:<instance id>:<service>`.

**API**
`GET /deploy/api/apps/app-id/resources` returns the tree,
`GET /deploy/api/apps/app-id/resources/activity?node=<key>` one node's events and log lines,
and `GET /deploy/api/apps/app-id/resources/diff?instance=instance-id` the comparison.

## 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](what-runs-on-your-machines.md).

## Related

- [Monitoring](monitoring.md)
- `deploy.apps.resources` · `dcloud deploy apps resources`
