> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/getting-started/running-llms-with-kinesis-network/monitoring-apps.md).

# Monitor and troubleshoot

Read status, choose the right logs and investigate deployment or runtime failures.

Open an app to inspect its status, endpoints and operational tabs. Image pulls, builds and machine provisioning can take time; use the reported state to decide what to inspect next.

| Tab             | Use it for                                                              |
| --------------- | ----------------------------------------------------------------------- |
| **Logs**        | Container output, separated by server when there are multiple instances |
| **Terminal**    | An interactive shell in a running container                             |
| **Metrics**     | CPU, GPU, memory and other usage over time                              |
| **History**     | App actions and platform events affecting placement or execution        |
| **Deployments** | Repository import, image-build progress and builder logs                |
| **Config**      | Source, runtime, network, execution and resource settings               |

Monitoring covers resources you can access in the current organization. A **Person** filter appears when more than one member has apps, alongside project, app and node filters. Viewers cannot open a terminal or read secret values. Organization admins use the [audit log](https://docs.kinesis.network/organizations/settings.md) to trace member, server and resource changes.

## Follow deployment state

| State or symptom              | What to inspect                                         |
| ----------------------------- | ------------------------------------------------------- |
| Building                      | Deployment step and builder logs                        |
| Downloading or starting       | Image size, pull progress and startup behavior          |
| Provisioning                  | Grid capacity, servers and pending orders               |
| Start blocked                 | Runtime errors, balance and placement requirements      |
| Error or repeated exits       | Runtime logs, command, environment and restart policy   |
| Stopped with a running target | Matching capacity, placement filters and runtime errors |
| Queued on a shared grid       | Fair-share position and available capacity              |

## App runs but the endpoint does not respond

A successful build can still be deploying. In **Deployments**, the new build shows **Deploying** while servers take its image; older builds still serving stay **Active**. A failed rollout shows **Deploy failed**. For automation, inspect `get_app_status.rollout.phase`: wait through `pending` or `applying`, finish at `settled`, and inspect errors at `failed`. Follow `pollAfterSec`. If a rollout stays pending, check each node’s `reportedAt` for a server that stopped reporting.

Check that the service binds to `0.0.0.0`, uses the configured container port and supports the selected protocol. Use the endpoint Kinesis returns: some protocols allocate a public port different from the container's port. In API status, an endpoint with a null address is not wired yet.

App, build and server logs are the producing process’s raw output. They may contain sensitive values even when app configuration hides secrets. Limit the time range and redact excerpts before sharing them.

## Build fails before the app starts

Read builder logs rather than runtime logs. Confirm the image's base tag, package installation steps, build context and Dockerfile path. For repository apps, correct the source settings or Dockerfile, then trigger a new build. A successful image build is followed by deployment; continue checking app status afterward.

To restore an earlier repository image, use **Roll back** in Deployments while the image is still stored. If it is unavailable, build that commit again. Rollback does not rebuild or restore an old environment/configuration; the next build replaces the image again.

## Grid quota or serverless refusal

Quota usage belongs to the app’s creator. `QUOTA_EXCEEDED` can leave an app start-blocked; `ScaleCapped` means it runs below the required instance count. Lower minimum instances, free another of the creator’s placements or ask a grid admin. Lowered caps can warn and then stop newer placements after the grace period. See [grid policies](https://docs.kinesis.network/getting-started/running-llms-with-kinesis-network/understanding-grids.md).

For `serverless_gpu_unavailable`, select a grid or set `hardware.gpuCount` to 0. This is separate from the organization’s serverless permission.

For `serverless_disabled`, select an accessible grid or ask an organization admin. Adding API scopes does not bypass this setting.

## App stops or loses capacity

Inspect runtime errors and History. Repeated startup failures, an idle-reclaim policy, a fair-share turn ending, quota enforcement, a security stop or a manual stop can produce different outcomes. A grid may still be filling even while another instance is running. A `SECURITY_STOPPED` platform event names suspicious activity detected by the security agent; inspect that event before deciding whether to restart.

## Automate inspection

Usage charts show bucket peaks alongside averages. The usage API adds `avg` and `peak` to each point in each server’s series, while retaining the existing totals. Rates include CPU/GPU use, memory, storage and bytes per second. Each peak is that metric’s busiest five-second record within its bucket; peaks across different servers need not have happened at the same time.

Use REST status, logs and usage endpoints, or MCP `get_app_status`, `get_app_logs` and `get_app_usage`. Runtime logs and build logs require `monitoring:read` in addition to any resource-specific scope listed in the reference. App-usage queries support ranges of at most 30 days.

See the [Apps reference](https://docs.kinesis.network/api/apps.md), [Builds reference](https://docs.kinesis.network/api/builds.md) and [agent workflows](https://docs.kinesis.network/mcp/workflows.md).

When asking [support](https://docs.kinesis.network/support.md) for help, include the organization slug, project/app ID, time of the failure, request ID when available and a short log excerpt with secrets removed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/getting-started/running-llms-with-kinesis-network/monitoring-apps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
