권한이 부여된 워크스페이스 검색 및 워크스페이스 간 쿼리¶

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를 업데이트한 후 workspace 범주만 동기화하지 말고 owl sync로 전체를 동기화하세요.

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

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 및 구조화된 진단 필드는 문제 해결을 위해 보관하세요.
사이트가 도구 또는 워크스페이스 간 매개변수를 지원하지 않으면 관리자에게 서버 버전을 확인하세요. 범위 매개변수를 제거한 뒤 재시도하지 마세요.