모니터링·알림 도구
이 도구들은 AI 클라이언트가 서버의 실시간 성능 메트릭과 이를 감시하는 알림 규칙에 접근할 수 있게 해줍니다. “web-01의 현재 부하가 어느 정도인지”, “디스크 I/O를 가장 많이 쓰는 서버는 어디인지”, “데이터베이스 서버의 메모리 사용률이 높을 때 알림을 설정해줘” 같은 요청에 대응합니다.
모든 도구는 workspace(필수)와 region(선택, 미지정 시 설정된 리전 사용)을 공통으로 받습니다. 아래 표에서는 이 파라미터를 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
get_cpu_usage | 서버의 CPU 사용률 통계 | 읽기 전용 |
get_memory_usage | 서버의 메모리 사용률 통계 | 읽기 전용 |
get_disk_usage | 디바이스·파티션 단위 디스크 사용량 | 읽기 전용 |
get_disk_io | 서버의 디스크 읽기/쓰기 처리량 | 읽기 전용 |
get_network_traffic | 서버의 네트워크 대역폭·패킷 속도 | 읽기 전용 |
get_top_servers | 리소스 사용량 기준 상위 5개 서버 | 읽기 전용 |
get_server_metrics_summary | 서버의 CPU·메모리·디스크·네트워크 통합 요약 | 읽기 전용 |
list_alerts | 필터링 가능한 발생 알림 목록 | 읽기 전용 |
get_alert | 알림 단건 상세 정보 | 읽기 전용 |
acknowledge_alert | 알림을 확인 또는 해제로 표시 | 추가적 |
get_alert_rules | 구성된 알림 규칙과 임계값 | 읽기 전용 |
create_alert_rule | 새 알림 규칙 생성 | 추가적 |
update_alert_rule | 기존 알림 규칙 수정 | 멱등적 쓰기 |
delete_alert_rule | 알림 규칙 영구 삭제 | 파괴적 |
attach_alert_rule | 기존 규칙을 서버에 연결 | 멱등적 쓰기 |
detach_alert_rule | 서버에서 규칙 연결 해제 | 멱등적 쓰기 |
get_alert_rule_recipients | 알림 규칙이 누구에게 알릴지 개수로 미리보기 | 읽기 전용 |
list_rule_overrides | 워크스페이스 규칙에 대한 서버별 예외 목록, 필터링 가능 | 읽기 전용 |
get_rule_override | 규칙 예외 단건 상세 정보 | 읽기 전용 |
create_rule_override | 규칙에 대한 서버별 예외 생성 | 추가적 |
update_rule_override | 기존 규칙 예외 수정 | 멱등적 쓰기 |
delete_rule_override | 규칙 예외 영구 삭제 | 파괴적 |
메트릭
시계열 메트릭 도구 5종(get_cpu_usage, get_memory_usage, get_disk_usage, get_disk_io, get_network_traffic)은 모두 start_date, end_date를 ISO 8601 형식(예: 2024-01-01T00:00:00Z)으로 받습니다. start_date를 생략하면 현재 시각으로부터 24시간 전으로 기본 설정됩니다. end_date는 선택 파라미터로, 생략하면 요청에 종료 시점을 전달하지 않으며 실제 상한값은 API가 결정합니다.
get_cpu_usage
지정한 시간 범위 동안 서버의 CPU 사용률 메트릭을 조회합니다. 현재값, 평균, 최소, 최대 사용률과 현재값을 기준으로 산출한 상태(health status)를 반환합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 메트릭을 조회할 서버 ID |
start_date | string | 아니오 | 조회 시작 시각, ISO 8601(예: 2024-01-01T00:00:00Z). 기본값은 24시간 전 |
end_date | string | 아니오 | 조회 종료 시각, ISO 8601(예: 2024-01-02T00:00:00Z) |
예시
“web-01의 지난 24시간 CPU 사용률을 보여줘”
클라이언트가 web-01을 서버 ID로 변환한 뒤 현재값, 평균, 최소, 최대 CPU 사용률과 상태(idle, low, moderate, high, critical)를 반환합니다.
get_memory_usage
지정한 시간 범위 동안 서버의 메모리(RAM) 사용률 메트릭을 조회합니다. 현재값, 평균, 최소, 최대 사용률과 상태를 반환합니다. 메모리 압박이나 OOM 문제를 조사할 때 유용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 메트릭을 조회할 서버 ID |
start_date | string | 아니오 | 조회 시작 시각, ISO 8601. 기본값은 24시간 전 |
end_date | string | 아니오 | 조회 종료 시각, ISO 8601 |
예시
“db-02가 메모리 부족 상태인지 확인해줘”
기본적으로 최근 24시간의 메모리 사용률 통계를 반환하며, idle, low, moderate, high, critical 중 하나로 상태를 표시하는 필드가 포함됩니다.
get_disk_usage
서버의 디스크 사용량을 디바이스 또는 파티션 단위로 조회합니다. 사용률과 total/used/free 용량을 사람이 읽기 쉬운 단위로 반환합니다. device 또는 partition 중 하나를 지정할 수 있고, 둘 다 생략하면 서버에서 사용 가능한 디바이스 목록을 자동으로 조회해 첫 번째 디바이스를 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 메트릭을 조회할 서버 ID |
device | string | 아니오 | 디바이스 경로(예: /dev/sda1). partition도 생략하면 자동 탐지 |
partition | string | 아니오 | 파티션 경로(예: /) |
start_date | string | 아니오 | 조회 시작 시각, ISO 8601. 기본값은 24시간 전 |
end_date | string | 아니오 | 조회 종료 시각, ISO 8601 |
예시
“app-03의 루트 파티션에 디스크 공간이 얼마나 남았어?”
해당 디바이스 또는 파티션의 현재값, 평균, 최소, 최대 사용률과 total/used/free 용량을 반환합니다.
get_disk_io
서버의 디스크 읽기/쓰기 처리량 메트릭을 조회합니다. 디바이스별 최대/평균 전송 속도를 반환합니다. 스토리지 성능 병목을 진단할 때 유용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 디스크 I/O 메트릭을 조회할 서버 ID |
device | string | 아니오 | 디스크 디바이스명(예: sda, nvme0n1) |
start_date | string | 아니오 | 조회 시작 시각, ISO 8601. 기본값은 24시간 전 |
end_date | string | 아니오 | 조회 종료 시각, ISO 8601 |
예시
“데이터베이스 서버의 지난 1시간 디스크 I/O를 확인해줘”
요청한 디바이스와 시간 범위에 대한 읽기/쓰기 처리량 데이터를 반환합니다.
get_network_traffic
서버의 네트워크 대역폭·트래픽 메트릭을 인터페이스 단위로 조회합니다. 입력/출력 처리량(bps)과 패킷 속도(pps)의 현재값, 평균, 최대값을 반환합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 메트릭을 조회할 서버 ID |
interface | string | 아니오 | 네트워크 인터페이스(예: eth0) |
start_date | string | 아니오 | 조회 시작 시각, ISO 8601. 기본값은 24시간 전 |
end_date | string | 아니오 | 조회 종료 시각, ISO 8601 |
예시
“오늘 로드밸런서의 네트워크 처리량이 어느 정도야?”
서버 인터페이스의 현재값, 평균, 최대 입력/출력 대역폭과 패킷 속도를 반환합니다.
get_top_servers
워크스페이스에서 지난 24시간 리소스 사용량 기준 상위 5개 서버를 조회합니다. 메트릭 유형별로 결과가 5개로 고정되며 조정할 수 없습니다. 한 번의 호출로 여러 메트릭 유형을 동시에 조회할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
metric_types | string | 아니오 | 쉼표로 구분한 메트릭 유형: cpu, memory, disk_io, traffic. 비워두면 4종 전체 조회 |
예시
“지금 CPU와 메모리를 가장 많이 쓰는 서버는 어디야?”
metric_types="cpu,memory"로 호출하면 두 메트릭의 순위 결과를 하나의 응답으로 반환합니다.
get_server_metrics_summary
단일 서버의 CPU, 메모리, 디스크, 네트워크 데이터 가용성을 하나의 압축된 응답으로 결합한 종합 모니터링 개요를 조회합니다. 빠른 상태 점검이나 개별 메트릭 도구로 더 깊이 조사하기 전의 출발점으로 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 메트릭을 조회할 서버 ID |
hours | integer | 아니오 | 요약할 과거 시간(시간 단위). 기본값 24, 최대 168(1주일)로 제한 |
예시
“web-01 상태를 빠르게 점검해줘”
요청한 기간에 대해 CPU, 메모리, 디스크, 네트워크 데이터의 가용성을 요약하고, 전체 시계열 데이터가 필요하면 어떤 전용 도구를 쓰면 되는지 안내합니다.
알림
알림 규칙(alert rule)은 알림을 발생시키는 임계값을 정의하고, 알림(alert)은 그 규칙이 실제로 발생시킨 개별 통지입니다. get_alert_rules와 아래의 CRUD 도구들은 모두 규칙을 다루며, list_alerts, get_alert, acknowledge_alert는 규칙이 만들어낸 알림을 다룹니다. attach_alert_rule과 detach_alert_rule은 규칙을 감시 대상 서버에 연결·해제하며, 규칙 전체를 바꾸지 않고 서버 하나만 다르게 설정하려면 아래 규칙 예외를 참고하세요.
list_alerts
워크스페이스의 알림 목록을 조회합니다. 서버, 상태, 확인/해제 상태로 필터링할 수 있습니다. 활성 알림 확인이나 알림 이력 검토에 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 서버 ID로 필터링 |
status | string | 아니오 | 알림 상태로 필터링 |
acknowledged | boolean | 아니오 | 확인 상태로 필터링(false는 아직 확인하지 않은 활성 알림) |
dismissed | boolean | 아니오 | 해제 상태로 필터링 |
page | integer | 아니오 | 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“프로덕션 서버의 활성 알림을 보여줘”
acknowledged=false로 필터링된 알림을 반환해 아직 확인하지 않은 알림만 표시합니다.
get_alert
특정 알림의 상세 정보를 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
alert_id | string | 예 | 조회할 알림 ID |
예시
“알림 abc-123은 왜 발생한 거야?”
해당 알림을 발생시킨 규칙과 메트릭 값을 포함한 전체 알림 레코드를 반환합니다.
acknowledge_alert
알림에 확인 기록을 남깁니다. 확인(checked, 봤다는 표시) 또는 해제(dismissed, 대응할 필요 없다는 표시) 중 하나로 지정할 수 있습니다. 사용자당 알림 하나에 확인은 한 번만 가능하며 이후에는 변경할 수 없습니다. 같은 알림에 다시 호출하면 거부됩니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
alert_id | string | 예 | 확인할 알림 ID |
action_type | string | 예 | checked 또는 dismissed |
예시
“그 디스크 공간 알림은 확인했다고 표시해줘, 나중에 처리할게”
action_type="checked"로 acknowledge_alert를 호출합니다. 이후 acknowledged=false로 필터링한 list_alerts 결과에는 이 알림이 더 이상 나타나지 않습니다.
get_alert_rules
워크스페이스에서 서버에 구성된 모니터링 알림 규칙을 조회합니다. 특정 서버로 필터링할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 특정 서버로 규칙 필터링 |
예시
“데이터베이스 서버에 설정된 알림 규칙을 보여줘”
각 규칙의 전체 정의(이름, 대상 지표, 임계값, operator, 지속 시간, 복귀 임계값, 데이터 없음 감지 시간, 장치, 심각도, 이메일 수신 대상, Slack 채널 게시 여부, 워크스페이스 기본 규칙 여부)를 반환합니다.
create_alert_rule
워크스페이스 단위로 지표 하나를 지켜보는 알림 규칙을 생성합니다. CPU, 메모리, 디스크 사용률 등이 대상입니다. 규칙을 만들려면 유료 플랜이 필요하며, 대상 하나당 기본 규칙은 하나만 지정할 수 있습니다. 규칙을 생성해도 서버에 자동으로 연결되지는 않으므로, 이후 attach_alert_rule로 서버에 붙여야 합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 알림 규칙 이름(워크스페이스 내에서 고유해야 함) |
target | string | 예 | 지켜볼 대상 지표(예: cpu-usage, memory-usage, disk-usage, 또는 대역폭·패킷 속도의 최대/평균 지표 중 하나) |
threshold | number | 예 | 알림을 발생시키는 기준값 |
is_default | boolean | 아니오 | 이 규칙을 대상의 기본 규칙으로 지정합니다. 이후 등록되는 모든 서버에 자동으로 적용됩니다. 기본값 false |
operator | string | 아니오 | 임계값의 어느 쪽을 넘을 때 발화할지: gte(기본값)는 이상일 때, lte는 이하일 때 발화 |
duration_s | integer | 아니오 | 조건이 발화하기까지 유지되어야 하는 시간(초). 0(기본값)은 한 번의 임계값 초과 샘플만으로 발화. 0보다 크게 설정할 때는 대상의 수집 주기 2회분 이상이어야 하며, 그보다 짧으면 400(metrics_alert_rule_duration_too_short)으로 거부됨 |
recovery_threshold | number | 아니오 | 알림이 해제되기 위해 되돌아가야 하는 값. 생략하면 임계값 자체가 해제 기준이 됨 |
no_data_after_s | integer | 아니오 | 이 시간(초) 동안 새 샘플이 없으면 알림을 발생 |
device | string | 아니오 | 규칙을 디스크·파티션·네트워크 인터페이스 하나로 좁힙니다. 장치 단위 대상(디스크 사용률, 디스크 I/O, 네트워크)에만 지정 가능하며, cpu-usage와 memory-usage는 서버 전체 단위라 거부됨 |
severity | string | 아니오 | 발생한 알림의 심각도: critical, warning(기본값), info 중 하나. critical만 이메일을 보낼 수 있고, critical과 warning은 Slack에 게시할 수 있으며, info는 notify_email·notify_slack_channel 값과 관계없이 둘 다 보내지 않음 |
notify_email | string | 아니오 | 경고 메일을 받을 대상. 이미 서버를 볼 수 있는 사람 중에서 고름: all(기본값), admins, group_members, none. 사람만 설정 가능하며, 서비스 토큰이나 에이전트가 이 값을 지정하면 400(metrics_alert_rule_destination_not_allowed)으로 거부됨. critical 심각도 규칙에서만 실제로 작동함 |
notify_slack_channel | boolean | 아니오 | 발생과 해제를 워크스페이스에 연결된 Slack 채널에 게시할지 여부. 기본값 true. notify_email과 같은 사람 전용 제한이 적용됨. critical과 warning 심각도에서 작동하며 info에서는 작동하지 않음 |
예시
“웹 서버 중 하나라도 메모리 사용률이 90%를 5분 넘게 초과하면 알려줘”
target="memory-usage", threshold=90, duration_s=300으로 규칙을 생성해 잠깐의 스파이크로는 발화하지 않게 합니다. 감시할 서버는 이어서 attach_alert_rule로 연결합니다.
update_alert_rule
기존 알림 규칙을 수정합니다. 호출 시 전달한 필드만 변경되며, 수정 가능한 필드 중 최소 하나는 전달해야 합니다. 규칙을 다시 만들지 않고 임계값을 조정하거나 이름을 바꿀 때 사용합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
rule_id | string | 예 | 수정할 알림 규칙 ID |
name | string | 아니오 | 새 이름 |
target | string | 아니오 | 새 대상 지표 |
threshold | number | 아니오 | 새 임계값 |
is_default | boolean | 아니오 | 이 규칙을 대상의 기본 규칙으로 지정 |
operator | string | 아니오 | gte는 임계값 이상일 때, lte는 이하일 때 발화 |
duration_s | integer | 아니오 | 조건이 발화하기까지 유지되어야 하는 시간(초). 0은 한 번의 임계값 초과 샘플만으로 발화. 0보다 크게 설정할 때는 대상의 수집 주기 2회분 이상이어야 하며, 그보다 짧으면 400(metrics_alert_rule_duration_too_short)으로 거부됨 |
recovery_threshold | number | 아니오 | 알림이 해제되기 위해 되돌아가야 하는 값. 생략하면 임계값 자체가 해제 기준이 됨 |
no_data_after_s | integer | 아니오 | 이 시간(초) 동안 새 샘플이 없으면 알림을 발생 |
device | string | 아니오 | 규칙을 디스크·파티션·네트워크 인터페이스 하나로 좁힙니다. 장치 단위 대상에만 지정 가능 |
severity | string | 아니오 | 발생한 알림의 심각도: critical, warning, info 중 하나. critical만 이메일을 보낼 수 있고, critical과 warning은 Slack에 게시할 수 있으며, info는 notify_email·notify_slack_channel 값과 관계없이 둘 다 보내지 않음 |
notify_email | string | 아니오 | 경고 메일을 받을 대상: all, admins, group_members, none. create_alert_rule과 같은 사람 전용 제한과 심각도별 동작이 적용됨. 생략하면 규칙에 이미 설정된 값이 그대로 유지됨 |
notify_slack_channel | boolean | 아니오 | 발생과 해제를 워크스페이스에 연결된 Slack 채널에 게시할지 여부. create_alert_rule과 같은 사람 전용 제한과 심각도별 동작이 적용됨. 생략하면 규칙에 이미 설정된 값이 그대로 유지됨 |
예시
“db-02의 CPU 알림 임계값을 95%로 올려줘”
해당 규칙의 threshold만 갱신하고 나머지 필드는 그대로 유지합니다.
delete_alert_rule
알림 규칙을 영구적으로 삭제합니다. 더 이상 필요하지 않은 규칙을 제거할 때 사용합니다.
접근 수준: 파괴적
알림 규칙 삭제는 되돌릴 수 없습니다. 다른 서버의 규칙은 그대로 두고 특정 서버에서만 이 규칙 적용을 멈추고 싶다면, 삭제 대신 detach_alert_rule을 사용하세요. 연결 해제나 삭제 대신, 서버 하나만 예외로 두고 나머지 플릿에서는 규칙을 계속 적용하고 싶다면 create_rule_override를 enabled=false로 호출하세요.
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
rule_id | string | 예 | 삭제할 알림 규칙 ID |
예시
“폐기된 서버의 오래된 디스크 공간 알림 규칙을 삭제해줘”
규칙을 영구적으로 제거하며, 즉시 평가와 알림 발생을 멈춥니다.
attach_alert_rule
기존 알림 규칙을 서버에 연결해 그 규칙이 해당 서버를 감시하도록 합니다. create_alert_rule로 규칙을 만든 뒤 이어서 호출해 실제로 작동시킬 때 사용합니다. 규칙을 생성하는 것만으로는 아무 서버에도 연결되지 않습니다. 이미 연결된 서버에 다시 연결해도 아무것도 바뀌지 않으므로 안전하게 재시도할 수 있습니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 규칙이 감시할 서버 |
rule_id | string | 예 | 연결할 알림 규칙 |
예시
“새 메모리 알림 규칙을 web-01, web-02, web-03에 적용해줘”
에이전트가 서버마다 한 번씩 규칙 ID와 함께 attach_alert_rule을 호출합니다.
detach_alert_rule
서버에서 알림 규칙 연결을 해제해 그 서버를 더 이상 감시하지 않게 합니다. 규칙 자체는 삭제되지 않으며, 연결된 다른 서버에서는 계속 감시합니다. 애초에 연결되어 있지 않던 서버에 대해 호출해도 아무것도 바뀌지 않습니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 감시를 멈출 서버 |
rule_id | string | 예 | 연결 해제할 알림 규칙 |
예시
“CPU 알림 규칙이 db-02는 감시하지 않게 해줘, 다른 서버는 그대로 두고”
에이전트가 db-02의 서버 ID와 규칙 ID로 detach_alert_rule을 호출합니다. 연결된 다른 모든 서버에서는 규칙이 계속 평가됩니다.
get_alert_rule_recipients
알림 규칙이 실제로 발생하기 전에, 그 규칙이 누구에게 알릴지 개수로만(이름 없이) 미리 확인합니다.
alpacon-server 2.36.0 이상이 필요합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
rule_id | string | 예 | 미리볼 알림 규칙 ID |
예시
“db-02의 CPU 알림이 지금 발생하면 몇 명이 알림을 받아?”
email(notify_email 값을 그대로 담은 mode, count, admins/group_members/owner별로 나눈 reasons. 이 셋은 겹칠 수 있어 합이 count와 같지 않을 수 있음), slack_channel(notify_slack_channel 값을 그대로 담은 enabled, 워크스페이스에 쓸 수 있는 Slack 설치가 있는지를 나타내는 connected), event_subscriptions(두 수신 대상 설정과 무관한 기계 구독 수)를 반환합니다. 심각도가 warning이나 info인 규칙은 notify_email 값과 관계없이 email.count가 0입니다(직접 메일을 보내는 것은 critical 규칙뿐). info 규칙은 slack_channel.enabled/.connected 값이 그대로 나와도 실제로는 아무 데도 게시하지 않습니다.
규칙이 붙어 있고 실제로 발생시킬 수 있는 서버 중 내가 볼 수 있는 서버만 대상으로 셉니다. get_alert_rules로는 잘 조회되는 규칙인데 여기서 404가 나온다면, 그 규칙의 서버가 전부 내가 볼 수 없는 서버라는 뜻이지 규칙이 사라진 게 아닙니다. 어떤 서버에도 붙지 않은 규칙은 0을 반환합니다.
규칙 예외
규칙 예외(rule override)는 워크스페이스 알림 규칙에 대한 서버별 예외입니다. 특정 서버 하나만 다른 임계값, 복귀 임계값, 지속 시간을 쓰게 하거나, 아예 규칙 적용에서 제외할 수 있습니다. 예외에서 값을 지정하지 않은 필드는 그 서버에서도 규칙 자체의 값을 그대로 따릅니다. 즉, 예외는 지정한 내용만 덮어씁니다. 한 서버는 규칙 하나당 예외를 최대 하나만 가질 수 있으며, 같은 조합으로 두 번째 예외를 만들면 거부됩니다.
규칙 예외는 특정 서버 하나에 적용되는 규칙의 변형일 뿐, attach_alert_rule/detach_alert_rule을 대신하지 않습니다. 규칙이나 그 예외가 평가되려면 규칙이 해당 서버에 먼저 연결되어 있어야 합니다.
list_rule_overrides
워크스페이스에 설정된 규칙 예외 목록을 조회합니다. 서버, 규칙, 활성 상태로 필터링해 어떤 서버가 워크스페이스 규칙과 다르게 동작하는지 감사할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 이 서버에 대한 예외로 필터링 |
rule_id | string | 아니오 | 이 규칙에 대한 예외로 필터링 |
enabled | boolean | 아니오 | 예외의 활성 상태로 필터링. false는 해당 서버를 규칙에서 완전히 제외한다는 뜻 |
page | integer | 아니오 | 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“CPU 알림 임계값이 다른 서버들과 다른 서버가 있어?”
에이전트가 rule_id를 CPU 규칙 ID로 지정해 list_rule_overrides를 호출하고, 각 예외의 threshold를 확인합니다.
get_rule_override
규칙 예외 하나의 상세 정보를 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
override_id | string | 예 | 조회할 규칙 예외 ID |
예시
“db-02를 디스크 알림에서 제외한 그 예외를 보여줘”
에이전트가 예외 ID로 get_rule_override를 호출해 대상 server, rule, 어떤 필드를 바꾸는지 보고합니다.
create_rule_override
워크스페이스 알림 규칙에 대한 서버별 예외를 만듭니다. 특정 서버의 threshold, recovery_threshold, duration_s를 다르게 지정하거나, enabled=false로 지정해 다른 필드와 무관하게 그 서버를 규칙에서 완전히 제외할 수 있습니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 예외를 적용할 서버 |
rule_id | string | 예 | 예외를 적용할 알림 규칙 |
threshold | number | 아니오 | 이 서버의 임계값을 대체. 지정하지 않으면 규칙의 값을 그대로 따름 |
recovery_threshold | number | 아니오 | 이 서버의 복귀 임계값을 대체. 지정하지 않으면 규칙의 값을 그대로 따름 |
duration_s | integer | 아니오 | 이 서버의 지속 시간(초)을 대체. 지정하지 않으면 규칙의 값을 그대로 따르며, 0은 한 번의 초과 샘플만으로 발화 |
enabled | boolean | 아니오 | false면 다른 필드와 무관하게 이 서버를 규칙에서 완전히 제외. 기본값은 규칙과 동일한 true |
예시
“스테이징 데이터베이스는 유독 변동이 심해, 다른 서버의 규칙은 그대로 두고 이 서버의 CPU 알림 임계값만 95%로 올려줘”
에이전트가 server_id를 스테이징 데이터베이스로, rule_id를 CPU 규칙으로, threshold=95로 create_rule_override를 호출합니다.
update_rule_override
기존 규칙 예외를 수정합니다. 전달한 필드만 반영되며, 생략한 필드는 규칙의 값으로 되돌아가지 않고 예외에 설정된 현재 값을 그대로 유지합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
override_id | string | 예 | 수정할 규칙 예외 ID |
server_id | string | 아니오 | 예외를 다른 서버로 이동 |
rule_id | string | 아니오 | 예외를 다른 알림 규칙으로 이동 |
threshold | number | 아니오 | 새 임계값 예외 |
recovery_threshold | number | 아니오 | 새 복귀 임계값 예외 |
duration_s | integer | 아니오 | 새 지속 시간 예외(초) |
enabled | boolean | 아니오 | false면 이 서버를 규칙에서 완전히 제외 |
한 서버는 규칙 하나당 예외를 최대 하나만 가질 수 있습니다. 이미 예외가 있는 (server_id, rule_id) 조합으로 이동하면 실패하므로, 기존 예외를 먼저 삭제하거나 이동 대신 그 예외를 직접 수정하세요.
예시
“그 스테이징 예외의 임계값이 아직도 너무 민감해, 98%로 올려줘”
에이전트가 예외 ID와 threshold=98로 update_rule_override를 호출하며, recovery_threshold, duration_s, enabled는 그대로 둡니다.
update_rule_override로는 예외로 덮어쓴 필드 하나만 규칙의 원래 값으로 되돌릴 방법이 없습니다. 생략한 필드는 예외에 설정된 현재 값을 유지할 뿐입니다. 예외를 완전히 없애려면 delete_rule_override를 사용하세요.
delete_rule_override
규칙 예외를 영구적으로 삭제해 해당 서버를 워크스페이스 규칙의 원래 값으로 되돌립니다.
접근 수준: 파괴적
삭제는 되돌릴 수 없습니다. 해당 서버는 즉시 워크스페이스 규칙의 임계값과 설정으로 다시 평가되기 시작합니다.
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
override_id | string | 예 | 삭제할 규칙 예외 ID |
예시
“스테이징 데이터베이스의 CPU 임계값 예외를 제거해줘, 이제 플릿 규칙을 그대로 따르면 돼”
에이전트가 list_rule_overrides로 예외를 찾은 뒤, 그 ID로 delete_rule_override를 호출합니다.