API: Usage metrics

Usage numbers come from a small monitoring agent inside the VM, which sends them every 60 seconds with a token that belongs to that one VM. The /agent/* endpoints are what the agent itself uses; you normally only call the /orders/{order}/metrics ones. See Usage monitoring.

Read a VM's usage

GET /orders/{order}/metrics

Returns CPU percent, memory and root disk used/total (bytes) and network in/out (bytes per second) for range 1h, 24h (one point per minute), 7d (5-minute averages) or 30d (hourly averages), plus whether the agent is reporting. CPU and network are null for a point the agent could not compute, for example right after a reboot.

Authentication: Send your API key or token as a bearer token.

Path parameters

Query parameters

Responses

• 200 OK. Returns: data (VmMetricsSeries).
• 403 Not allowed, the resource is not yours
• 422 Validation error, or not allowed in the current state

Example

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID/metrics \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Get the agent install command

GET /orders/{order}/metrics/agent

Returns the agent's status and the one-line install and uninstall commands for this VM. Only the VM's owner can call it, because the install command contains the VM's token. install_command is null until a token exists; create one with the rotate endpoint.

Authentication: Send your API key or token as a bearer token.

Path parameters

Responses

• 200 OK. Returns: data (object).
• 403 Not allowed, the resource is not yours

Example

curl -X GET https://veneshcloud.ir/api/orders/ORDER_ID/metrics/agent \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Create or replace the agent token

POST /orders/{order}/metrics/agent/rotate

Creates the VM's agent token, or replaces it. The old token stops working at once, so an agent installed with it stops reporting until you run the new install command on the VM. Owner only.

Authentication: Send your API key or token as a bearer token.

Path parameters

Responses

• 200 OK. Returns: data (object).
• 403 Not allowed, the resource is not yours
• 422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/orders/ORDER_ID/metrics/agent/rotate \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Send one usage sample (agent)

POST /agent/metrics

Used by the monitoring agent inside the VM, with the VM's agent token as the bearer token. It only stores numbers for that one VM (at most one point per minute) and returns nothing. Values outside sane limits are refused.

Authentication: None, this endpoint is public.

Request body (application/json)

Responses

• 204 Done, no content returned
• 410
• 413
• 422 Validation error, or not allowed in the current state
• 429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/agent/metrics \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"v":1,"cpu_percent":"string","mem_total":1,"mem_used":1,"disk_total":1,"disk_used":1,"net_rx_bps":"string","net_tx_bps":"string"}'

Download an agent file

GET /agent/{file}

Returns one of the agent's files as plain text so you can read it before running it: install.sh, uninstall.sh, venesh-metrics-agent.sh, venesh-metrics-agent.service or venesh-metrics-agent.timer. Public.

Authentication: None, this endpoint is public.

Path parameters

Responses

• 200 OK
• 404 Not found

Example

curl -X GET https://veneshcloud.ir/api/agent/FILE_ID \
  -H "Accept: application/json"

Objects

Field lists for the objects returned above.

MetricsAgentStatus

VmMetricsPoint

VmMetricsSeries