최신 지표

엔드포인트: /api/metrics/latest/

요청 한 번으로 서버 한 페이지 분량의 CPU, 메모리, 디스크 사용률, 디스크 I/O, 네트워크 최신 값을 읽습니다. 워크스페이스의 지표 개요 화면이 쓰는 것과 같은 값입니다. 서버 목록과 같은 필터, 검색, 페이지네이션을 그대로 받으므로, 서버를 페이지로 나누거나 검색하거나 좁혀서 조회할 때 서버마다 따로 요청하지 않고도 여러 서버의 최신 값을 한 번에 받을 수 있습니다.

워크스페이스에서 Metrics 확장 기능이 켜져 있어야 합니다. 플랜이 이 확장 기능을 지원하지 않으면 402를, 지원하지만 아직 켜지 않았다면 403을 반환합니다. metric:read 스코프가 필요합니다.

요청

GET /api/metrics/latest/

쿼리 파라미터

서버 목록이 받는 필터, 검색, 페이지네이션 파라미터(name, groups, tag, is_connected, starred, os, search 등)를 그대로 받으며, 다음이 추가됩니다.

응답

{
  "count": 42,
  "current": 1,
  "next": 2,
  "previous": null,
  "last": 3,
  "results": [
    {
      "id": "0f3c9d2e-1a4b-4c8d-9e6f-2b7a1c5d8e30",
      "name": "web-01",
      "is_connected": true,
      "cpu": {
        "value": 42.1,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "memory": {
        "value": 68.4,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "disk-usage": {
        "value": 78.0,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": "/",
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "disk-io": {
        "value": 12582912.0,
        "unit": "bytes_per_sec",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": "all",
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "net": {
        "value": 3145728.0,
        "unit": "bytes_per_sec",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": "all",
        "collected": true,
        "reason": null,
        "interval_s": 60
      }
    },
    {
      "id": "3b8f4c1a-7d2e-4a9b-8c5f-1e6a2b9d4c7f",
      "name": "db-01",
      "is_connected": true,
      "cpu": {
        "value": 12.3,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:13:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "memory": {
        "value": null,
        "unit": "percent",
        "sampled_at": null,
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "disk-usage": {
        "value": 34.5,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:13:00+09:00",
        "device": "/data",
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "disk-io": {
        "value": 512000.0,
        "unit": "bytes_per_sec",
        "sampled_at": "2026-09-17T02:13:00+09:00",
        "device": "all",
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "net": {
        "value": 204800.0,
        "unit": "bytes_per_sec",
        "sampled_at": "2026-09-17T02:13:00+09:00",
        "device": "all",
        "collected": true,
        "reason": null,
        "interval_s": 60
      }
    }
  ]
}

results의 각 항목은 id, name, is_connected와 지표별 객체(cpu, memory, disk-usage, disk-io, net) 하나씩을 담습니다. unit은 CPU·메모리·디스크 사용률에서는 percent, 디스크 I/O와 네트워크에서는 bytes_per_sec입니다. device는 값이 어느 디스크·인터페이스에서 왔는지 나타냅니다. 디스크 사용률은 구체적인 마운트 지점, 디스크 I/O·네트워크 합계는 all, 장치와 무관한 CPU·메모리는 null입니다.

필요한 스코프: metric:read

예시

curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/latest/?is_connected=true&ordering=-cpu" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

값이 비어 있을 때

한 지표의 value, sampled_at, device가 null인 경우는 그 지표에 아직 샘플이 도착하지 않았을 때뿐입니다. 서버를 막 등록했거나, 그 지표가 한동안 보고되지 않은 경우입니다. interval_s는 그 지표의 샘플이 몇 초마다 도착해야 하는지를 나타냅니다.

collected와 reason은 이 엔드포인트에서는 항상 true와 null입니다. 이 엔드포인트에 접근할 수 있다는 것 자체가 이미 워크스페이스에서 Metrics 확장 기능이 켜져 있다는 뜻이므로, 응답에 실리는 지표 중 수집되지 않는 것은 없습니다.

가장 바쁘거나 가장 한가한 호스트 찾기

ordering으로 어떤 지표든 정렬할 수 있습니다. 내림차순이면 가장 바쁜 서버가, 오름차순이면 가장 한가한 서버가 먼저 나옵니다.

# CPU 사용률이 가장 높은 서버부터
curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/latest/?ordering=-cpu" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
 
# 디스크 사용률이 가장 낮은 서버부터
curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/latest/?ordering=disk-usage" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

정렬 기준 지표에 값이 없는 서버는 방향과 관계없이 항상 맨 뒤로 밀립니다. -net으로 정렬해도 네트워크 트래픽을 한 번도 보고하지 않은 서버가 맨 앞에 나오는 일은 없습니다. state=stale이나 state=no_data와 함께 쓰면, 보고가 밀린 서버와 값이 단순히 낮은 서버를 구분할 수 있습니다.

오류 코드