콘텐츠로 이동

동일 조직 트레이스 쿼리



POST /api/v1/df/same_org/trace/query

개요

traceId로 현재 워크스페이스 또는 동일 조직의 지정된 워크스페이스 트레이싱 데이터를 쿼리합니다.

호출 전 및 사용 단계

  1. APM 트레이스 상세 또는 보고된 데이터의 trace_id 필드에서 전체 트레이스 ID를 복사합니다. 첫 쿼리에서는 현재 워크스페이스와 기본 시간 범위를 사용할 수 있습니다.
  2. 사이트에서 동일 조직 쿼리를 지원하는 경우 동일 조직 워크스페이스 목록의 content.data[].workspaceUUID에서 대상 UUID를 선택합니다. workspaceUUIDs를 생략하거나 빈 배열을 전달하면 현재 워크스페이스만 쿼리합니다.
  3. 반복 쿼리 시 traceId, 시간 범위 및 필터 조건을 일관되게 유지하고 커서만 업데이트합니다. cursorTime / cursorToken을 우선 사용하며, next_cursor_time이 0보다 작으면 종료합니다.

쿼리 시간 범위는 기본적으로 24시간을 초과하지 않습니다. 중복 제거 후 워크스페이스 간 UUID 수는 기본적으로 최대 20개입니다. 두 상한은 사이트 구성에 따라 조정될 수 있습니다. 최신 커서 또는 레거시 페이지네이션 파라미터 중 하나를 사용합니다. 아래 파라미터 표의 두 가지 커서 예시는 각각 다른 요청에 사용됩니다.

요청 헤더

파라미터 이름 유형 필수 설명
DF-API-KEY string Y AK 식별자, AK uuid
예시: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 본 API 권한이 있는 Key를 생성하거나 획득합니다.

Body 요청 파라미터

파라미터 이름 유형 필수 설명
traceId string Y 트레이스 ID, 최대 길이 512
null 허용: False
예시: 032d15aa2ac166254744efd440987bdd
획득 또는 입력 방법: APM 트레이스 상세 또는 trace_id 필드에서 가져옵니다.
workspaceUUIDs array 선택 사항, 동일 조직 워크스페이스 UUID 목록 지정, 단일 UUID 최대 길이 128; 전달하지 않거나 빈 배열이면 현재 워크스페이스 기준으로 쿼리
null 허용: True
예시: ["wksp_example"]
획득 또는 입력 방법: 동일 조직 워크스페이스 목록에서 워크스페이스 UUID를 필터링하여 복사합니다. 워크스페이스 간 기능은 사이트에서 활성화해야 합니다.
startTime integer 선택 사항, 쿼리 시작 시간, 13자리 밀리초 타임스탬프
null 허용: True
예시: 1772516100000
획득 또는 입력 방법: 쿼리 시작 시간을 Unix 밀리초로 변환합니다. 생략하면 기본값은 서버 현재 시간 1시간 전입니다. 이 시간 예시는 실제 트레이스가 발생한 시간으로 대체해야 합니다.
endTime integer 선택 사항, 쿼리 종료 시간, 13자리 밀리초 타임스탬프; 전달하지 않으면 종료 시간이 자동으로 보완되지 않습니다
null 허용: True
예시: 1772519700000
획득 또는 입력 방법: 쿼리 종료 시간을 Unix 밀리초로 변환합니다. 시작 시간보다 늦어야 하며 서버 현재 시간보다 늦지 않아야 합니다. 생략 시 서버 현재 시간을 종료 상한으로 검증합니다.
source string 선택 사항, tracing source; 전달하지 않으면 모든 source를 쿼리합니다; 구체적인 source 이름 또는 *만 지원하며 최대 길이 128
null 허용: True
예시: web
획득 또는 입력 방법: APM 데이터에 이미 존재하는 tracing source 이름을 사용합니다. 서비스 이름을 source로 직접 사용해서는 안 됩니다. 생략하거나 *를 전달하면 모든 source를 쿼리할 수 있습니다.
whereClause string 선택 사항, 추가 DQL where 조건 조각, 최대 길이 4096, 외부 중괄호를 포함하지 않으며 서버에서 parser 검증을 수행합니다
null 허용: True
예시: service = 'checkout'
획득 또는 입력 방법: DQL 필터 조건 조각을 입력하고 APM에 알려진 필드를 사용하며 외부 중괄호를 생략합니다.
limit integer 선택 사항, 반환 수 제한; 전달하지 않으면 DQL 기본 페이지네이션 크기를 따르며, 명시적으로 전달할 때 기본 최대 1000이고 사이트 구성에 의해 제어됩니다
null 허용: True
예시: 50
획득 또는 입력 방법: 클라이언트에서 표시할 건수에 따라 양의 정수를 입력합니다. 명시적 상한은 사이트 구성에 의해 제어됩니다.
searchAfter array 선택 사항, 레거시 페이지네이션 호환 필드; Doris 쿼리에서는 이 필드를 사용하지 않으며 __docid를 기준으로 직접 구성하지 마십시오
null 허용: True
예시: [1772519400000, "cursor-example"]
획득 또는 입력 방법: 레거시 페이지네이션 호환 방식입니다. 쿼리 결과가 레거시 커서를 반환한 경우에만 전달합니다. 첫 번째 항목은 13자리 Unix 밀리초이고 두 번째 항목은 비어 있지 않은 문자열입니다. Doris에서는 cursorTime / cursorToken을 사용합니다.
cursorTime integer 선택 사항, 스크롤 페이지네이션 커서; 첫 쿼리에서는 13자리 밀리초 타임스탬프를 사용할 수 있으며, 이후에는 응답의 16자리 마이크로초 next_cursor_time을 그대로 전달해야 합니다
null 허용: True
예시: 1772519400000123
획득 또는 입력 방법: 첫 쿼리에서는 생략할 수 있습니다. 이어서 쿼리해야 할 때는 이전 응답의 next_cursor_time을 복사합니다.
cursorToken string 선택 사항, 응답의 next_cursor_token을 그대로 전달합니다; 응답이 비어 있으면 생략하거나 빈 문자열을 전달할 수 있으며 최대 길이 512
null 허용: True
예시: cursor-example
획득 또는 입력 방법: 이전 응답의 next_cursor_token을 복사합니다. 빈 값은 생략할 수 있습니다.

