최신 지표

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

응답은 서버 목록을 페이지 단위로 반환하며, 서버마다 CPU, 메모리, 디스크 사용률, 디스크 I/O, 네트워크 최신 값을 담습니다. 워크스페이스의 메트릭 개요 화면에 표시되는 값과 같습니다. 서버 목록과 같은 필터, 검색, 페이지네이션을 지원하므로, 서버마다 따로 요청하지 않고도 여러 서버의 최신 값을 검색하거나 범위를 좁혀 조회할 수 있습니다.

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

요청

http
GET /api/metrics/latest/

쿼리 파라미터

서버 목록과 같은 필터, 검색, 페이지네이션 파라미터(name, groups, tag, is_connected, starred, os, search 등)를 지원하며, 다음 파라미터도 사용할 수 있습니다.

파라미터타입설명
statestringstale: 다섯 메트릭 중 가장 최근 샘플도 너무 오래됐거나 샘플이 전혀 없는 서버. no_data: 어떤 메트릭에도 저장된 샘플이 없는 서버. 모든 no_data 서버는 stale에도 포함
orderingstring서버 목록의 ordering 외에 sampled_at과 다섯 메트릭(cpu, memory, disk-usage 또는 disk_usage, disk-io 또는 disk_io, net)으로 정렬 가능. 앞에 -를 붙이면 내림차순. metric_severity와 -metric_severity도 지원(서버 심각도 참고). 기본값: 즐겨찾기 서버를 저장된 순서대로 먼저 표시한 뒤 name 순서로 정렬
pageinteger페이지 번호
page_sizeinteger페이지당 결과 수(기본값: 15, 최대: 100)

응답

json
{
  "count": 42,
  "current": 1,
  "next": 2,
  "previous": null,
  "last": 3,
  "summary": {
    "critical": 3,
    "warning": 7,
    "stale": 4,
    "no_data": 1
  },
  "results": [
    {
      "id": "0f3c9d2e-1a4b-4c8d-9e6f-2b7a1c5d8e30",
      "name": "web-01",
      "is_connected": true,
      "metric_severity": "warning",
      "cpu": {
        "value": 42.1,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60,
        "threshold": 80.0,
        "operator": "gte"
      },
      "memory": {
        "value": 68.4,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60,
        "threshold": 90.0,
        "operator": "gte"
      },
      "disk-usage": {
        "value": 78.0,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": "/",
        "collected": true,
        "reason": null,
        "interval_s": 60,
        "threshold": 85.0,
        "operator": "gte"
      },
      "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,
        "threshold": null,
        "operator": null
      },
      "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,
        "threshold": null,
        "operator": null
      }
    },
    {
      "id": "3b8f4c1a-7d2e-4a9b-8c5f-1e6a2b9d4c7f",
      "name": "db-01",
      "is_connected": true,
      "metric_severity": null,
      "cpu": {
        "value": 12.3,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:13:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60,
        "threshold": null,
        "operator": null
      },
      "memory": {
        "value": null,
        "unit": "percent",
        "sampled_at": null,
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60,
        "threshold": null,
        "operator": null
      },
      "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,
        "threshold": null,
        "operator": null
      },
      "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,
        "threshold": null,
        "operator": null
      },
      "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,
        "threshold": null,
        "operator": null
      }
    }
  ]
}

results의 각 항목에는 id, name, is_connected, metric_severity와 메트릭별 객체(cpu, memory, disk-usage, disk-io, net)가 하나씩 있습니다. unit은 CPU, 메모리, 디스크 사용률에서는 percent, 디스크 I/O와 네트워크에서는 bytes_per_sec입니다. device는 측정 대상 디스크나 인터페이스를 나타냅니다. 디스크 사용률은 마운트 지점, 디스크 I/O와 네트워크 합계는 all, 장치와 무관한 CPU와 메모리는 null입니다.

셀 임계값

각 메트릭 객체에는 다음 필드가 있습니다.

