동일 조직 내 교차 워크스페이스 Trace 조회 사용 설명¶

본 문서는 배포 플랜 Studio에서 동일 조직 내 교차 워크스페이스 Trace 조회 기능의 설정, 인터페이스 사용 방법 및 FAQ를 설명합니다.

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

사용 전제 조건¶

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

설정¶

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

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

설정 항목 설명:

설정 항목	기본값	설명
`enable`	`false`	동일 조직 내 교차 워크스페이스 Trace 조회를 허용할지 여부. 비활성화 시 현재 워크스페이스만 조회 가능합니다.
`maxWorkspaceCount`	`20`	단일 Trace 조회 및 워크스페이스 목록 필터링 시 전달 가능한 최대 워크스페이스 UUID 수입니다.
`maxLimit`	`1000`	단일 Trace 조회 시 `limit`을 명시적으로 전달할 때 허용되는 최대값입니다.
`maxTimeRangeHours`	`24`	단일 Trace 조회 시 허용되는 최대 시간 창(단위: 시간)입니다.
`workspaceListPageSizeMax`	`100`	동일 조직 워크스페이스 간소화 정보 목록 조회 인터페이스에서 허용되는 최대 페이지 크기입니다.

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

활성화/비활성화 동작¶

비활성화 시¶

SameOrgTraceQuerySet.enable=false인 경우:

동일 조직 워크스페이스 간소화 정보 목록 조회 인터페이스는 정상적으로 사용할 수 있습니다.
Trace 조회 인터페이스는 현재 워크스페이스만 조회할 수 있습니다.
요청의 대상 워크스페이스 UUID 목록에 현재 워크스페이스가 아닌 다른 워크스페이스가 포함된 경우 인터페이스는 다음을 반환합니다:

{
  "code": 406,
  "errorCode": "ft.SameOrgTraceQueryDisabled",
  "message": "동일 조직 내 교차 워크스페이스 Trace 조회 설정이 활성화되지 않았습니다."
}

현재 워크스페이스 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

일반적인 요청 매개변수:

매개변수	설명
`workspaceUUIDs`	OpenAPI 매개변수, 선택 사항, 워크스페이스 UUID 목록으로 필터링합니다.
`workspace_uuids`	AIAPI 매개변수, 선택 사항, 워크스페이스 UUID 목록으로 필터링합니다.
`pageIndex` / `page_index`	페이지 번호, 기본값 `1`.
`pageSize` / `page_size`	페이지당 항목 수, 기본값 `20`, 최대값은 `workspaceListPageSizeMax`에 의해 제어됩니다.

동일 조직 Trace 조회¶

OpenAPI:

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

AIAPI:

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

OpenAPI 매개변수는 lowerCamelCase 형식을 사용하고, AIAPI 매개변수는 snake_case 형식을 사용합니다.

OpenAPI 매개변수	AIAPI 매개변수	설명
`traceId`	`trace_id`	필수, 추적 ID.
`workspaceUUIDs`	`workspace_uuids`	선택 사항, 대상 워크스페이스 UUID 목록; 전달하지 않으면 현재 워크스페이스를 조회합니다.
`whereClause`	`where_clause`	선택 사항, 추가 DQL 필터 조건, `trace_id` 조건은 포함할 필요가 없습니다.
`source`	`source`	선택 사항, Trace 데이터 소스, 기본값은 모든 소스를 조회합니다.
`startTime`	`start_time`	선택 사항, 밀리초 타임스탬프; 전달하지 않으면 기본적으로 최근 1시간입니다.
`endTime`	`end_time`	선택 사항, 밀리초 타임스탬프; 전달하지 않으면 내부 DQL `time_range`에는 시작 시간만 있습니다.
`limit`	`limit`	선택 사항, 반환 최대 개수; 전달하지 않으면 내부 쿼리 기본값에 의해 제어됩니다.
`cursorTime`	`cursor_time`	선택 사항, 스크롤 페이지 매김 커서 시간.
`searchAfter`	`search_after`	선택 사항, 스크롤 페이지 매김 커서.

OpenAPI는 selectClause 및 offset을 지원하지 않으며, 페이지 매김은 cursorTime / searchAfter를 사용하십시오.

OpenAPI 요청 예시¶

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
}

FAQ¶

`ft.SameOrgTraceQueryDisabled` 반환¶

현재 사이트에서 동일 조직 내 교차 워크스페이스 Trace 조회 설정이 활성화되지 않았지만, 요청에 현재 워크스페이스가 아닌 UUID가 포함되었음을 의미합니다.

처리 방법:

현재 워크스페이스만 조회하면 되는 경우, 다른 워크스페이스 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시간의 시작 시간을 사용합니다.