콘텐츠로 이동

목록



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를 보존하고 백오프하세요. 지속적으로 실패하면 관리자에게 관련 이력 레코드와 구성을 확인하도록 요청하세요.

문서 평가

이 페이지가 도움이 되었나요?