경고 규칙 API

목록

경고 규칙 목록 조회

경고 규칙 목록을 페이지네이션하여 가져옵니다.

요청

GET /api/metrics/alert-rules/

쿼리 파라미터

응답

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "3f1c9b2e-6a4d-4e8f-9b1a-2c3d4e5f6a7b",
      "owner": null,
      "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",
      "owner": {
        "id": 1,
        "name": "admin",
        "email": "admin@example.com"
      },
      "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\""

생성

경고 규칙 생성

새 경고 규칙을 만듭니다.

요청

POST /api/metrics/alert-rules/

요청 본문

{
  "name": "Sustained high CPU",
  "target": "cpu-usage",
  "threshold": 80,
  "operator": "gte",
  "duration_s": 300,
  "recovery_threshold": 70,
  "no_data_after_s": 600,
  "severity": "critical",
  "notify_email": "admins",
  "notify_slack_channel": false
}

요청 파라미터

notify_email과 notify_slack_channel은 로그인한 워크스페이스 멤버만 설정할 수 있습니다. 애플리케이션이나 서비스 토큰이 이 두 필드 중 하나라도 요청에 담으면, 규칙에 이미 설정된 값과 같은 값을 보내는 경우라도 metrics_alert_rule_destination_not_allowed로 거부됩니다.

규칙을 만들었다고 해서 작성자에게 그 규칙에 대한 별도 권한이 생기지는 않습니다. 규칙 수정 및 삭제 권한을 참고하세요. 새 규칙이 is_default: true이고 대상이 disk-usage로 남는 생성 요청은 호출자가 워크스페이스 관리자가 아니면 metrics_alert_rule_core_admin_only로 거부됩니다. 핵심 디스크 사용률 규칙을 참고하세요.

응답

{
  "id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
  "owner": {
    "id": 1,
    "name": "admin",
    "email": "admin@example.com"
  },
  "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:create

예시

curl -X POST "https://your-workspace.ap1.alpacon.io/api/metrics/alert-rules/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sustained high CPU", "target": "cpu-usage", "threshold": 80, "duration_s": 300}'

조회

경고 규칙 상세 조회

특정 경고 규칙을 ID로 조회합니다.

요청

GET /api/metrics/alert-rules/{rule_id}/

경로 파라미터

응답

