권한이 부여된 워크스페이스 검색 및 워크스페이스 간 조회¶

OWL은 기본적으로 현재 워크스페이스를 조회합니다. 다른 워크스페이스를 조회해야 하는 경우 먼저 권한이 부여된 데이터 조회와 동일 조직 내 Trace 조회를 구분한 후 해당 도구를 선택하십시오.

조회 방식 선택¶

시나리오	워크스페이스 검색	조회 방식
현재 워크스페이스	워크스페이스 검색 불필요	워크스페이스 매개변수 없이 바로 조회
권한이 부여된 워크스페이스 간 데이터	대상이 확정되지 않은 경우 `owl.workspace.data_authorized.list` 호출	DQL 도구에 `workspace_uuids`와 `target_region`을 전달하며, 한 번의 조회는 하나의 대상 사이트로 제한
동일 조직 내 워크스페이스 간 Trace	대상 UUID가 확정되지 않은 경우 `owl.account.workspace.same_org.list` 호출	`owl.data.same_org.trace.query`에 `trace_id`와 선택한 `workspace_uuids` 전달, 생략하거나 빈 배열이면 현재 워크스페이스만 조회

이미 명확한 검색 결과가 있으면 그대로 재사용할 수 있습니다. 동일 조직 내 워크스페이스 목록은 일반 데이터 조회 권한을 의미하지 않으며, 권한이 부여된 워크스페이스 목록을 대체할 수 없습니다. 조회에 실패하거나 빈 결과가 반환된 경우 자격 증명을 전환하거나 워크스페이스 범위를 확대하거나 다른 유형의 조회 경로로 변경해서는 안 됩니다.

업그레이드 및 멤버 도구 마이그레이션¶

사용 전에 대상 사이트가 권한이 부여된 워크스페이스 검색과 워크스페이스 간 조회를 지원하는지 확인하십시오. CLI를 v1.4.0으로 업그레이드하고, 서버 측도 Registry와 도구 카탈로그를 함께 업그레이드한 후 전체 동기화를 실행하십시오. MCP 클라이언트에서 도구를 다시 검색하십시오.

owl sync
owl tool list --category workspace

새로 추가된 workspace 카테고리에는 owl.workspace.data_authorized.list와 owl.workspace.member.list가 포함됩니다. 기존 member 카테고리는 제거되며, 이전 이름 owl.member.list는 멤버 도구의 호출 별칭으로 유지되어 동일한 매개변수와 권한 검증을 재사용하지만 목록에 독립 도구로 표시되지는 않습니다.

owl exec owl.workspace.member.list -p '{"search":"alice"}'
# 이전 스크립트와의 호환
owl exec owl.member.list -p '{"search":"alice"}'

구버전 CLI는 별칭을 지원하지 않으므로 카탈로그만 동기화해서는 기존 명령이 작동한다고 보장할 수 없습니다. 먼저 CLI를 업그레이드한 후 owl sync를 실행하십시오. workspace 카테고리만 동기화해서는 안 됩니다.

권한이 부여된 워크스페이스 검색¶

owl.workspace.data_authorized.list는 사이트별로 현재 워크스페이스에 데이터 조회 권한을 부여한 워크스페이스를 나열합니다.

owl exec owl.workspace.data_authorized.list -p '{}'

매개변수	유형	설명
`region_code`	string	선택 사항, 대상 사이트 필터링, `custom:` 등의 접두어를 포함한 반환된 전체 코드 유지
`search`	string	선택 사항, 워크스페이스 이름 또는 UUID로 검색
`page_index`	integer	사이트별 페이지 번호, 1부터 시작, 기본값 1
`page_size`	integer	사이트별 페이지당 1~100개 워크스페이스, 기본값 100

선택적 문자열은 값이 없으면 생략하며, null, 빈 문자열 또는 공백만으로는 전달할 수 없습니다. 반환된 workspace_uuid와 region_code를 사용하여 대상을 선택하고, 대상 워크스페이스의 API Key로 전환해서는 안 됩니다.

반환 결과의 current_workspace는 현재 워크스페이스이며, sites[]에는 각 사이트의 workspaces와 독립적인 page_info가 포함됩니다. 전역 페이지 번호는 없습니다. 특정 사이트에 다음 페이지가 남아 있으면 필터 조건을 유지한 채 해당 사이트만 별도로 조회하십시오.

owl exec owl.workspace.data_authorized.list -p '{"region_code":"cn2","page_index":2,"page_size":100}'

워크스페이스는 (region_code, workspace_uuid)로 구분됩니다. 목록은 워크스페이스 간 조회 권한이 있음을 의미하며, 구체적인 데이터 유형과 로그 인덱스 권한은 여전히 조회 인터페이스에서 검증합니다. page_size는 조회 가능한 워크스페이스 수의 상한도 아닙니다.

단일 대상 사이트의 데이터 조회¶

