목록¶
POST /api/v1/error_track/list
개요¶
시간 창을 기준으로 오류 집계 및 처리 상태를 조회합니다.
호출 전 및 사용 단계¶
현재 Key에는 errorCenter.errorTrackQuery 권한이 필요하며, Key가 속한 워크스페이스만 조회합니다. 먼저 밀리초 단위 시간 창을 지정한 다음 conditions로 텔레메트리 필드를 필터링합니다. 응답의 issue_id는 상세, 상태 및 댓글 경로에 사용되는 비즈니스 식별자이므로 refData.uuid로 바꾸지 마세요.
먼저 최대 10,000개의 EH 오류 후보를 가져온 다음 로컬에서 담당자/상태 기준으로 필터링 및 페이지네이션합니다. totalCount는 해당 상한을 초과하는 전체 오류 총수가 아닙니다. 시간 창/조건을 좁힌 후 페이지네이션하세요. 최신 대표 레코드와 횟수는 동일한 시간 창에서 조회되며, 여러 번 조회하는 동안 새 데이터로 인해 페이지네이션 드리프트가 발생할 수 있습니다. issueStatusCountInfo는 담당자 필터링 후, 상태 필터링 전에 집계되며 실제 개수가 있는 상태 키만 표시됩니다. 로컬 메타데이터가 초기화되지 않은 오류는 Triage로 집계되지만 refData는 여전히 {}입니다.
각 항목은 현재 시간 창 내 최신 텔레메트리 레코드 하나의 동적 필드에 refData, app_info 및 service_info를 추가한 것입니다. 모든 원시 오류 이벤트가 아닙니다. 목록은 모든 항목에 대해 로컬 메타데이터를 생성하지 않습니다. content는 객체로 유지되며, data 배열은 content.data에 있고 pageInfo는 응답 최상위에 있습니다. 공통 선언은 content.declaration에만 있으며 data 항목의 필드가 아닙니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>조회 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| assigner | string | 선택적 단일 담당자 ID이며, 로컬 assigner 포함 관계로 필터링합니다. 쉼표/배열은 지원하지 않습니다. 생략하거나 빈 문자열이면 필터링하지 않으며, 메타데이터가 없는 항목은 담당자 필터링 시 제외됩니다. null 허용: False 예시: group_example조회 또는 입력 방법: 워크스페이스 멤버에서 acnt_를 가져오거나, 팀 목록에서 현재 공간의 group_을 가져옵니다. |
|
| conditions | string | 선택적 DQL 조건 문자열이며, 생략하거나 공백이면 추가로 필터링하지 않습니다. 완전한 DQL/SQL이 아니고 JSON 조건 객체도 아닙니다. 후보, 개수 및 최신 레코드 조회에 사용됩니다. 실제 필드를 사용하고 문자열을 올바르게 이스케이프해야 하며, 신뢰할 수 없는 입력을 직접 연결하지 마세요. 빈 문자열 허용: True null 허용: False 예시: service = 'payment-api'조회 또는 입력 방법: 실제 EH 필드에 따라 DQL 필터 표현식을 구성하며, 먼저 쿼리 도구에서 검증할 수 있습니다. |
|
| endTime | integer | Y | 필수 정수이며 시간 창의 종료점입니다. Unix 초/나노초를 전달하지 마세요. null 허용: False 예시: 1785427200000조회 또는 입력 방법: 호출자가 대상 시간 창을 Unix 밀리초로 변환합니다. |
| issueStatus | commaArray | 선택적 쉼표 구분 문자열이며, Triage/Assigned/Working/Resolved/Ignored 조합을 권장합니다. 생략하거나 빈 문자열이면 필터링하지 않습니다. JSON 배열이 아니며, 각 항목은 trim하지 않고 대소문자를 구분합니다. 알 수 없는 값은 일반적으로 열거형 오류가 아니라 일치 항목 없음으로 처리됩니다. null 허용: False 예시: Triage,Working조회 또는 입력 방법: 오류 센터 상태에 따라 선택하며, 상세의 issueStatus에서 가져옵니다. |
|
| pageIndex | integer | 선택적 정수이며, 생략 시 1입니다. 현재 이 ErrorTrack 진입점들은 양수/최대 제한을 선언하지 않았으므로 클라이언트는 양의 정수만 사용해야 합니다. null 허용: False 예시: 1조회 또는 입력 방법: 호출자가 페이지네이션을 제어하며 1부터 시작합니다. |
|
| pageSize | integer | 선택적 정수이며, 생략 시 10입니다. 선언에 상한이 없으므로 작은 페이지로 읽는 것을 권장하며, 0/음수를 전달하여 구현 동작에 의존해서는 안 됩니다. null 허용: False 예시: 10조회 또는 입력 방법: 호출자가 표시/배치 처리 규모에 따라 선택합니다. |
|
| startTime | integer | Y | 필수 정수이며 시간 창의 시작점입니다. endTime보다 작은지 확인하세요. 선언은 시간 창 길이/시간 순서를 제한하지 않으며, 넓은 창은 후보를 잘라내거나 비용을 증가시킬 수 있습니다. null 허용: False 예시: 1785423600000조회 또는 입력 방법: 호출자가 대상 시간 창을 Unix 밀리초로 변환합니다. |
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/error_track/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"startTime":1785423600000,"endTime":1785427200000,"conditions":"service = '"'"'payment-api'"'"'","pageIndex":1,"pageSize":10}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | data, issueStatusCountInfo 및 공통 선언을 포함합니다. |
| content.data | array<object> |
이 페이지의 오류 집계이며, 일치 항목이 없으면 []입니다. |
| content.data[].time | integer | 현재 집계 대표 레코드의 Unix 밀리초 시간입니다. |
| content.data[].issue_id | string | 오류 집계 ID이며, 이후 상세/상태/댓글 경로에서 이 값을 사용합니다. |
| content.data[].count | number | 요청 시간 창 내 집계 발생 횟수입니다. 통계가 누락된 경우 호환을 위해 1로 반환되며, 전체 이력 누적값이 아닙니다. |
| content.data[].__docid | string | 데이터 엔진 레코드 ID이며, 대표 레코드에 따라 변경될 수 있고 관리 경로에 사용되지 않습니다. |
| content.data[].__source | string | 텔레메트리 소스 메타 정보이며, 생략될 수 있습니다. |
| content.data[].source | string | 일반적으로 logging/tracing/rum이며, 실제 수집 레코드에 의해 결정됩니다. |
| content.data[].app_id | string | RUM 공개 appId이며, RumCfg 내부 UUID가 아닙니다. RUM이 아니면 없을 수 있습니다. |
| content.data[].app_name | string | 수집된 애플리케이션 이름이며, 현재 구성과 다를 수 있습니다. |
| content.data[].service | string | 서비스 이름이며, 서비스 구성 UUID가 아닙니다. |
| content.data[].env | string | 수집 환경입니다. |
| content.data[].version | string | 수집 버전입니다. |
| content.data[].error_type | string | 수집된 오류 유형입니다. |
| content.data[].error_message | string | 오류 메시지이며, 여러 줄을 포함할 수 있습니다. |
| content.data[].error_stack | string | 오류 스택이며, SourceMap으로 복원되었음을 보장하지 않습니다. |
| content.data[].fingerprint | string | 수집된 오류 지문입니다. |
| content.data[].resource | string | 오류 리소스 이름입니다. |
| content.data[].log_index | string | 소스 인덱스 이름입니다. |
| content.data[].session_id | string | RUM 세션 ID입니다. |
| content.data[].view_id | string | RUM 페이지 ID입니다. |
| content.data[].trace_id | string | 분산 추적 trace ID이며, 인터페이스 traceId와 다릅니다. |
| content.data[].span_id | string | 분산 추적 span ID입니다. |
| content.data[].create_time | integer | 수집 최초 생성 시간이며, Unix 밀리초입니다. |
| content.data[].create_at | JSON 또는 null | 소스 보존 필드이며, 유형 및 존재 여부는 텔레메트리 소스에 따라 달라지고 고정된 시간 단위를 가정하지 않습니다. |
| content.data[].date | integer | 소스 시간 필드이며, 일반적으로 Unix 밀리초입니다. 수집 필드 정의를 기준으로 합니다. |
| content.data[].date_ns | integer | 소스 Unix 나노초 시간입니다. |
| content.data[].time_us | integer | 소스 Unix 마이크로초 시간입니다. |
| content.data[].* | number | 일부 집계 호환 필드이며, 없을 수 있고 안정적인 비즈니스 식별자로 사용되지 않습니다. |
| content.data[].기타 수집 필드 | JSON | 조회 시간 창의 최신 대표 레코드에 있는 기타 컬럼을 그대로 펼칩니다. 필드는 누락/null일 수 있고 유형은 수집 소스에 따라 달라지므로 클라이언트는 이러한 변동을 허용해야 합니다. |
| content.data[].refData | object | 로컬 상태 메타데이터입니다. 초기화되지 않은 경우 {}이며, 오류가 존재하지 않는 것으로 간주할 수 없습니다. |
| content.data[].app_info | object | 현재 활성 RUM 애플리케이션의 jsonContent이며, 일치하지 않으면 {}이고 Client Token을 포함하지 않습니다. |
| content.data[].app_info.name | string | 현재 애플리케이션 표시 이름입니다. |
| content.data[].app_info.type | string | 현재 애플리케이션 플랫폼 유형입니다. |
| content.data[].app_info.extend | object | 선택적 애플리케이션 동적 표시 확장입니다. |
| content.data[].app_info.extend.사용자 정의 키 | JSON | 애플리케이션 구성에 저장된 확장 값입니다. |
| content.data[].service_info | object | 현재 활성 서비스 관리 요약이며, 일치하지 않으면 {}입니다. |
| content.data[].service_info.service | string | 서비스 이름입니다. |
| content.data[].service_info.type | string | 서비스 분류입니다. |
| content.data[].service_info.colour | string | 서비스 표시 색상입니다. |
| content.data[].service_info.language | string 또는 null | 서비스 언어이며, 구성이 비어 있으면 null일 수 있습니다. |
| content.data[].refData.id | integer 또는 null | 데이터베이스 행 ID이며, 경로 위치 지정에 사용되지 않습니다. 제출 전 스냅샷에서는 null일 수 있습니다. |
| content.data[].refData.uuid | string | 로컬 리소스 UUID입니다. 상세 메타데이터는 isset_, 작업 기록은 issetoper_, 댓글은 issetcomment_입니다. |
| content.data[].refData.status | integer | 리소스 상태이며, 일반적으로 0이고 소프트 삭제된 3은 조회에서 제외됩니다. |
| content.data[].refData.creator | string | 생성 주체입니다. 자동 초기화된 메타데이터는 sys이고, Key로 기록된 주체는 wsak_입니다. |
| content.data[].refData.updator | string | 최근 업데이트 주체이며, 업데이트되지 않은 경우 비어 있을 수 있습니다. |
| content.data[].refData.createAt | integer | Unix 초 생성 시간입니다. |
| content.data[].refData.updateAt | integer | Unix 초 업데이트 시간이며, 업데이트되지 않은 경우 -1일 수 있습니다. 동일 값의 상태/담당자 업데이트는 반드시 갱신되지 않을 수 있습니다. |
| content.data[].refData.deleteAt | integer | Unix 초 삭제 시간이며, 삭제되지 않은 경우 일반적으로 -1입니다. |
| content.data[].refData.workspaceUUID | string | 현재 Key가 속한 워크스페이스입니다. |
| content.data[].refData.issueID | string | 텔레메트리 issue_id의 비즈니스 식별자이며, 로컬 uuid와 다릅니다. |
| content.data[].refData.assigner | array<string> |
담당자 계정 acnt_ 또는 팀 group_입니다. 현재 저장 순서이며, 빈 배열은 미할당입니다. |
| content.data[].refData.assigner[] | string | 단일 담당자 식별자입니다. 저장 성공만으로 계정이 존재하거나 알림 가능하다고 판단할 수 없습니다. |
| content.data[].refData.issueStatus | string | Triage/Assigned/Working/Resolved/Ignored입니다. |
| content.data[].refData.extend | object 또는 null | 로컬 메타데이터 확장입니다. 과거의 비정상 값은 오류를 허용해야 합니다. |
| content.data[].refData.extend.errorType | string | 초기화 시 조회된 오류 유형입니다. 조회 실패/데이터 없음이면 비어 있을 수 있습니다. |
| content.data[].refData.extend.firstTime | integer | 초기화 시 최근 30일의 create_time(Unix 밀리초)을 조회합니다. 조회 실패/데이터 없음이면 현재 밀리초로 대체되며, 전체 이력의 최초 시각을 보장하지 않습니다. |
| content.data[].refData.extend.statusChangeRecords | array<object> |
상태 변경 기록이며, 각 항목은 저장 이력 순서입니다. |
| content.data[].refData.extend.statusChangeRecords[].status | string | 위 상태 중 하나입니다. |
| content.data[].refData.extend.statusChangeRecords[].time | integer | 상태 진입 시간이며, Unix 초입니다. |
| content.data[].refData.extend.statusChangeRecords[].operator | string | 작업 주체 UUID/시스템 식별자입니다. |
| content.data[].refData.extend.기타 키 | JSON | 과거에 저장된 기타 확장 키이며, 고정된 실행 파라미터가 아닙니다. |
| content.data[].refData.duration | integer | 초 단위입니다. 이전 전체 주기의 시간 차이 합에 현재 시간에서 마지막 Triage 주기 시작점을 뺀 값을 더합니다. Resolved/Ignored 이후에도 계속 증가할 수 있으며, 엄격한 MTTR이 아닙니다. 계산이 비정상이면 누락될 수 있습니다. |
| content.data[].refData.statusDuration | object | 최근 Triage 주기의 상태 진입 시간 매핑이며, 각 상태의 지속 초가 아닙니다. 계산이 비정상이면 생략될 수 있습니다. |
| content.data[].refData.statusDuration.상태 | integer | Triage/Assigned/Working/Resolved/Ignored 중 실제로 나타나고 증가 선택을 충족하는 Unix 초 시간입니다. |
| content.data[].refData.creatorInfo | object | 생성 주체 요약이며, 일치하지 않으면 {}입니다. 시스템 주체 필드는 계정보다 적을 수 있습니다. |
| content.data[].refData.updatorInfo | object | 업데이트 주체 요약이며, 일치하지 않으면 {}입니다. |
| content.data[].refData.assignerInfo | array<object> |
해석 가능한 담당자 요약입니다. 유효하지 않은 계정은 나타나지 않을 수 있으며, assigner와 길이가 같음을 보장하지 않습니다. |
| content.data[].refData.assignerInfo[].uuid | string | 계정 또는 팀 UUID입니다. |
| content.data[].refData.assignerInfo[].name | string | 표시 이름입니다. 팀 요약은 uuid/name만 포함합니다. |
| content.data[].refData.creatorInfo.uuid | string | 주체 UUID이며, 계정, Key 또는 시스템 식별자일 수 있습니다. |
| content.data[].refData.creatorInfo.status | integer | 주체 상태입니다. |
| content.data[].refData.creatorInfo.wsAccountStatus | integer | 현재 공간 멤버 관계 상태 요약입니다. |
| content.data[].refData.creatorInfo.username | string | 로그인 이름 또는 Key 이름입니다. |
| content.data[].refData.creatorInfo.name | string | 표시 이름입니다. |
| content.data[].refData.creatorInfo.iconUrl | string | 아바타 URL이며, 비어 있을 수 있습니다. |
| content.data[].refData.creatorInfo.email | string | 이메일입니다. Key 주체는 자체 UUID일 수 있으며, 발송 가능함을 보장하지 않습니다. |
| content.data[].refData.creatorInfo.mobile | string | 휴대폰 번호이며, 비어 있을 수 있습니다. |
| content.data[].refData.creatorInfo.countryCode | string | 전화 국가 코드이며, 비어 있을 수 있습니다. |
| content.data[].refData.creatorInfo.acntWsNickname | string | 현재 공간 닉네임이며, 비어 있을 수 있습니다. |
| content.data[].refData.updatorInfo.uuid | string | 주체 UUID이며, 계정, Key 또는 시스템 식별자일 수 있습니다. |
| content.data[].refData.updatorInfo.status | integer | 주체 상태입니다. |
| content.data[].refData.updatorInfo.wsAccountStatus | integer | 현재 공간 멤버 관계 상태 요약입니다. |
| content.data[].refData.updatorInfo.username | string | 로그인 이름 또는 Key 이름입니다. |
| content.data[].refData.updatorInfo.name | string | 표시 이름입니다. |
| content.data[].refData.updatorInfo.iconUrl | string | 아바타 URL이며, 비어 있을 수 있습니다. |
| content.data[].refData.updatorInfo.email | string | 이메일입니다. Key 주체는 자체 UUID일 수 있으며, 발송 가능함을 보장하지 않습니다. |
| content.data[].refData.updatorInfo.mobile | string | 휴대폰 번호이며, 비어 있을 수 있습니다. |
| content.data[].refData.updatorInfo.countryCode | string | 전화 국가 코드이며, 비어 있을 수 있습니다. |
| content.data[].refData.updatorInfo.acntWsNickname | string | 현재 공간 닉네임이며, 비어 있을 수 있습니다. |
| content.data[].refData.assignerInfo[].status | integer | 주체 상태입니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].wsAccountStatus | integer | 현재 공간 멤버 관계 상태 요약입니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].username | string | 로그인 이름 또는 Key 이름입니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].iconUrl | string | 아바타 URL이며, 비어 있을 수 있습니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].email | string | 이메일입니다. Key 주체는 자체 UUID일 수 있으며, 발송 가능함을 보장하지 않습니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].mobile | string | 휴대폰 번호이며, 비어 있을 수 있습니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].countryCode | string | 전화 국가 코드이며, 비어 있을 수 있습니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.data[].refData.assignerInfo[].acntWsNickname | string | 현재 공간 닉네임이며, 비어 있을 수 있습니다. 계정 요약에만 있으며, 팀에는 이 키가 없습니다. |
| content.issueStatusCountInfo | object | 후보 오류의 담당자 필터링 후 상태 개수 매핑이며, issueStatus 필터링으로 축소되지 않습니다. |
| content.issueStatusCountInfo.상태 | integer | Triage/Assigned/Working/Resolved/Ignored 중 데이터가 있는 상태의 개수입니다. 키가 없다고 응답이 손상된 것은 아닙니다. |
| pageInfo | object | 페이지네이션 메타 정보이며, OpenAPI에서는 최상위에 있습니다. content는 객체로 유지됩니다. |
| pageInfo.count | integer | 이 페이지의 실제 항목 수입니다. |
| pageInfo.totalCount | integer | 필터를 충족하는 후보/로컬 레코드 총수입니다. 텔레메트리 목록은 10,000 후보 상한의 영향을 받습니다. |
| pageInfo.pageIndex | integer | 페이지 번호이며, 1부터 시작합니다. |
| pageInfo.pageSize | integer | 이번 요청의 페이지당 요청 수입니다. |
| content.declaration | object 또는 null | 현재 워크스페이스의 공통 선언입니다. content 부모 객체에만 추가되며, data 항목에 재귀적으로 추가되지 않습니다. |
{
"code": 200,
"content": {
"data": [
{
"time": 1785427200000,
"issue_id": "err_payment_timeout",
"count": 8,
"__docid": "doc_example",
"source": "rum",
"app_id": "payment_web",
"service": "payment-api",
"env": "production",
"version": "1.0.0",
"error_type": "js_error",
"error_message": "Request timed out",
"error_stack": "at pay @ https://cdn.example.com/app.js:1:1",
"refData": {},
"app_info": {
"name": "支付Web",
"type": "web"
},
"service_info": {
"service": "payment-api",
"type": "web",
"colour": "#3F94DC",
"language": "python"
}
}
],
"issueStatusCountInfo": {
"Triage": 1
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"count": 1,
"totalCount": 1,
"pageIndex": 1,
"pageSize": 10
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
EH 조회의 다운스트림 비즈니스 4xx는 실제 HTTP/errorCode/message에 따라 반환될 수 있습니다. traceId를 보존하고 조회 오류에 따라 시간 범위를 좁히거나 conditions를 수정하세요. 식별되지 않았거나 패스스루되지 않은 5xx는 일반적으로 500으로 통일됩니다. DQL 조회 체인에서만 복구 가능한 503은 ft.QueryServiceUnavailable(content.retryable=true)로 정규화됩니다. 상태가 Resolved된 이후의 일반 동기 호출은 동일한 정규화를 보장하지 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않습니다. | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하세요. |
| 400 | ft.JsonFormatError | 요청 JSON의 최상위가 객체가 아닙니다. | 일부 json 파일 형식 오류 | 파라미터 객체를 제출하세요. |
| 503 | ft.QueryServiceUnavailable | EH DQL 조회 체인 업스트림이 일시적으로 사용할 수 없어 503 정규화가 트리거되었습니다. | 조회 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도하세요. | content.retryable을 확인하고 백오프하세요. 시간 창을 좁히고 traceId를 보존하세요. |
| 500 | ft.InternalServerError | 데이터베이스 읽기, 과거 JSON 구조 또는 연관 요약 구성에서 처리되지 않은 예외가 발생했습니다. | 내부 오류 | traceId를 보존하고 백오프하세요. 지속적으로 실패하면 관리자에게 관련 이력 레코드와 구성을 확인하도록 요청하세요. |