동일 조직 트레이스 쿼리¶
POST /api/v1/df/same_org/trace/query
개요¶
traceId로 현재 워크스페이스 또는 동일 조직의 지정된 워크스페이스 트레이싱 데이터를 쿼리합니다.
호출 전 및 사용 단계¶
- APM 트레이스 상세 또는 보고된 데이터의 trace_id 필드에서 전체 트레이스 ID를 복사합니다. 첫 쿼리에서는 현재 워크스페이스와 기본 시간 범위를 사용할 수 있습니다.
- 사이트에서 동일 조직 쿼리를 지원하는 경우 동일 조직 워크스페이스 목록의 content.data[].workspaceUUID에서 대상 UUID를 선택합니다. workspaceUUIDs를 생략하거나 빈 배열을 전달하면 현재 워크스페이스만 쿼리합니다.
- 반복 쿼리 시 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을 확인하고, 일시적 오류라면 지연 후 다시 시도할 수 있습니다. |