App monitoring overview
const url = 'https://opfield.example.com/api/apps/550e8400-e29b-41d4-a716-446655440000/overview?range=1h';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://opfield.example.com/api/apps/550e8400-e29b-41d4-a716-446655440000/overview?range=1h' \ --header 'Authorization: Bearer <token>'Per environment the caller may view: health, member count, issues (members per type and state: failing, degraded, stopped, disabled, maintenance, starting, not_started), alerts ({tone: destructive for a failing member, warning for a degraded member or an environment warning, title, detail: the reason}), and 24-point series over the range (1h or 24h) for containers (CPU, memory, restarts, healthy share, unhealthy names), databases (disk, connections, transactions/operations/queries, cache hit, CPU of a managed database), storage (disk, objects, buckets, RX/TX), routes (requests, 5xx, p95 latency, traffic, from the access logs of their ingress nodes) and Pages (active deployment, requests of the routes serving it), plus the nodes the members run on. Series are kept a day per member, so a recreate, a deployment or a restart of Opfield or a daemon keeps them; a series that started within the range has leading nulls. Environment health (the Apps list and the overview compute it the same way): unknown without members; failing when a member fails; degraded when a member is degraded or a warning is open; else healthy. Every failing member is a destructive alert and every degraded member or warning a warning alert, so the alerts always explain the health. Containers, deployments and Compose projects: stopped on request (through Opfield, the API, MCP or docker stop: exit 0, 130 or 143, or 137 without an OOM kill; a deployment or Compose project stopped through Opfield) is “stopped”, shown but neutral, while something else of the environment runs; when every one of them is stopped the environment is degraded (nothing runs). Crashed (another exit code, OOM-killed, dead, in a restart loop) is failing; running but restarted 3+ times in the last hour is degraded; a Compose project with only some services up is degraded; a health check that has not reported yet is neutral (“starting”). Routes: disabled or in maintenance is neutral, but when no route of the environment is enabled and serving it is degraded; a route whose target member was stopped on request is degraded (“its target is stopped”), not failing; an expired certificate fails the route, one whose renewal failed or that expires within 14 days is degraded. Managed databases and storage stopped or paused are degraded (dependencies). Pages: with a route, degraded unless an enabled route serves an active deployment; without a route, healthy with a ready deployment that has a preview URL, neutral (“not started”) before the first deployment is ready, else degraded. A member whose node has been offline for 60 s is degraded (“node unreachable”). Warnings: a database or storage disk at least 80% full; at least 2% of the routes’ requests over the last 5 minutes failing with 5xx (from 10 requests on). A database or storage on several servers carries availability {state, mode, stateReason, members[{memberId, nodeId, nodeName, role, primary, eligible, health: healthy|degraded|down|stopped}]} (null on one server); a set that lost a copy or cannot fail over counts degraded, not failing, while its primary answers. Only members the caller may view count; unknown values are null and unknown series empty. Cached for 15 seconds.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Example
550e8400-e29b-41d4-a716-446655440000Query Parameters
Section titled “Query Parameters”Responses
Section titled “Responses”Successful response
object
Resource object. Exact fields depend on the endpoint.
object
Example
{ "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example resource", "createdAt": "2024-01-01T12:00:00.000Z", "updatedAt": "2024-01-01T12:30:00.000Z" }}Bad request
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ { "path": [ "name" ], "message": "Required" } ]}Authentication required
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "UNAUTHORIZED", "message": "Authentication required"}Forbidden
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "FORBIDDEN", "message": "Insufficient permissions"}Not found
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "NOT_FOUND", "message": "Resource not found"}Conflict
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "CONFLICT", "message": "Resource already exists"}Unprocessable entity
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "UNPROCESSABLE_ENTITY", "message": "Request could not be processed"}Internal server error
object
Error code
Human-readable error message
Additional error details
Example
{ "code": "INTERNAL_ERROR", "message": "Internal server error"}