모니터링·알림 도구
이 도구들은 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 | 리소스 사용량 기준 서버 순위 | 읽기 전용 |
get_server_metrics_summary | 서버의 CPU·메모리·디스크·네트워크 통합 요약 | 읽기 전용 |
list_alerts | 필터링 가능한 발생 알림 목록 | 읽기 전용 |
get_alert | 알림 단건 상세 정보 | 읽기 전용 |
mute_alert | 알림 통지 일시 중단 | 추가적 |
get_alert_rules | 구성된 알림 규칙과 임계값 | 읽기 전용 |
create_alert_rule | 새 알림 규칙 생성 | 추가적 |
update_alert_rule | 기존 알림 규칙 수정 | 멱등적 쓰기 |
delete_alert_rule | 알림 규칙 영구 삭제 | 파괴적 |
메트릭
시계열 메트릭 도구 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는 현재 시각으로 기본 설정됩니다.
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시간 리소스 사용량 기준으로 상위 서버를 조회합니다. 한 번의 호출로 여러 메트릭 유형을 동시에 조회할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
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, mute_alert는 규칙이 만들어낸 알림을 다룹니다.
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은 왜 발생한 거야?”
해당 알림을 발생시킨 규칙과 메트릭 값을 포함한 전체 알림 레코드를 반환합니다.
mute_alert
알림을 음소거해 통지를 일시적으로 중단합니다. 이미 원인을 파악하고 조치 중인 알림에 대해 반복 알림을 멈추고 싶을 때 사용하며, 규칙 자체를 비활성화하지는 않습니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
alert_id | string | 예 | 음소거할 알림 ID |
duration | integer | 아니오 | 음소거 시간(분) |
예시
“그 디스크 공간 알림, 지금 조치 중이니까 2시간만 음소거해줘”
지정한 시간 동안 해당 알림의 통지를 중단합니다.
get_alert_rules
워크스페이스에서 서버에 구성된 모니터링 알림 규칙과 알림 임계값을 조회합니다. 특정 서버로 필터링할 수 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 아니오 | 특정 서버로 규칙 필터링 |
예시
“데이터베이스 서버에 설정된 알림 규칙을 보여줘”
각 규칙의 조건, 임계값, 알림 설정을 반환합니다.
create_alert_rule
모니터링 임계값과 알림 방식을 정의하는 알림 규칙을 생성합니다. CPU, 메모리, 디스크 메트릭에 대한 새 모니터링을 구성할 때 사용합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 알림 규칙 이름 |
metric_type | string | 예 | 모니터링할 메트릭(예: cpu, memory, disk) |
condition | string | 예 | 조건 연산자(예: gt, lt, gte, lte) |
threshold | number | 예 | 알림을 발생시키는 임계값 |
servers | array | 아니오 | 규칙을 적용할 서버 ID 목록 |
notification_channels | array | 아니오 | 알림 채널 ID 목록 |
description | string | 아니오 | 규칙 설명 |
enabled | boolean | 아니오 | 규칙 활성화 여부. 기본값 true |
예시
“웹 서버 중 하나라도 메모리 사용률이 90%를 넘으면 알려줘”
metric_type="memory", condition="gt", threshold=90으로 지정한 서버들을 대상으로 하는 규칙을 생성합니다.
update_alert_rule
기존 알림 규칙을 수정합니다. 호출 시 전달한 필드만 변경되며, 수정 가능한 필드 중 최소 하나는 전달해야 합니다. 규칙을 다시 만들지 않고 임계값이나 알림 설정을 조정할 때 사용합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
rule_id | string | 예 | 수정할 알림 규칙 ID |
name | string | 아니오 | 새 이름 |
metric_type | string | 아니오 | 새 메트릭 유형 |
condition | string | 아니오 | 새 조건 연산자 |
threshold | number | 아니오 | 새 임계값 |
servers | array | 아니오 | 새 서버 ID 목록 |
notification_channels | array | 아니오 | 새 알림 채널 ID 목록 |
description | string | 아니오 | 새 설명 |
enabled | boolean | 아니오 | 규칙 활성화/비활성화 |
예시
“db-02의 CPU 알림 임계값을 95%로 올려줘”
해당 규칙의 threshold만 갱신하고 나머지 필드는 그대로 유지합니다.
delete_alert_rule
알림 규칙을 영구적으로 삭제합니다. 더 이상 필요하지 않은 규칙을 제거할 때 사용합니다.
접근 수준: 파괴적
알림 규칙 삭제는 되돌릴 수 없습니다. 나중에 다시 필요할 수 있다면 삭제 대신 update_alert_rule로 enabled: false를 설정해 비활성화하는 것을 고려하세요.
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
rule_id | string | 예 | 삭제할 알림 규칙 ID |
예시
“폐기된 서버의 오래된 디스크 공간 알림 규칙을 삭제해줘”
규칙을 영구적으로 제거하며, 즉시 평가와 알림 발생을 멈춥니다.