Monitoring and health

Service health, uptime checks, error-rate thresholds, traces, Server and container metrics and request logs.

Read how a Service is doing and set the limits that raise an incident: uptime checks, the error rate from 5xx answers per Domain, and Server CPU and memory thresholds. Metrics and request logs come from the Server the Service runs on.

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Monitoring in the user guide.

Service health

Get a Service's health

GET/service-health/{serviceType}/{serviceId}

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceType`required	path	string	Service type. One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.
`serviceId`required	path	string	The Service's id. Not empty.
`page`	query	integer	At least 1. Default `1`.
`limit`	query	integer	1 to 100. Default `20`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/service-health/application/ikGaJLrdLoCZDcimNaVV3 \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Uptime checks

List uptime checks

GET/uptime-checks

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.
`serviceId`required	query	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/uptime-checks?serviceType=application&serviceId=ikGaJLrdLoCZDcimNaVV3" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create an uptime check

POST/uptime-checks

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Request body

Field	Type	Notes
`serviceType`required	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`.
`serviceId`required	string	Not empty.
`kind`	string	One of `http`, `tcp`. Default `"http"`.
`domainId`	string	Not empty.
`port`	integer	1 to 65535.
`intervalSeconds`	integer	30 to 3600. Default `60`.
`timeoutSeconds`	integer	1 to 60. Default `10`.
`expectedStatuses`	array of string	1 to 20 items.
`downAfter`	integer	1 to 20. Default `3`.
`enabled`	boolean	Default `true`.
`keyword`	string or null	1 to 256 characters.
`headerName`	string or null	1 to 128 characters. Matches `^[!#$%&'*+.^_`\|~0-9A-Za-z-]+$`.
`headerValue`	string or null	1 to 4096 characters. Matches `^[\t\x20-\x7e\x80-\xff]+$`.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/uptime-checks \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serviceType": "application",
    "serviceId": "ikGaJLrdLoCZDcimNaVV3"
  }'

List ports a check may dial

GET/uptime-checks/published-ports

The TCP ports a check on this Service may dial, the address it dials them on, and why there are none when there are none — the modal's published-port picker.

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.
`serviceId`required	query	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/uptime-checks/published-ports?serviceType=application&serviceId=ikGaJLrdLoCZDcimNaVV3" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update an uptime check

PATCH/uptime-checks/{uptimeCheckId}

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`uptimeCheckId`required	path	string	The uptime check's id.

Request body

Field	Type	Notes
`domainId`	string	Not empty.
`port`	integer	1 to 65535.
`intervalSeconds`	integer	30 to 3600.
`timeoutSeconds`	integer	1 to 60.
`expectedStatuses`	array of string	1 to 20 items.
`downAfter`	integer	1 to 20.
`enabled`	boolean
`keyword`	string or null	1 to 256 characters.
`headerName`	string or null	1 to 128 characters. Matches `^[!#$%&'*+.^_`\|~0-9A-Za-z-]+$`.
`headerValue`	string or null	1 to 4096 characters. Matches `^[\t\x20-\x7e\x80-\xff]+$`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/uptime-checks/kLCit2svhFoR5GaDEed5t \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "domainId": "6MZy6JYxZ28Cxm9jWJgGj",
    "port": 3000,
    "intervalSeconds": 30
  }'

Delete an uptime check

DELETE/uptime-checks/{uptimeCheckId}

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`uptimeCheckId`required	path	string	The uptime check's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/uptime-checks/kLCit2svhFoR5GaDEed5t \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Error-rate thresholds

Get an error-rate threshold

GET/error-rate-thresholds/{serviceId}

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id.
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl "https://cloudgate.octabyte.app/backend/error-rate-thresholds/ikGaJLrdLoCZDcimNaVV3?serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update an error-rate threshold

PUT/error-rate-thresholds/{serviceId}

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id.
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.

Request body

Field	Type	Notes
`percentage`	number	0.1 to 100. Default `5`.
`windowMinutes`	integer	At least -9007199254740991. Default `5`.
`minRequests`	integer	1 to 1000000. Default `20`.
`enabled`	boolean	Default `true`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PUT "https://cloudgate.octabyte.app/backend/error-rate-thresholds/ikGaJLrdLoCZDcimNaVV3?serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "percentage": 5,
    "windowMinutes": 5,
    "minRequests": 20
  }'

Delete an error-rate threshold

DELETE/error-rate-thresholds/{serviceId}

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id.
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE "https://cloudgate.octabyte.app/backend/error-rate-thresholds/ikGaJLrdLoCZDcimNaVV3?serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Traces

Get trace settings

GET/traces/{serviceId}

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id.
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl "https://cloudgate.octabyte.app/backend/traces/ikGaJLrdLoCZDcimNaVV3?serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update trace settings

