미복구 이벤트 목록¶
POST /api/v1/events/abnormal/list
개요¶
현재 워크스페이스에서 아직 복구되지 않은 모니터 또는 사용자 정의 이벤트를 나열하고, 이벤트 연관 식별자별로 그룹화하여 최신 상태를 반환합니다.
호출 전 및 사용 단계¶
동일한 df_monitor_checker_event_ref 기준으로 그룹화하여 최신 상태가 fatal, critical, error, warning, nodata에 속하는 이벤트를 반환합니다. 통합 수집 이벤트 및 대규모 이벤트 집계는 이 목록에 포함되지 않습니다. 현재 공개 요청은 여전히 timeRange에 두 개의 밀리초 정수를 전달해야 하지만, 이 필드는 이 버전에서 조회 범위를 설정하는 데 사용되지 않으며 실제로는 서버의 현재 시각을 기준으로 과거 48시간을 사용합니다. 이 값을 사용하여 임의의 과거 구간 결과를 추론하지 마세요. 과거 범위를 지정하려면 DQL 쿼리를 사용할 수 있습니다. search는 제목과 설명을 검색하고, lastStatus는 최종 상태를 추가로 제한합니다. 기본값은 offset=0, limit=20입니다. 이후 offset을 limit만큼 증가시키며, data가 빈 값으로 반환되거나 total_count에 도달할 때까지 반복합니다. 조회하는 동안 이벤트가 변경될 수 있으므로 페이지 간 데이터와 개수가 달라질 수 있습니다. 이 API는 현재 API Key가 속한 워크스페이스를 사용하며, 워크스페이스 간 또는 사이트 간 파라미터를 선언하지 않습니다. 다른 워크스페이스나 사이트의 경우 해당 사이트의 Endpoint와 해당 워크스페이스의 API Key를 사용하여 각각 호출하세요.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| filters[*] | json | 단일 조건 객체입니다. 일반 조건은 name, operation, value를 입력하고, 중첩 그룹은 filters를 입력하며 condition을 별도로 설정할 수 있습니다. 예: {"name": "df_source", "operation": "=", "value": ["monitor"], "condition": "and"}가져오기 또는 입력 방법: 각 항목을 필드 조건 또는 중첩 조건 그룹으로 입력합니다. |
|
| filters[*].name | string | 필드명이며 일반 조건에서 필수입니다. 예: df_source가져오기 또는 입력 방법: 이벤트 상세에서 반환된 원시 필드명을 사용합니다. 예: df_source, df_monitor_checker_name 또는 수집 차원. |
|
| filters[*].operation | string | 일반 조건에서 필수입니다. 사용 가능한 값: =, !=, >, >=, <, <=, in, not in(notin 호환), wildcard, not wildcard, query_string, exists, not_exists, match, not match(notmatch 호환), re, =~, !=~. between은 지원되지 않습니다. 구간에는 >=와 <= 두 조건을 사용합니다.예: =가져오기 또는 입력 방법: 필드와 조회 의도에 따라 다음 연산자 중 하나를 선택합니다. 중첩 filters 그룹에서는 생략합니다. |
|
| filters[*].value | array | 비교 값 배열입니다. in/not in은 모든 값을 사용하고, 그 외 값 연산은 일반적으로 첫 번째 항목을 사용합니다. exists/not_exists에는 []를 전달할 수 있습니다. 예: ["monitor"]가져오기 또는 입력 방법: 해당 필드에 실제로 존재하는 값을 사용하며, 문자열, 숫자, 부울 값은 원래 데이터 타입과 일치해야 합니다. |
|
| filters[*].value[*] | string/number/boolean | 단일 문자열, 숫자 또는 부울 값입니다. 전체 배열을 다시 문자열로 직렬화해서는 안 됩니다. 예: monitor가져오기 또는 입력 방법: 대상 이벤트의 동일한 필드에서 값을 가져오거나 비교할 숫자 임계값을 입력합니다. |
|
| filters[*].condition | string | 논리 연결자이며 생략하면 기본값은 AND입니다. 각 그룹의 첫 번째 조건 연결자는 적용되지 않습니다. 예: and가져오기 또는 입력 방법: 이전 조건과의 관계에 따라 and 또는 or를 선택합니다. |
|
| filters[*].filters | array | 하위 조건 그룹입니다. 이 필드가 존재하면 해당 항목의 name, operation, value는 조건 구성에 사용되지 않습니다. 재귀적으로 중첩할 수 있습니다. 예: [{"name": "df_monitor_checker_name", "operation": "wildcard", "value": ["*checkout*"]}]가져오기 또는 입력 방법: 괄호 조합이 필요하면 filters와 동일한 구조의 하위 배열을 입력합니다. |
|
| filters | array | 이벤트 필터 조건 배열입니다. 여러 조건의 기본값은 AND이며 하위 조건을 재귀적으로 구성할 수 있습니다. null 허용: False 예: [{"name": "df_source", "operation": "=", "value": ["monitor"], "condition": "and"}]가져오기 또는 입력 방법: 먼저 이벤트 상세 또는 이벤트 필드 참조에서 원시 필드명을 확인한 다음 아래 필터 구조에 따라 입력합니다. 생략하거나 []이면 사용자 정의 필터를 추가하지 않습니다. |
|
| lastStatus | string | 최신 이벤트의 이상 상태입니다. 생략하면 위의 모든 미복구 상태와 일치합니다. null 허용: False 선택 가능한 값: ['fatal', 'critical', 'error', 'warning', 'nodata'] 예: critical가져오기 또는 입력 방법: fatal, critical, error, warning, nodata 중 하나를 선택합니다. |
|
| limit | integer | 반환 개수 상한이며 기본값은 20입니다. null 허용: False $maxValue: 100 $minValue: 1 예: 20가져오기 또는 입력 방법: 조회 요구 사항에 따라 1~100 사이의 정수를 선택합니다. |
|
| offset | integer | 결과 오프셋이며 음수가 아닌 정수이고 기본값은 0입니다. null 허용: False $minValue: 0 예: 0가져오기 또는 입력 방법: 첫 페이지에는 0을 입력하고, 이후에는 이번 limit을 더합니다. 필터 조건은 변경하지 않습니다. |
|
| search | string | 제목과 설명을 검색합니다. 생략하면 기본값은 빈 문자열이며 키워드 필터를 추가하지 않습니다. null 허용: False 예: checkout가져오기 또는 입력 방법: 이벤트 제목 또는 설명에 포함된 키워드를 입력합니다. |
|
| timeRange | array | Y | 호환 시간 범위 필드이며 길이는 반드시 2여야 합니다. 현재 API는 이 값으로 조회 범위를 제한하지 않습니다. null 허용: False 최대 길이: 2 최소 길이: 2 예: [1785427200000, 1785430800000]가져오기 또는 입력 방법: 클라이언트 시간 선택기에 따라 시작 및 종료 Unix 밀리초를 생성하여 배열로 전달합니다. 이 버전에서는 필드가 유지되며 여전히 필수입니다. 실제 조회 범위는 설명을 참조하세요. |
| timeRange[*] | integer | Y | 배열 내의 Unix 밀리초 타임스탬프입니다. null 허용: False 예: 1785427200000가져오기 또는 입력 방법: JavaScript Date.getTime()과 같이 밀리초 정수를 사용합니다. |
파라미터 추가 설명¶
이벤트 필드 및 수집 의미는 이벤트 필드 참조를 참조하세요. filters에서는 operation 대신 op, value 대신 values, condition 대신 logic을 호환 사용할 수 있습니다. 표의 전체 이름을 일관되게 사용하는 것이 좋습니다. 중첩 필드는 항목별 구조 검증이 없으므로 operation이 누락되거나 타입이 잘못되면 일반 내부 오류가 발생할 수 있습니다. 전송 전에 예시에 따라 검증하세요.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/events/abnormal/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"timeRange":[1785427200000,1785430800000],"lastStatus":"critical","filters":[{"name":"df_source","operation":"=","value":["monitor"],"condition":"and"}],"offset":0,"limit":20}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | object | 미복구 이벤트 및 페이지네이션 오프셋 정보입니다. |
| content.data | array<object> |
현재 페이지의 미복구 이벤트이며 결과가 없으면 []입니다. |
| content.data[].__docid | string | 이벤트 문서 ID입니다. 이벤트 상세의 경로 doc_id에 입력합니다. df_event_id 및 이벤트 연관 식별자와 다릅니다. |
| content.data[].time | integer | 이벤트 조회에서 반환된 시간(Unix 밀리초)입니다. |
| content.data[].date | integer | 호환 시간 필드입니다. 목록에서는 time과 동일하며 Unix 밀리초입니다. |
| content.data[].df_title | string | 이벤트 제목입니다. |
| content.data[].df_message | string | 이벤트 상세 설명입니다. |
| content.data[].df_status | string | 이벤트 상태입니다. 미복구 목록에서는 fatal, critical, error, warning, nodata이며, 상세에서는 ok, info 또는 기타 소스에서 정의한 복구 상태일 수도 있습니다. |
| content.data[].df_source | string | 이벤트 소스입니다. 예를 들어 monitor는 모니터 이벤트, custom은 이 모듈에서 생성한 사용자 정의 이벤트입니다. |
| content.data[].df_event_id | string | 이벤트 고유 ID입니다. 상세 경로의 doc_id로 사용하지 않습니다. |
| content.data[].df_monitor_checker_event_ref | string | 동일한 트리거 대상의 이벤트 연관 식별자입니다. 그룹화 및 복구에 사용되며 단일 이벤트 ID로 사용할 수 없습니다. |
| content.data[].df_dimension_tags | string 또는 null | 탐지 차원 태그로, 일반적으로 JSON 객체를 직렬화한 문자열입니다. 값이 있으면 파싱하여 service, host 등의 실제 차원을 읽을 수 있습니다. |
| content.data[].df_check_range_start | integer | 탐지 범위 시작 시간(Unix 초)입니다. 목록에서 누락되면 0으로 채웁니다. |
| content.data[].df_check_range_end | integer | 탐지 범위 종료 시간(Unix 초)입니다. 목록에서 누락되면 0으로 채웁니다. |
| content.data[].df_fault_start_time | integer 또는 null | 이번 인시던트 시작 시간(Unix 초)입니다. 소스에서 제공하는 경우에만 반환됩니다. |
| content.data[].df_fault_id | string 또는 null | 이번 인시던트 ID이며 일반적으로 첫 인시던트 이벤트의 df_event_id입니다. |
| content.data[].df_monitor_checker | string 또는 null | 탐지 함수 이름입니다. 예: custom_metric. |
| content.data[].df_monitor_checker_name | string 또는 null | 모니터 이름입니다. |
| content.data[].df_monitor_checker_value | number, string 또는 null | 이벤트 발생 시의 탐지 값입니다. 단위는 모니터의 메트릭 설정에 따라 결정되며 일괄적으로 밀리초로 간주할 수 없습니다. |
| content.data[].df_monitor_type | string 또는 null | 모니터링 유형입니다. 예: custom, slo, bot_obs. 통합 수집 integration_collection은 이 미복구 목록에 포함되지 않습니다. |
| content.data[].df_workspace_uuid | string 또는 null | 이벤트 레코드의 워크스페이스 식별자입니다. |
| content.data[].df_meta | string, object 또는 null | 소스에서 제공한 확장 메타데이터입니다. 문자열은 JSON 직렬화 값일 수 있습니다. 구조는 이벤트 소스에 따라 다릅니다. |
| content.data[].df_bot_obs_detail | string, object 또는 null | 지능형 점검 이벤트의 추가 상세입니다. 해당 소스가 아니면 누락될 수 있습니다. |
| content.data[].df_event_detail | string, object 또는 null | 이벤트 소스에서 제공한 확장 상세이며, 필드는 해당 모니터링 유형에 따라 제공됩니다. |
| content.data[].df_is_silent | boolean, number 또는 null | 소스에 기록된 음소거 플래그입니다. 목록에서는 이 원시 값을 일괄적으로 boolean으로 변환하지 않습니다. |
| content.data[].df_sent_target_types | array, string 또는 null | 소스에 기록된 알림 대상 유형이며 소스 및 이력 레코드 형식에 따라 달라질 수 있습니다. |
| content.data[].df_alert_info | string, object 또는 null | 소스에 기록된 알림 정보이며 구조는 이벤트 유형에 따라 달라집니다. |
| content.data[].isRecover | boolean | 일부 조회 경로에서 반환되는 복구 중 플래그이며 생략될 수 있습니다. 값이 있으면 복구 중으로 표시되었는지 여부를 나타냅니다. true는 최종 복구 성공을 의미하지 않으므로 상태를 계속 조회해야 합니다. |
| content.data[].alert_time_ranges | array<array<integer\|null>> |
이상 시간 구간 목록으로 시작 시간 오름차순이며 각 항목은 [시작 밀리초, 종료 밀리초]입니다. 미복구 구간의 종료 시간은 null일 수 있습니다. |
| content.data[].alert_time_ranges[*] | array | 단일 이상 구간 [start,end]입니다. |
| content.data[].alert_time_ranges[*][0] | integer 또는 null | 구간 시작(Unix 밀리초)입니다. |
| content.data[].alert_time_ranges[*][1] | integer 또는 null | 구간 종료(Unix 밀리초)입니다. 종료되지 않은 경우 null입니다. |
| content.data[].issueLists | array<object> |
연관된 Issue 목록이며 연관된 항목이 없으면 []입니다. |
| content.data[].issueLists[].issueName | string | 연관된 Issue 이름입니다. |
| content.data[].issueLists[].issueUUID | string | 연관된 Issue UUID입니다. |
| content.data[].incidentsList | array<string> |
이벤트와 연관된 인시던트 UUID 목록이며 연관된 항목이 없으면 []입니다. |
| content.data[].incidentsList[] | string | 단일 인시던트 UUID입니다. |
| content.data[].mute_rule | array<string> |
일치하는 음소거 규칙이 있고 차원 태그를 파싱할 수 있을 때 반환되는 음소거 규칙 UUID 배열입니다. 일치하는 항목이 없으면 생략될 수 있습니다. |
| content.data[].mute_rule[] | string | 단일 음소거 규칙 UUID입니다. |
| content.total_count | integer | 조회된 그룹 수입니다. 동적 데이터와 백엔드 조회 제한으로 인해 페이지네이션 일관성이 영향을 받을 수 있습니다. |
| content.limit | integer | 이번 요청의 최대 개수입니다. |
| content.offset | integer | 이번 요청의 오프셋입니다. |
| content.declaration | object 또는 null | 워크스페이스 공통 선언입니다. 각 이벤트에 재귀적으로 삽입되지 않습니다. |
{
"code": 200,
"content": {
"data": [
{
"__docid": "DOC-EXAMPLE",
"time": 1785430800000,
"date": 1785430800000,
"df_title": "checkout-api 响应时间超过阈值",
"df_message": "最近 5 分钟平均响应时间超过 500 ms。",
"df_status": "critical",
"df_source": "monitor",
"df_event_id": "event-example",
"df_monitor_checker_event_ref": "checkout-prod-latency",
"df_dimension_tags": "{\"service\":\"checkout-api\",\"env\":\"production\"}",
"df_check_range_start": 1785430500,
"df_check_range_end": 1785430800,
"df_fault_start_time": 1785430500,
"df_fault_id": "event-fault-example",
"df_monitor_checker": "custom_metric",
"df_monitor_checker_name": "checkout-api 平均响应时间",
"df_monitor_checker_value": 800,
"df_monitor_type": "custom",
"df_workspace_uuid": "wksp_example",
"df_is_silent": false,
"df_sent_target_types": [
"dingtalk"
],
"df_meta": "{}",
"df_bot_obs_detail": null,
"df_event_detail": null,
"df_alert_info": null,
"isRecover": false,
"alert_time_ranges": [
[
1785430500000,
null
]
],
"issueLists": [],
"incidentsList": []
}
],
"total_count": 1,
"limit": 20,
"offset": 0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
결과가 없으면 data=[]를 반환하며 이벤트가 존재하지 않는다는 오류를 발생시키지 않습니다. 현재 공개 파라미터로는 기본 48시간 범위를 변경할 수 없으므로 조회 결과가 너무 많으면 더 구체적인 filters를 사용하세요. 내부 워크스페이스 간 파라미터를 전달할 필요는 없습니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 단일 JSON 객체를 제출하고 배열이나 문자열을 전달하지 않습니다. |
| 406 | ft.InvalidParameter | filters에서 지원되지 않는 연산자를 사용함 | 파라미터 {}가 유효하지 않습니다 |
연산자 목록에 따라 수정합니다. 구간에는 >=와 <=를 사용합니다. |
| 503 | ft.QueryServiceUnavailable | 조회 서비스를 일시적으로 사용할 수 없으며 실제 업스트림이 503을 반환함 | 조회 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도하세요. | content.retryable=true를 확인한 후 백오프하여 재시도합니다. 계속 실패하면 traceId를 제공합니다. |
| 406 | ft.KodoRequestDeadlineExceeded | 이벤트 조회가 백엔드에서 허용된 실행 시간을 초과함 | 데이터 조회 시간이 초과되었습니다. 데이터 양이 너무 많거나 네트워크 지연이 있거나 서버 부하가 높기 때문일 수 있습니다. 다음 방법으로 해결할 수 있습니다: 1. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 조회합니다. 2. 잠시 기다린 후 다시 조회합니다. |
필터에 매칭되는 이벤트 수를 줄인 후 재시도합니다. 상세 조회는 timeRange를 줄일 수 있습니다. |
| 406 | ft.KodoTooManyRows | 조회 데이터 양이 백엔드 제한을 초과함 | 조회한 데이터 양이 최대 개수 제한을 초과했습니다. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 조회하세요. | 명확한 이벤트 조건을 사용하여 매칭되는 데이터를 줄입니다. 단일 페이지 조회량이 집계 비용을 반드시 낮추지는 않습니다. |
| 429 | ft.KodoServerOverloaded | 조회 서비스가 혼잡하거나 과부하됨 | 현재 요청이 너무 많습니다. 잠시 후 다시 시도하세요. | 백오프 후 재시도하고 동시에 발행하는 요청 수를 줄입니다. |
| 500 | ft.InternalServerError | 조회 연결 실패, 업스트림 서비스 이상 또는 기타 내부 오류 | 내부 오류 | 잠시 후 재시도합니다. 계속 실패하면 traceId와 민감 정보를 제거한 요청을 제공합니다. |