{
  "id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
  "owner": {
    "id": 1,
    "name": "admin",
    "email": "admin@example.com"
  },
  "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/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

수신자

수신자 미리보기

경고 규칙이 실제로 발생하기 전에, 그 규칙이 누구에게 알림을 보낼지 개수로만(이름 없이) 미리 확인합니다.

요청

GET /api/metrics/alert-rules/{rule_id}/recipients/

경로 파라미터

응답

{
  "email": {
    "mode": "group_members",
    "count": 7,
    "reasons": { "admins": 0, "group_members": 6, "owner": 1 }
  },
  "slack_channel": { "enabled": true, "connected": true },
  "event_subscriptions": 2
}

응답 어디에도 사용자 이름, 이메일, ID는 나타나지 않습니다.

규칙에 붙은 서버가 전부 내가 볼 수 없는 서버라면 404를 반환합니다. 규칙 자체를 볼 수 없을 때와 같은 응답입니다. 반면 아직 어떤 서버에도 붙지 않은 규칙은 404가 아니라 0을 반환합니다. 막 만들어 아직 서버에 붙이지 않은 상태가 그 모양이며, 거기서 404를 반환하면 저장이 실패한 것처럼 보이기 때문입니다.

필요한 스코프: alert_rule:read

예시

curl -X GET "https://your-workspace.ap1.alpacon.io/api/metrics/alert-rules/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/recipients/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

미리보기

평가 미리보기

규칙을 저장하지 않고 최근 realtime 샘플에 재생해서, 그 규칙이 언제 발생하고 해제됐을지 확인합니다. 발생과 해제 판정은 워크스페이스의 실제 규칙을 평가하는 것과 같은 평가기가 내리며, 이 API는 그 판정에 샘플을 재생해서 넣어 줄 뿐입니다.

요청

POST /api/metrics/alert-rules/preview/

요청 본문

{
  "rule": {"target": "cpu-usage", "operator": "gte", "threshold": 80,
           "duration_s": 300, "recovery_threshold": 75, "no_data_after_s": null,
           "device": "", "severity": "warning",
           "notify_email": "all", "notify_slack_channel": true},
  "rule_id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
  "servers": ["3f0e2b1c-5d6a-4e7f-8a9b-0c1d2e3f4a5b"],
  "window_s": 3600
}

요청 파라미터

rule_id나 servers 중 적어도 하나는 있어야 합니다.

위 필드 외에 상한이 두 개 더 있습니다. 서버는 최대 20대이고, 서버 수 × window_s는 5 × 604800초를 넘을 수 없습니다. 20대면 창은 약 1.75일로 줄고, 7일 전체를 쓰면 서버는 5대로 줄어듭니다. 별도로 재생이 읽거나 판정하는 샘플 행은 300,000행을 넘을 수 없으며, 디스크나 인터페이스가 많은 서버라면 서버 상한보다 먼저 이 상한에 걸릴 수 있습니다. rule_id만 보내면 servers는 그 규칙이 붙어 있는 서버로 기본값이 정해지는데, 그 기본 서버 목록이 20대를 넘으면 20대 상한에 걸려 거부되므로 이때는 servers를 직접 지정해야 합니다.

규칙을 저장할 때와 같은 수신 대상 제한이 여기에도 적용됩니다: 본문에 notify_email이나 notify_slack_channel을 담아 보내면 애플리케이션이나 서비스 토큰은 metrics_alert_rule_destination_not_allowed로 거부됩니다.

응답

{
  "window": {"start": "2026-09-01T11:00:00Z", "end": "2026-09-01T12:00:00Z"},
  "sample_interval_s": 60,
  "summary": {"episodes": 1, "would_interrupt": 1, "open_at_end": 0, "longest_s": 240},
  "servers": [
    {"server": "3f0e2b1c-5d6a-4e7f-8a9b-0c1d2e3f4a5b", "device": "", "samples": 60,
     "episodes": [
       {"condition": "threshold", "raised_at": "2026-09-01T11:50:00Z",
        "resolved_at": "2026-09-01T11:54:00Z", "peak": 91.2, "outlived_hold": true,
        "would_interrupt": true}
     ]}
  ],
  "recipients": {
    "email": {"mode": "all", "count": 3,
              "reasons": {"admins": 1, "group_members": 2, "owner": 1}},
    "slack_channel": {"enabled": true, "connected": false},
    "event_subscriptions": 0
  },
  "not_reproduced": ["tick_jitter", "state_before_window"]
}

없는 rule_id, 또는 붙어 있는 서버가 전부 내가 볼 수 없는 서버라면 404를 반환합니다. servers에 내가 볼 수 없거나 존재하지 않는 서버가 있으면 server_not_found 코드와 함께 400을 반환합니다. rule_id로 남의 규칙을 미리보는 것은 막지 않습니다. 저장하지 않는 읽기이기 때문이며, 활동 로그에도 남지 않습니다.

필요한 스코프: alert_rule:read

예시

curl -X POST "https://your-workspace.ap1.alpacon.io/api/metrics/alert-rules/preview/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"rule": {"target": "cpu-usage", "threshold": 80, "duration_s": 300}, "servers": ["3f0e2b1c-5d6a-4e7f-8a9b-0c1d2e3f4a5b"]}'

수정

경고 규칙 수정

기존 경고 규칙을 수정합니다. PATCH를 통한 부분 업데이트를 지원합니다.

요청

PATCH /api/metrics/alert-rules/{rule_id}/

경로 파라미터

요청 본문

{
  "threshold": 85,
  "recovery_threshold": 75
}

요청 파라미터

경고 규칙 생성과 같은 필드이며, 모두 선택 사항입니다. operator나 threshold를 바꾸면 이 규칙 자체의 복귀 임계값이나 서버 오버라이드의 복귀 임계값이 바뀐 값의 잘못된 쪽에 남게 될 경우, 그 수정은 거부됩니다.

특정 규칙에 접근해 수정할 수 있는 주체는 정해져 있습니다. 규칙 수정 및 삭제 권한을 참고하세요. 핵심 디스크 사용률 규칙은 워크스페이스 관리자의 PUT/PATCH만 허용하며, 그 밖의 호출자는 metrics_alert_rule_core_admin_only를 받습니다.

응답

수정된 필드를 포함한 전체 경고 규칙 객체를 반환합니다 (경고 규칙 상세 조회와 같은 스키마).

필요한 스코프: alert_rule:update

예시

curl -X PATCH "https://your-workspace.ap1.alpacon.io/api/metrics/alert-rules/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"threshold": 85, "recovery_threshold": 75}'

삭제

경고 규칙 삭제

경고 규칙을 삭제합니다. 기본 규칙(is_default: true)은 기본 상태로 지정된 채로는 삭제할 수 없습니다. 먼저 is_default를 해제하세요.

특정 규칙에 접근해 삭제할 수 있는 주체는 정해져 있습니다. 규칙 수정 및 삭제 권한을 참고하세요.

요청

DELETE /api/metrics/alert-rules/{rule_id}/

경로 파라미터

응답

204 No Content

필요한 스코프: alert_rule:delete

예시

curl -X DELETE "https://your-workspace.ap1.alpacon.io/api/metrics/alert-rules/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""