---
title: "최신 지표 API"
description: "Alpacon 최신 메트릭 API 참고 문서입니다. 요청 한 번으로 여러 서버의 CPU, 메모리, 디스크, 디스크 I/O, 네트워크 최신 값을 조회합니다. 서버 목록과 같은 필터와 정렬을 적용하고, 페이지를 나눠 워크스페이스에 속한 전체 서버의 상태를 확인할 수 있습니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# 최신 지표

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

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

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

## 요청

```http
GET /api/metrics/latest/
```

### 쿼리 파라미터

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

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

### 셀 임계값

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

| 필드 | 타입 | 설명 |
|-------|------|-------------|
| `threshold` | number 또는 null | 서버별 [규칙 재정의](/reference/api/metrics/rule-overrides/)를 반영한 유효 임계값. 단위는 셀의 `unit`과 같음 |
| `operator` | string 또는 null | 값이 임계값 이상이면 `gte`, 임계값 이하면 `lte` |

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

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

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

### 서버 심각도

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

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

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

### 전체 집계

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

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

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

필요한 스코프: [`metric:read`](/reference/scopes/#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 확장 기능](/use/servers/monitor/#모니터링-대시보드)이 켜져 있다는 뜻이므로, 응답에 포함된 메트릭은 모두 수집 중입니다.

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

`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`를 함께 쓰면 보고가 늦어진 서버와 값이 단순히 낮은 서버를 구분할 수 있습니다.

## 오류 코드

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

Source: https://docs.alpacax.com/ko/reference/api/metrics/latest/