CLI는 owl.data.query 또는 owl.data.simple_query_file을 사용하고, MCP는 owl.data.simple_query를 사용합니다. 워크스페이스 간 조회는 기존 DQL 매개변수 외에 다음 항목을 추가합니다.

매개변수	유형	규칙
`workspace_uuids`	string[]	비어 있지 않은 배열, 요소는 권한이 부여된 워크스페이스 목록의 `workspace_uuid`에서 가져옴
`target_region`	string	목록의 `region_code`에서 가져옴, 이 매개변수를 제공할 때는 `workspace_uuids`도 함께 제공해야 함

두 매개변수를 모두 생략하면 현재 워크스페이스를 조회합니다. 워크스페이스 UUID만 전달하면 서버가 기존 권한을 기반으로 사이트를 유추합니다. 동일 요청에서 한 사이트 내의 여러 권한이 부여된 워크스페이스를 선택할 수 있지만 여러 사이트를 혼합할 수는 없습니다. 원격 사이트를 명시적으로 조회할 때는 현재 워크스페이스를 함께 포함할 수 없습니다.

workspace_uuids=["*"]는 대상 사이트의 모든 권한이 부여된 워크스페이스를 의미합니다. 대상 사이트를 생략하면 현재 사이트를 사용하고 현재 워크스페이스를 포함합니다. *는 명시적 UUID와 혼합할 수 없으며, 페이지를 넘길 때마다 권한이 다시 확인됩니다. 고정된 조회 범위가 필요하면 명시적 UUID를 전달하십시오.

CLI 예시¶

예시의 워크스페이스, 사이트, 데이터 소스, 시간을 실제 값으로 바꾸십시오. 시간은 13자리 밀리초 타임스탬프를 사용하며, 종료 시간은 시작 시간보다 늦어야 하고 간격은 최대 7일입니다.

owl exec owl.data.simple_query_file -p '{"namespace":"L","source":"nginx","start_time":1772516130000,"end_time":1772516140000,"limit":100,"workspace_uuids":["wksp_b","wksp_c"],"target_region":"cn2"}'

CLI는 조회 결과를 data 파일로 저장하고, 파일 인덱스의 매개변수에 워크스페이스와 사이트 범위를 유지합니다. 모든 데이터에 워크스페이스 필드가 있다고 가정해서는 안 되며, 모든 데이터를 첫 번째 워크스페이스에 귀속시켜서도 안 됩니다.

MCP 예시¶

facade 모드에서는 먼저 workspace 카테고리에서 권한이 부여된 워크스페이스 도구를 검색한 후, 조회 범위를 확인하고 exec_tool을 통해 호출합니다.

{
  "tool_name": "owl.data.simple_query",
  "parameters": {
    "namespace": "L",
    "source": "nginx",
    "start_time": 1772516130000,
    "end_time": 1772516140000,
    "workspace_uuids": ["wksp_b", "wksp_c"],
    "target_region": "cn2"
  }
}

static 모드에서는 tools/list에서 도구를 검색한 후, 비즈니스 도구 이름으로 tools/call을 직접 호출하고 위 parameters 객체를 arguments로 전달합니다. 두 모드 모두 현재 연결된 인증 정보를 사용합니다.

페이지 넘김 및 오류 처리¶

권한이 부여된 워크스페이스 목록은 페이지 번호를 사용하고, 데이터 조회는 커서를 사용합니다. 데이터 응답에서 data.page_info.has_more=true인 경우, 반환된 next_cursor_time / next_cursor_token을 원래대로 다음 cursor_time / cursor_token으로 사용하며, 기존 시간, 조건, 워크스페이스 및 사이트 범위를 유지합니다.

커서 시간은 마이크로초 단위일 수 있으므로 13자리 밀리초로 변환하지 않아야 합니다. 또한 목록의 page_index, page_size를 데이터 조회에 사용해서는 안 됩니다. 각 호출은 한 페이지씩만 가져오며, 이후 페이지는 호출자가 명시적으로 요청해야 합니다.

CLI의 success 또는 MCP의 isError를 먼저 확인한 후 도구 결과를 파싱하십시오. text 도구의 AIAPI 응답은 OWL 실행 결과의 output 문자열에 있습니다.
성공했지만 데이터가 비어 있는 경우도 유효한 결과이므로 범위를 자동으로 확대하여 재조회하지 않아야 합니다.
매개변수, 권한 또는 사이트가 일치하지 않으면 매개변수를 수정하거나 권한 범위를 다시 확인하십시오. 실패를 우회하기 위해 워크스페이스별로 재시도해서는 안 됩니다.
trace ID 또는 구조화된 오류 진단 필드가 반환되면 문제 해결을 위해 해당 정보를 보존하십시오.
대상 사이트가 도구 또는 워크스페이스 간 매개변수를 지원하지 않는 경우, 관리자에게 서버 버전을 확인한 후 재시도하십시오. 워크스페이스 매개변수를 제거하고 재시도해서는 안 됩니다.