PUT/traces/{serviceId}

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id.
`serviceType`required	query	string	One of `application`, `postgres`, `mysql`, `mariadb`, `mongo`, `redis`, `compose`, `libsql`, `bucket`.

Request body

Field	Type	Notes
`enabled`required	boolean
`retentionDays`	integer	At least -9007199254740991. Default `3`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PUT "https://cloudgate.octabyte.app/backend/traces/ikGaJLrdLoCZDcimNaVV3?serviceType=application" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "enabled": true
  }'

Get a trace viewer frame

GET/traces/{serviceId}/frame

Where the console frames the Service's Trace store for this caller: its UI's base path under a frame token, and when that token expires.

Who can call it: Owner, Admin or Member. Needs service: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/traces/ikGaJLrdLoCZDcimNaVV3/frame \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Monitoring

Setup monitoring

POST/monitoring/servers/{serverId}/setup

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`required	path	string	The Server's id. Not empty.

Request body

Field	Type	Notes
`metricsConfig`required	object
`metricsConfig.server`required	object
`metricsConfig.server.refreshRate`required	number	At least 2.
`metricsConfig.server.port`required	number	At least 1.
`metricsConfig.server.token`	string
`metricsConfig.server.urlCallback`required	string (uri)
`metricsConfig.server.retentionDays`required	number	At least 1.
`metricsConfig.server.cronJob`required	string	Not empty.
`metricsConfig.server.thresholds`required	object
`metricsConfig.containers`required	object
`metricsConfig.containers.refreshRate`required	number	At least 2.
`metricsConfig.containers.services`required	object

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/monitoring/servers/Ni7mAbWKjbWy4KErPjtrY/setup \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "metricsConfig": {
      "server": {
        "refreshRate": 2,
        "port": 3000,
        "urlCallback": "https://northwind.dev",
        "retentionDays": 1,
        "cronJob": "0 3 * * *",
        "thresholds": {
          "cpu": 0,
          "memory": 0
        }
      },
      "containers": {
        "refreshRate": 2,
        "services": {
          "include": [
            "example"
          ],
          "exclude": [
            "example"
          ]
        }
      }
    }
  }'

Get server metrics

GET/monitoring/metrics

Who can call it: Owner, Admin or Member. Needs monitoring: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string	Not empty.
`limit`	query	string
`start`	query	string
`end`	query	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/monitoring/metrics \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get container metrics

GET/monitoring/metrics/containers

Who can call it: Owner, Admin or Member. Needs monitoring: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverId`	query	string	Not empty.
`appName`required	query	string	Not empty.
`limit`	query	string
`start`	query	string
`end`	query	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/monitoring/metrics/containers?appName=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Read stats logs

POST/monitoring/requests/logs

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Request body

Field	Type	Notes
`page`	object
`page.pageIndex`required	number
`page.pageSize`required	number
`sort`	object
`sort.id`required	string
`sort.desc`required	boolean
`search`	string
`status`	array of string
`method`	array of string
`dateRange`	object
`dateRange.start`	string
`dateRange.end`	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/monitoring/requests/logs \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "page": {
      "pageIndex": 1,
      "pageSize": 1
    },
    "sort": {
      "id": "4zhdmt5Eo7qULhWxBAsV6",
      "desc": true
    },
    "search": "example"
  }'

Read stats

POST/monitoring/requests/stats

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Request body

Field	Type	Notes
`dateRange`	object
`dateRange.start`	string
`dateRange.end`	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/monitoring/requests/stats \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "dateRange": {
      "start": "example",
      "end": "example"
    }
  }'

List request targets

GET/monitoring/requests/servers

The Requests page's Server picker. No SSH: logging-off Servers are listed.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/monitoring/requests/servers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Read requests

GET/monitoring/requests

One read of a Server's access log over SSH (or the platform host's), split by Service. A GET, so a Frozen Organization keeps it.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`serverId`	query	string	Not empty.
`start`	query	string
`end`	query	string
`pageIndex`	query	integer	At least 0.
`pageSize`	query	integer	1 to 500.
`search`	query	string
`status`	query	array of string
`method`	query	array of string
`serviceId`	query	array of string
`noService`	query	string	One of `true`, `false`.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/monitoring/requests \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Read service requests

GET/monitoring/requests/services/{serviceId}

A Service's Requests tab: its Server's read, found from the Service, with the Service filter fixed to it — or cloud-account for a Service in a Cloud account. Only an Application or a Compose stack has one. A GET, so a Frozen Organization keeps it.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`serviceId`required	path	string	The Service's id. Not empty.
`start`	query	string
`end`	query	string
`pageIndex`	query	integer	At least 0.
`pageSize`	query	integer	1 to 500.
`search`	query	string
`status`	query	array of string
`method`	query	array of string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/monitoring/requests/services/ikGaJLrdLoCZDcimNaVV3 \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.