동일 조직 워크스페이스 간 Trace 조회 사용 가이드¶

이 문서는 배포 플랜 Studio에서 동일 조직 워크스페이스 간 Trace 조회 기능의 구성 스위치, 인터페이스 사용 방법, 자주 묻는 질문을 설명합니다.

이 기능은 동일 조직 내에서 지정된 trace_id를 기준으로 여러 워크스페이스의 트레이스 데이터를 조회하는 데 사용됩니다. Trace 조회 시나리오에만 적용되며 일반 DQL 조회 인터페이스의 워크스페이스 간 의미 체계는 변경하지 않습니다.

사용 전제 조건¶

• Studio 백엔드 버전에 SameOrgTraceQuerySet 구성과 동일 조직 Trace 조회 전용 인터페이스가 포함되어 있어야 합니다.
• 대상 워크스페이스는 현재 워크스페이스와 동일한 조직에 속해야 합니다.
• 현재 워크스페이스가 아닌 다른 워크스페이스를 조회하려면 SameOrgTraceQuerySet.enable을 활성화해야 합니다.
• Kodo 측 파라미터는 별도로 조정할 필요가 없습니다. Studio 백엔드가 내부 요청에 대상 워크스페이스 목록을 포함합니다.

구성 스위치¶

SameOrgTraceQuerySet은 Studio 백엔드 서비스 구성에 있으며 기본적으로 비활성화되어 있습니다.

SameOrgTraceQuerySet:
  enable: false
  maxWorkspaceCount: 20
  maxLimit: 1000
  maxTimeRangeHours: 24
  workspaceListPageSizeMax: 100

구성 항목 설명:

구성을 활성화한 후에는 Studio 백엔드 관련 서비스를 재시작해야 합니다.

스위치 동작¶

스위치 비활성화¶

SameOrgTraceQuerySet.enable=false인 경우:

• 동일 조직 워크스페이스 간소화 정보 목록 조회 인터페이스는 계속 정상적으로 사용할 수 있습니다.
• Trace 조회 인터페이스는 현재 워크스페이스만 조회할 수 있습니다.
• 요청의 대상 워크스페이스 UUID 목록에 현재 워크스페이스가 아닌 워크스페이스가 포함된 경우 OpenAPI는 code=406, errorCode=ft.ParameterCheckFailed를 반환합니다. 이 오류 코드는 다른 파라미터 검증 실패에도 사용되므로 오류 코드만으로 스위치 상태를 판단할 수 없습니다.

현재 워크스페이스 UUID만 전달하거나 워크스페이스 UUID 목록을 전달하지 않으면 현재 워크스페이스의 트레이스 데이터를 조회하는 것과 동일합니다.

스위치 활성화¶

SameOrgTraceQuerySet.enable=true인 경우 Trace 조회 인터페이스는 동일 조직 내 여러 워크스페이스 UUID를 전달할 수 있습니다. 서버는 워크스페이스 수, 시간 범위, 조회 파라미터를 검증하고 내부 조회 시 대상 워크스페이스 목록을 포함합니다.

관련 인터페이스¶

동일 조직 워크스페이스 간소화 정보 목록 조회¶

이 인터페이스는 SameOrgTraceQuerySet.enable의 영향을 받지 않으며 Trace 조회 대상 워크스페이스를 선택하는 데 사용할 수 있습니다.

OpenAPI:

POST /api/v1/workspace/same_org/list

AIAPI:

POST /api/v1/account/workspace/same_org/list

일반적인 요청 파라미터:

목록은 워크스페이스 ID 내림차순으로 반환되며 pageIndex / page_index는 사용하지 않습니다. 페이지네이션 필드 대응 관계는 다음과 같습니다.

예를 들어 OpenAPI 첫 번째 요청 본문은 다음과 같습니다.

{"pageSize": 20}

응답에서 hasMore=true이고 nextBeforeWorkspaceId=12345이면 다음 요청은 다음과 같습니다.

{"pageSize": 20, "beforeWorkspaceId": 12345}

AIAPI의 대응 요청은 다음과 같습니다.

{"page_size": 20, "before_workspace_id": 12345}

페이지네이션 중에는 기존 워크스페이스 필터 조건을 유지하며 hasMore / has_more가 false가 되면 중지합니다. 워크스페이스 ID는 목록 페이지네이션에만 사용되고 이후 Trace 조회에는 워크스페이스 UUID를 사용합니다.

동일 조직 Trace 조회¶

OpenAPI:

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

AIAPI:

POST /api/v1/data/same_org/trace/query

OpenAPI 파라미터는 lower camelCase 형식이고 AIAPI 파라미터는 snake_case 형식입니다.

OpenAPI는 selectClause와 offset을 지원하지 않습니다. 페이지네이션에는 cursorTime / cursorToken을 사용하며 자세한 절차는 아래를 참조하십시오.

OpenAPI 요청 예시¶