필드타입설명
thresholdnumber 또는 null서버별 규칙 재정의를 반영한 유효 임계값. 단위는 셀의 unit과 같음
operatorstring 또는 null값이 임계값 이상이면 gte, 임계값 이하면 lte

cpu, memory, disk-usage 셀에 적용할 규칙이 없으면 두 필드는 모두 null입니다. 서버의 에이전트 설치가 끝나지 않았거나(commissioned=false) 서버가 비활성화된 경우, 서버별 규칙 재정의로 적용 대상 규칙이 모두 꺼진 경우도 포함합니다. 적용할 규칙이 여러 개면 gte를 lte보다 우선합니다. gte 중에서는 가장 낮은 임계값을, lte 중에서는 가장 높은 임계값을 반환합니다. 장치를 지정한 디스크 규칙은 셀에 표시된 디스크와 일치할 때만 적용됩니다.

disk-io와 net의 두 필드는 항상 null입니다. 이 셀은 모든 장치의 양방향 값을 합산하지만, 규칙은 장치별로 한 방향의 값을 평가합니다.

임계값을 조회하려면 규칙 재정의 조회 권한과 rule_override:read 토큰 스코프가 필요합니다. 이 권한이 없으면 모든 셀의 threshold와 operator가 null입니다.

서버 심각도

필드타입설명
metric_severitystring 또는 null서버의 열린 metric_threshold 알림 중 가장 높은 심각도. 우선순위는 critical, warning, info 순서. 이런 알림이 없거나 호출자에게 알림 조회 권한이 없으면 null

ordering=-metric_severity는 전체 페이지에 걸쳐 critical, warning, info, null 순서로 서버를 정렬합니다. ordering=metric_severity는 그 반대 순서입니다. 심각도가 같으면 기본 서버 정렬 순서를 따릅니다.

alert:read 토큰 스코프 등 알림 조회에 필요한 권한이 없으면 metric_severity, summary.critical, summary.warning은 null이며, 심각도 정렬은 무시됩니다. 임계값 공개 여부는 규칙 재정의 조회 권한으로 별도로 결정합니다.

전체 집계

최상위 summary는 필터를 적용한 뒤 호출자가 볼 수 있는 전체 서버 수를 페이지네이션 전에 집계합니다. 검색 조건과 state 필터도 집계에 반영합니다. 알림 수가 아닌 서버 수입니다.

필드타입설명
criticalinteger 또는 nullmetric_severity가 critical인 서버 수. 알림 조회 권한이 없으면 null
warninginteger 또는 nullmetric_severity가 warning인 서버 수. critical에 집계된 서버는 제외하며, 알림 조회 권한이 없으면 null
staleintegerstate=stale에 해당하는 서버 수. 데이터가 없는 서버도 포함
no_datainteger어떤 메트릭에도 저장된 샘플이 없는 서버 수. state=no_data와 같은 조건

모든 no_data 서버는 stale에도 집계됩니다. alert:read가 없어도 stale과 no_data 집계는 조회할 수 있습니다.

필요한 스코프: metric:read

예시

bash
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는 true, reason은 null입니다. 이 엔드포인트에 접근할 수 있으면 워크스페이스에서 Metrics 확장 기능이 켜져 있다는 뜻이므로, 응답에 포함된 메트릭은 모두 수집 중입니다.

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

ordering으로 메트릭별 정렬을 할 수 있습니다. 내림차순이면 가장 바쁜 서버가, 오름차순이면 가장 한가한 서버가 먼저 나옵니다.

bash
# Highest CPU first
curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/latest/?ordering=-cpu" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
 
# Lowest disk usage first
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를 함께 쓰면 보고가 늦어진 서버와 값이 단순히 낮은 서버를 구분할 수 있습니다.

오류 코드

상태오류 코드설명
401UNAUTHORIZED유효하지 않거나 누락된 인증 정보
402workspace_extension_plan_required워크스페이스 플랜에서 Metrics 확장 기능을 지원하지 않음
403workspace_extension_not_enabled이 플랜에서 Metrics 확장 기능을 지원하지만 아직 켜지지 않음
최종 수정: