경고 규칙 API
엔드포인트: /api/metrics/alert-rules/
경고 규칙은 에이전트가 이미 보낸 데이터를 사용해 서버의 지표를 감시하다가 값이 설정한 방향으로 임계값을 지나면 경고를 발생시킵니다. 규칙은 Alpacon이 자체 일정에 따라 약 1분마다 평가합니다. 규칙이 발생하고 해제되는 방식은 메트릭 알림을 참고하세요.
기본으로 생성되는 디스크 사용률 규칙(모든 서버가 플랜과 관계없이 갖는 규칙)을 포함해, 모든 동작에 워크스페이스의 Metrics 확장 기능이 켜져 있어야 합니다. 그 규칙은 확장 기능이 꺼진 워크스페이스에서도 계속 평가되며, 다만 그 상태를 이 API로는 확인할 수 없습니다.
규칙 수정 및 삭제 권한
워크스페이스 관리자는 모든 규칙을 수정하거나 삭제할 수 있습니다. 역할에 워크스페이스 전체 범위의 alert_rule:update(PUT/PATCH용) 또는 alert_rule:delete 권한이 있는 사용자도 마찬가지입니다. 기본 제공 operator 역할은 두 권한을 모두 가지며, member 역할은 둘 다 갖지 않습니다. 규칙을 만들었다고 해서 작성자에게 그 규칙에 대한 별도 권한이 생기지는 않습니다.
이 역할과 별개로, 관리자는 워크스페이스 전체 역할을 바꾸지 않고도 특정 사용자, 그룹, 또는 서비스 토큰의 Application에 규칙 하나만 수정하고 삭제할 권한을 줄 수 있습니다. 이 권한은 RBAC 역할 API를 통해 해당 규칙에 명시적으로 alert_rule:maintainer 바인딩을 부여하는 방식으로 설정하며, 콘솔의 역할 선택 화면은 아직 권한 범위를 규칙 하나로 좁히지 못합니다. 서비스 토큰은 이런 바인딩이 있어야만 규칙에 접근할 수 있고, Application이 가진 워크스페이스 전체 역할은 operator라도 그것만으로는 규칙에 접근하지 못합니다. 개인 API 토큰은 발급받은 사용자로 동작하므로, 그 사용자의 역할과 바인딩을 그대로 따릅니다.
Alpacon이 이 바인딩을 작성자에게 자동으로 부여하던 시기에 만들어진 규칙은 그때 작성자에게 준 바인딩을 여전히 가지고 있을 수 있으며, Alpacon이 이런 옛 바인딩을 정리할 때까지 그 작성자는 계속 규칙을 수정하고 삭제할 수 있습니다.
기본 규칙
CPU 사용률, 메모리 사용률을 비롯해 기본으로 지정된 코어 외 확장 규칙은 다른 규칙과 마찬가지로 alert_rule:update 권한이 있는 누구나 수정할 수 있습니다. 기본 규칙은 기본 상태로 지정된 동안에는 누가 요청하든 삭제할 수 없습니다. 경고 규칙 삭제를 참고하세요.
핵심 디스크 사용률 규칙
모든 워크스페이스에는 Metrics 확장 기능이 켜져 있는지와 관계없이 항상 동작하는 기본 디스크 사용률 규칙(is_default: true, 대상 disk-usage)이 있습니다. 다음은 워크스페이스 관리자만 할 수 있습니다.
PUT또는PATCH로 이 규칙을 수정- 장치와 관계없이
is_default: true이고 대상이disk-usage인 규칙을 새로 만들거나, 기존 규칙을 그렇게 바꾸는 것 - 이 규칙에 대한 서버 오버라이드를 생성·수정·삭제하거나, 오버라이드를 이 규칙으로 옮기거나 이 규칙에서 다른 규칙으로 옮기는 것
- 서버 API의 규칙 분리(detach-rule) 액션이나
rules에서 이 규칙을 뺀 서버 수정을 통해 서버에서 이 규칙을 분리하는 것
operator, 이 규칙에 대한 바인딩을 가진 주체, 모든 서비스 토큰을 포함해 그 밖의 누구든 403 metrics_alert_rule_core_admin_only를 받습니다. 이 규칙을 서버에 다시 붙이는 것은 이 제한을 받지 않으며, 이 규칙을 이미 읽을 수 있는 사람이라면 수신자나 평가 미리보기도 그대로 쓸 수 있습니다.
목록
경고 규칙 목록 조회
경고 규칙 목록을 페이지네이션하여 가져옵니다.
요청
GET /api/metrics/alert-rules/쿼리 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
name | string | 규칙 이름으로 필터링 |
target | string | 대상 지표로 필터링 |
threshold | number | 임계값으로 필터링 |
operator | string | 방향으로 필터링 (gte 또는 lte) |
device | string | 장치로 필터링 |
severity | string | 심각도로 필터링 (critical, warning, info) |
is_default | boolean | 기본 규칙 여부로 필터링 |
server | string (UUID) | 이 서버에 붙은 규칙만 조회 |
exclude_server | string (UUID) | 이 서버에 붙지 않은 규칙만 조회 |
search | string | 이름, 대상, 기본 규칙 여부로 검색 |
ordering | string | 정렬 순서. 기본값: -added_at |
page | integer | 페이지 번호 |
page_size | integer | 페이지당 결과 수 (기본값: 15, 최대: 100) |
응답
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "3f1c9b2e-6a4d-4e8f-9b1a-2c3d4e5f6a7b",
"name": "Core disk usage",
"target": "disk-usage",
"threshold": 80,
"operator": "gte",
"duration_s": 0,
"recovery_threshold": 78,
"no_data_after_s": null,
"device": "",
"severity": "warning",
"notify_email": "all",
"notify_slack_channel": true,
"is_default": true
},
{
"id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
"name": "Sustained high CPU",
"target": "cpu-usage",
"threshold": 80,
"operator": "gte",
"duration_s": 300,
"recovery_threshold": 70,
"no_data_after_s": 600,
"device": "",
"severity": "critical",
"notify_email": "admins",
"notify_slack_channel": false,
"is_default": false
}
]
}필요한 스코프: alert_rule:read
예시
curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/alert-rules/?target=cpu-usage" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""오류 코드
| 상태 | 오류 코드 | 설명 |
|---|---|---|
| 400 | metrics_alert_rule_exists | 이 대상과 장치 조합에 이미 기본 규칙이 있음 |
| 400 | metrics_alert_rule_recovery_threshold_invalid | recovery_threshold가 threshold의 회복하는 쪽에 있지 않음 |
| 400 | metrics_alert_rule_override_recovery_threshold_invalid | operator, threshold, recovery_threshold를 수정하면 어떤 서버 오버라이드의 회복 임계값이 발동하는 쪽에 남게 됨 |
| 400 | metrics_alert_rule_duration_too_short | duration_s가 0보다 크지만 이 대상의 수집 주기 2회분보다 짧음 |
| 400 | metrics_alert_rule_override_duration_too_short | target을 수정하면 어떤 서버 오버라이드의 양수 duration_s가 새 대상의 하한(수집 주기 2회분)보다 짧아짐 |
| 400 | metrics_alert_rule_no_data_window_too_short | no_data_after_s가 이 대상의 수집 간격보다 짧음 |
| 400 | metrics_alert_rule_no_data_window_too_long | no_data_after_s가 86400초(24시간)보다 김 |
| 400 | metrics_alert_rule_device_not_supported | 서버 전체를 대상으로 하는 지표(cpu-usage, memory-usage)에 device를 지정함 |
| 400 | metrics_alert_rule_cannot_be_deleted | is_default가 true인 규칙을 삭제하려고 함 |
| 400 | metrics_alert_rule_destination_not_allowed | 로그인한 워크스페이스 멤버가 아니라 애플리케이션이나 서비스 토큰이 notify_email 또는 notify_slack_channel을 설정하려고 함 |
| 400 | server_not_found | 평가 미리보기의 servers에 볼 수 없거나 존재하지 않는 서버를 지정함 |
| 400 | metrics_alert_rule_preview_window_too_long | 평가 미리보기의 window_s가 604800초(7일)보다 김 |
| 400 | metrics_alert_rule_preview_too_many_servers | 평가 미리보기에 서버를 20대 넘게 지정했거나, 서버 수 × window_s가 5 × 604800을 넘음 |
| 400 | metrics_alert_rule_preview_too_many_samples | 평가 미리보기가 읽거나 판정해야 할 샘플 행이 300,000행을 넘음 |
| 400 | metrics_alert_rule_preview_servers_required | 평가 미리보기에 rule_id와 servers 둘 다 없음 |
| 401 | UNAUTHORIZED | 유효하지 않거나 누락된 인증 정보 |
| 403 | metrics_alert_rule_core_admin_only | 워크스페이스 관리자가 아닌 주체가 핵심 디스크 사용률 규칙을 수정하려고 했거나, 규칙을 만들거나 대상을 바꿔 이 규칙으로 만들려고 함 |
| 403 | FORBIDDEN | 권한 부족, 또는 이 워크스페이스에서 Metrics 확장 기능이 꺼져 있음 |
| 404 | NOT_FOUND | 경고 규칙을 찾을 수 없음 |
규칙 자체의 값이 문제라면 먼저 확인되어 위의 오버라이드가 아닌 코드로 거부됩니다. 두 오버라이드 코드는 규칙에 달린 모든 오버라이드를 다 판정한 뒤에 거부되며, field_errors는 영향을 받은 오버라이드마다 overrides.<서버 id>.recovery_threshold 또는 overrides.<서버 id>.duration_s 경로를 씁니다. 한 서버가 둘 다에 걸리면 두 경로가 함께 실립니다. 호출자가 해당 서버를 볼 수 없으면 overrides.* 경로 없이 같은 코드의 non_field_errors만 담깁니다. 규칙 오버라이드 API로 오버라이드를 직접 고칠 때의 오류 코드는 바뀌지 않습니다.