예시의 워크스페이스, 트레이스 ID, 시간 범위는 실제 값으로 변경해야 하며 페이지네이션 중에는 이러한 조회 조건을 유지합니다.

curl --location 'https://<studio-backend-host>/api/v1/df/same_org/trace/query' \
  --header 'Content-Type: application/json' \
  --header 'DF-API-KEY: <your-openapi-key>' \
  --data '{
    "traceId": "TRACE-XXXX",
    "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
    "startTime": 1772516130000,
    "endTime": 1772519730000,
    "limit": 100
  }'

AIAPI 요청 예시¶

{
  "trace_id": "TRACE-XXXX",
  "workspace_uuids": ["wksp_xxx", "wksp_yyy"],
  "where_clause": "`service` = 'api'",
  "start_time": 1772516130000,
  "limit": 100
}

Trace 스크롤 페이지네이션¶

OpenAPI의 단일 결과는 content.data[0]에 있고 AIAPI의 대응 위치는 data.data[0]입니다. 여기서 next_cursor_time과 next_cursor_token을 읽습니다.

1. 첫 조회에서는 커서를 생략할 수 있으며 cursorTime / cursor_time을 조회 종료 시간의 13자리 밀리초 타임스탬프로 설정할 수도 있습니다.
2. next_cursor_time < 0이면 페이지네이션을 종료합니다. 이 음수 값을 인터페이스에 다시 전달하지 마십시오.
3. 다음 페이지가 필요하면 next_cursor_time을 그대로 전달하고 비어 있지 않은 next_cursor_token도 함께 전달합니다. 이후 커서는 16자리 마이크로초 타임스탬프일 수 있으므로 밀리초로 변환하지 마십시오. 변환하면 동일한 타임스탬프 인근 데이터가 누락될 수 있습니다.
4. next_cursor_token이 비어 있으면 생략하거나 빈 문자열을 전달할 수 있습니다. 유효한 next_cursor_time이 없으면 커서를 직접 구성하거나 요청을 반복하지 말고 응답을 기록하고 원인을 조사하십시오.

이전 페이지가 반환한 next_cursor_time이 1772519729000123이고 next_cursor_token이 cursor_example이라고 가정하면 OpenAPI 다음 페이지 요청 본문은 다음과 같습니다.

{
  "traceId": "TRACE-XXXX",
  "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
  "startTime": 1772516130000,
  "endTime": 1772519730000,
  "limit": 100,
  "cursorTime": 1772519729000123,
  "cursorToken": "cursor_example"
}

위 커서는 예시일 뿐이며 실제 요청에는 반드시 이전 페이지의 응답 값을 사용해야 합니다. AIAPI는 cursor_time / cursor_token을 사용하고 나머지 필드는 앞서 설명한 snake_case 이름을 사용합니다. startTime / endTime(또는 start_time / end_time)은 기존 밀리초 시간 범위를 유지해야 하며 페이지네이션 커서와 함께 변환하면 안 됩니다. source나 필터 조건을 사용한 경우에도 페이지를 넘길 때 동일하게 유지해야 합니다.

자주 묻는 질문¶

ft.ParameterCheckFailed 반환¶

동일 조직 워크스페이스 간 Trace 조회 스위치를 비활성화한 상태에서 다른 워크스페이스를 요청하면 OpenAPI가 이 오류를 반환합니다. 대상 워크스페이스가 동일 조직에 속하지 않거나 시간 범위, 기타 파라미터가 유효하지 않은 경우에도 같은 오류가 반환될 수 있으므로 요청 파라미터와 함께 원인을 조사해야 합니다.

처리 방법:

• 먼저 시간 범위, 커서, 워크스페이스 소속 및 사이트 구성을 확인합니다.
• 현재 워크스페이스만 조회하면 되는 경우 다른 워크스페이스 UUID를 제거합니다.
• 워크스페이스 간 조회가 정말 필요하다면 Studio 백엔드 구성에서 SameOrgTraceQuerySet.enable을 활성화하고 서비스를 재시작합니다.

기존 query_data 인터페이스에 동일 조직 워크스페이스 목록을 계속 전달할 수 있나요?¶

지원하지 않습니다. /api/v1/df/query_data, /api/v1/df/query_data_v1, /api/v1/df/asynchronous/query_data 및 AIAPI의 일반 DQL 조회 인터페이스는 더 이상 동일 조직 워크스페이스 간 조회 진입 파라미터를 받지 않습니다. 동일 조직 Trace 조회 전용 인터페이스를 사용하십시오.

종료 시간을 전달하지 않으면 어떻게 조회하나요?¶

endTime / end_time을 전달하지 않으면 서버가 내부적으로 구성하는 DQL time_range에는 시작 시간만 포함됩니다. 시작 시간도 전달하지 않으면 서버는 기본적으로 최근 1시간의 시작 시간을 사용합니다.