파라미터 추가 설명

본 API는 트레이스 쿼리에만 사용되며 일반 DQL q를 지원하지 않습니다.

파라미터 이름 type 필수 설명
traceId string Y 트레이스 ID
workspaceUUIDs array 동일 조직 워크스페이스 UUID 목록; 단일 UUID 최대 길이 128; 전달하지 않거나 빈 배열이면 현재 워크스페이스를 쿼리합니다
startTime integer 쿼리 시작 시간; 전달하지 않으면 기본값은 최근 1시간의 시작 시간입니다
endTime integer 쿼리 종료 시간; 전달하지 않으면 내부 time_range에 시작 시간만 포함됩니다
source string tracing source; 전달하지 않으면 모든 source를 쿼리합니다; 구체적인 source 이름 또는 *만 지원하며 최대 길이 128
whereClause string 추가 DQL where 조건 조각, 최대 길이 4096, 외부 중괄호를 포함하지 않으며 서버에서 parser 검증을 수행합니다
limit integer 반환 수 제한; 전달하지 않으면 DQL 기본 페이지네이션 크기를 따르며, 명시적으로 전달할 때 기본 최대 1000이고 사이트 구성에 의해 제어됩니다
searchAfter array 레거시 페이지네이션 호환 필드; Doris 쿼리에서는 이 필드를 사용하지 않으며 __docid를 기준으로 직접 구성하지 마십시오
cursorTime integer 스크롤 페이지네이션 커서; 첫 쿼리에서는 13자리 밀리초 타임스탬프를 사용할 수 있으며, 이후에는 응답의 16자리 마이크로초 next_cursor_time을 그대로 전달해야 합니다
cursorToken string 응답의 next_cursor_token을 그대로 전달합니다; 응답이 비어 있으면 생략하거나 빈 문자열을 전달할 수 있으며 최대 길이 512

OpenAPI 파라미터는 lowerCamelCase를 유지합니다. selectClause와 offset은 지원하지 않습니다. 페이지네이션에는 cursorTime / cursorToken을 사용해야 하며, next_cursor_time이 0보다 작으면 종료합니다.

요청 예시

curl 'https://openapi.guance.com/api/v1/df/same_org/trace/query' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"traceId":"032d15aa2ac166254744efd440987bdd","limit":50}'

응답

HTTP 200, application/json.

필드 유형 설명
content.data array 쿼리 결과 목록이며, 본 API는 하나의 트레이스 쿼리를 제출합니다.
content.data[*].series array 실제 데이터 시리즈이며, columns에는 필드 이름이 있고 values에는 동일한 순서의 레코드가 있습니다.
content.data[*].next_cursor_time integer 다음 페이지 시간 커서; 반환 시 그대로 사용하며, 음수 값은 더 이상 데이터가 없음을 나타냅니다.
content.data[*].next_cursor_token string 다음 페이지와 함께 사용하는 Token; 비어 있거나 반환되지 않을 수 있습니다.
{
    "code": 200,
    "content": {
        "data": [
            {
                "series": [
                    {
                        "columns": [
                            "trace_id",
                            "service"
                        ],
                        "values": [
                            [
                                "TRACE-XXXX",
                                "api"
                            ]
                        ]
                    }
                ],
                "next_cursor_time": 1772519400000123,
                "next_cursor_token": ""
            }
        ]
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 필드 유형, 필수 여부 또는 제약 조건이 파라미터 표와 일치하지 않음 요청 필드 검증에 실패했으며 메시지에 필드 또는 규칙이 표시됩니다. 필드, 유형 및 제약 조건을 확인하십시오.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류. content의 reason, line, column을 확인한 후 수정하십시오.
406 ft.ParameterCheckFailed 시간 또는 커서 형식, 선후 관계 또는 범위가 유효하지 않음 시간 오류에는 content.field, reason, serverTime 및 receivedTime이 포함될 수 있습니다. 시간 정밀도, 순서를 검증하거나 이전 페이지의 cursor를 그대로 복사하십시오.
406 ft.ParameterCheckFailed 동일 조직 쿼리가 활성화되지 않았거나, 지정된 워크스페이스가 일치하지 않거나, source / 필터 조건이 허용되지 않음 일반 파라미터 검사 실패 정보를 반환합니다. 먼저 현재 워크스페이스에서 쿼리한 다음 대상 워크스페이스, source 및 whereClause를 항목별로 확인하십시오.
403 ft.ForbiddenQuery 대상 워크스페이스 또는 APM 데이터를 쿼리할 권한이 없음 쿼리 권한이 부족합니다. API Key가 속한 워크스페이스와 APM 쿼리 권한을 확인하십시오.
503 ft.QueryServiceUnavailable 종속 쿼리 서비스를 일시적으로 사용할 수 없음 쿼리 서비스를 일시적으로 사용할 수 없으므로 나중에 다시 시도하십시오. content.retryable을 확인하고, 일시적 오류라면 지연 후 다시 시도할 수 있습니다.

문서 평가

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