MCP 도구 목록¶
이 문서에서는 OWL MCP Server에서 현재 MCP를 통해 호출할 수 있는 비즈니스 도구 기능을 소개합니다. 도구 분류, 권한 유형, 사용 규칙, 도구 개요 및 일반적인 MCP 사용 경로를 포함합니다.
도구의 표시 범위와 호출 결과는 현재 연결에 사용된 API Key 권한에 따라 달라집니다. API Key에 관련 리소스 또는 작업 권한이 없으면 해당 도구 호출이 실패하거나 빈 결과를 반환할 수 있습니다.
주의
OWL MCP Server는 기본적으로 facade 모드를 사용하며, 클라이언트는 먼저 list_catalogs, list_tools, exec_tool 세 가지 래퍼 도구를 보게 됩니다. 서버에서 static 모드를 활성화하면 MCP tools/list에서 호출이 허용된 비즈니스 도구를 직접 노출할 수 있으며, 서버의 제외 목록에 따라 지정된 도구를 숨길 수 있습니다. 일부 도구는 OWL CLI에서만 제공되며 MCP를 통해 실행할 수 없습니다(예: 대시보드 관련 도구). 실제로 표시되는 도구는 클라이언트의 tools/list 결과를 기준으로 합니다.
v1.8.0에서 필드 검색, 페이지네이션 및 노트 expected_etag가 추가되었습니다. 전체 파라미터는 현재 도구 schema를 기준으로 합니다. 업그레이드 순서와 쓰기 복구 규칙은 v1.8.0 업데이트 설명을 참조하세요.
도구 범위¶
OWL MCP Server에서 실행 가능한 비즈니스 도구는 플랫폼 기능과 함께 지속적으로 업데이트됩니다. 실제 실행 가능한 도구는 list_catalogs 및 list_tools가 반환하는 도구 카탈로그를 기준으로 합니다.
현재 문서에서는 다음 비즈니스 분류를 다룹니다:
| 분류 | 설명 |
|---|---|
account |
동일 조직 워크스페이스 탐색 |
catalog |
통합 카탈로그 엔터티 조회, 생성, 수정 및 토폴로지 관계 조회 |
data |
데이터 소스/필드 탐색, 로그 인덱스 탐색, SLO, 로그 클러스터링, 과금 탐색, 간편 데이터 조회 및 동일 조직 내 워크스페이스 간 Trace 조회 |
errors |
오류 센터 이슈 조회 및 댓글 관리 |
event |
이벤트 목록 조회 및 이벤트 상세 조회 |
incident |
인시던트 목록 및 상세, 관련 이벤트 참조, 인시던트 댓글, 작업 기록 및 온콜 일정 |
infrastructure |
호스트, 컨테이너, 프로세스 등 인프라 객체 조회 |
llm |
LLM 관측 가능성 애플리케이션 목록 조회 |
workspace |
워크스페이스 간 데이터 조회 권한 범위 탐색, 현재 워크스페이스 멤버 및 팀 조회 |
mdsearch |
통합 문서 코퍼스 검색, 문서 읽기 및 디렉터리 탐색 |
monitor |
모니터 조회, 생성, 업데이트 및 외부 이벤트 수신 |
nbook_note |
노트 조회, 읽기, 생성, 수정 및 삭제 |
pipeline |
Pipeline 목록 조회 및 샘플 검증 |
권한 유형¶
| 권한 유형 | 의미 | 사용 권장 사항 |
|---|---|---|
| 읽기 전용 | 조회, 검색, 상세 조회, 샘플 검증 등 워크스페이스 리소스를 수정하지 않음 | 필요에 따라 Agent가 자동 호출하도록 허용할 수 있습니다 |
| 쓰기 | 생성, 업데이트, 댓글 추가, 외부 이벤트 수신 등 워크스페이스 리소스를 수정함 | Agent 클라이언트에서 수동 확인을 구성하는 것이 좋습니다 |
사용 규칙¶
facade 모드에서 MCP 클라이언트는 다음 순서로 호출해야 합니다:
list_catalogs를 호출하여 사용 가능한 분류를 확인합니다.list_tools를 호출하고catalog_id를 전달하여 해당 분류의 비즈니스 도구와 파라미터를 확인합니다.exec_tool을 호출하고tool_name과parameters를 전달하여 비즈니스 도구를 실행합니다.
static 모드에서는 클라이언트가 세 가지 래퍼 도구를 거치지 않고 tools/list가 반환하는 비즈니스 도구를 직접 호출할 수 있습니다. 어떤 모드를 사용하든 도구 파라미터와 권한 요구 사항은 동일하게 유지됩니다.
| 유형 | 규칙 |
|---|---|
| 시간 범위 | 13자리 밀리초 타임스탬프를 사용합니다 |
| 페이지네이션 파라미터 | 일반적으로 page_size와 page_index를 사용합니다 |
| 상세 조회 | 일반적으로 목록 도구가 반환하는 UUID, ID, URN 등의 식별자에 의존합니다 |
| 데이터 조회 | 먼저 탐색 도구를 호출하여 source, field, index를 얻은 다음 조회 도구를 호출하는 것이 좋습니다 |
| 반환 구조 | 실제 도구 응답을 기준으로 합니다. DQL 조회 필드의 의미는 반환 필드 설명을 참조하세요. |
도구 개요¶
| 도구 세트 | 도구 | 기능 | 권한 |
|---|---|---|---|
| account | owl.account.workspace.same_org.list |
현재 API Key 워크스페이스와 동일 조직의 워크스페이스를 나열합니다 | 읽기 전용 |
| catalog | owl.catalog.entity_type_query |
통합 카탈로그에서 지원하는 엔터티 유형을 조회합니다 | 읽기 전용 |
| catalog | owl.catalog.entity_query |
유형, 이름, URN 또는 속성으로 엔터티를 필터링합니다 | 읽기 전용 |
| catalog | owl.catalog.entity_get |
urn으로 단일 엔터티 상세를 가져옵니다 |
읽기 전용 |
| catalog | owl.catalog.entity_create |
기존 엔터티 유형 아래에 엔터티를 생성합니다 | 쓰기 |
| catalog | owl.catalog.entity_modify |
지정된 엔터티의 표시 이름, 속성 또는 관계를 수정합니다 | 쓰기 |
| catalog | owl.catalog.entity_topology_query |
단일 엔터티와 연결된 토폴로지 관계를 조회합니다 | 읽기 전용 |
| data | owl.data.show_dql_namespace |
DQL namespace를 확인합니다 | 읽기 전용 |
| data | owl.data.simple_query |
간소화된 파라미터로 조회 문을 자동 구성합니다 | 읽기 전용 |
| data | owl.external_datasource.list |
현재 워크스페이스에서 액세스 가능한 외부 데이터 소스를 탐색합니다 | 읽기 전용 |
| data | owl.external_datasource.query |
구성된 외부 데이터 소스에 대해 제한된 읽기 전용 SQL을 실행합니다 | 읽기 전용 |
| data | owl.data.same_org.trace.query |
trace_id로 현재 또는 동일 조직 워크스페이스의 Trace를 조회합니다 |
읽기 전용 |
| data | owl.metric.list |
메트릭 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.rum.list |
RUM 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.apm.list |
APM 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.network.list |
Network 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.profile.list |
Profile 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.logging.list |
로그 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.logging.cluster_task.create |
로그 클러스터링 분석 비동기 작업을 생성합니다 | 읽기 전용 |
| data | owl.logging.cluster_task.get |
로그 클러스터링 분석 작업 결과를 가져옵니다 | 읽기 전용 |
| data | owl.billing.list |
클라우드 청구 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
읽기 전용 |
| data | owl.slo.list |
현재 워크스페이스의 SLO 목록을 조회합니다 | 읽기 전용 |
| data | owl.log_index.list |
로그 조회에 사용 가능한 인덱스를 나열합니다 | 읽기 전용 |
| data | owl.log_index.get |
단일 로그 인덱스 상세를 조회합니다 | 읽기 전용 |
| data | owl.field_schema.get |
현재 필드 카탈로그를 조회합니다 | 읽기 전용 |
| data | owl.field_schema.search |
필요에 따라 필드, 메트릭 및 measurement 구성을 검색합니다 | 읽기 전용 |
| errors | owl.errors.list |
오류 센터 이슈 목록을 조회합니다 | 읽기 전용 |
| errors | owl.errors.comment.add |
오류 이슈에 댓글을 추가합니다 | 쓰기 |
| errors | owl.errors.comment.list |
오류 이슈의 댓글 목록을 조회합니다 | 읽기 전용 |
| errors | owl.errors.comment.update |
기존 오류 댓글을 업데이트합니다 | 쓰기 |
| event | owl.event.list |
이벤트 목록을 조회합니다 | 읽기 전용 |
| event | owl.event.get |
단일 이벤트 상세를 조회합니다 | 읽기 전용 |
| event | owl.event.resolve |
이벤트 문서 ID, 이벤트 또는 인시던트 ID, 링크를 기준으로 이벤트 상세를 확인합니다 | 읽기 전용 |
| incident | owl.incident.list |
인시던트 목록을 조회합니다 | 읽기 전용 |
| incident | owl.incident.get |
인시던트 상세 및 페이지네이션된 관련 이벤트 참조를 조회합니다 | 읽기 전용 |
| incident | owl.incident_comment.list |
인시던트 댓글 목록을 조회합니다 | 읽기 전용 |
| incident | owl.incident_comment.add |
인시던트에 댓글을 추가합니다 | 쓰기 |
| incident | owl.incident_operation.list |
인시던트 작업 기록을 조회합니다 | 읽기 전용 |
| incident | owl.incident_schedule.list |
온콜 일정 목록을 조회합니다 | 읽기 전용 |
| incident | owl.incident_schedule.get |
온콜 일정 상세를 조회합니다 | 읽기 전용 |
| infrastructure | owl.infrastructure.list |
인프라 객체 목록을 조회합니다 | 읽기 전용 |
| infrastructure | owl.infrastructure.get |
단일 인프라 객체 상세를 조회합니다 | 읽기 전용 |
| llm | owl.llm.list |
LLM 애플리케이션 목록을 조회합니다 | 읽기 전용 |
| workspace | owl.workspace.data_authorized.list |
사이트별로 현재 워크스페이스에 데이터 조회 권한이 부여된 워크스페이스를 나열합니다 | 읽기 전용 |
| workspace | owl.workspace.member.list |
워크스페이스 멤버 목록을 조회합니다 | 읽기 전용 |
| workspace | owl.workspace.member.group_list |
현재 워크스페이스의 팀을 조회합니다 | 읽기 전용 |
| mdsearch | mdsearch_search |
통합 문서 코퍼스를 검색하고 후보 문서를 반환합니다 | 읽기 전용 |
| mdsearch | mdsearch_document |
id 또는 path로 전체 문서를 읽습니다 | 읽기 전용 |
| mdsearch | mdsearch_catalog |
문서 코퍼스의 디렉터리 구조를 탐색합니다 | 읽기 전용 |
| monitor | owl.monitor.list |
모니터 목록을 조회합니다 | 읽기 전용 |
| monitor | owl.monitor.upsert |
모니터를 생성하거나 기존 모니터를 업데이트합니다 | 쓰기 |
| monitor | owl.monitor.receive |
기존 수신 대상으로 외부 이벤트를 전송하거나, 수신기를 먼저 생성한 후 이벤트를 전송합니다 | 쓰기 |
| monitor | owl.monitor.get |
모니터 상세를 조회합니다 | 읽기 전용 |
| nbook_note | owl.nbook_note.list |
현재 계정에서 볼 수 있는 노트 요약을 조회합니다 | 읽기 전용 |
| nbook_note | owl.nbook_note.get |
노트 상세 및 Markdown 본문을 가져옵니다 | 읽기 전용 |
| nbook_note | owl.nbook_note.add |
노트를 생성합니다 | 쓰기 |
| nbook_note | owl.nbook_note.modify |
노트를 수정합니다 | 쓰기 |
| nbook_note | owl.nbook_note.delete |
노트를 삭제합니다 | 쓰기 |
| pipeline | owl.pipeline.list |
Pipeline 목록을 조회하고 디코딩된 콘텐츠를 반환합니다 | 읽기 전용 |
| pipeline | owl.pipeline.validate |
샘플 데이터로 Pipeline 처리 결과를 검증합니다 | 읽기 전용 |
Account¶
동일 조직 탐색에는 다음 표의 도구를 사용합니다. 반환된 workspace_uuid는 owl.data.same_org.trace.query의 workspace_uuids 입력 파라미터로 사용하여 워크스페이스 간 Trace 조회에 활용할 수 있습니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.account.workspace.same_org.list |
현재 워크스페이스와 동일 조직의 워크스페이스를 workspace id 내림차순으로 나열합니다 | 현재 워크스페이스와 동일 조직의 워크스페이스를 나열합니다 | workspace_uuids, page_size, before_workspace_id |
읽기 전용 |
주의: 반환 결과의
workspace_uuid만 이후workspace_uuids입력 파라미터로 사용해야 합니다.workspace_id는 목록 페이지네이션에만 사용되며 Trace 조회 도구에 전달해서는 안 됩니다.
v1.6.0부터 owl exec owl.account.workspace.same_org.list로 호출할 수 있으며, owl workspace same-org list 및 MCP와 목록 계약을 공유합니다. 결과에는 items와 page_info가 포함됩니다. page_size의 기본값은 20이고 범위는 1–100입니다. 다음 페이지에서는 next_before_workspace_id를 양의 정수 before_workspace_id로 그대로 전달해야 하며, 배열 인덱스에서 추론해서는 안 됩니다. workspace_uuids로 결과를 필터링할 수 있으며, 빈 배열은 필터링하지 않음을 의미합니다. 반환된 workspace_uuid는 동일 조직 Trace 조회에만 사용하며, 이 목록은 일반 데이터 조회 권한을 생성하지 않습니다.
Catalog¶
통합 카탈로그의 엔터티 유형 탐색, 엔터티 조회, 생성, 수정 및 토폴로지 관계 조회에 사용합니다. 엔터티를 생성하거나 수정할 때 사용하는 API Key에는 카탈로그 관리 권한이 있어야 합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.catalog.entity_type_query |
통합 카탈로그에서 지원하는 엔터티 유형을 조회합니다 | 현재 Catalog에서 지원하는 엔터티 유형을 나열합니다 | page_size, page_index |
읽기 전용 |
owl.catalog.entity_query |
유형, 이름, URN 또는 속성으로 엔터티를 필터링합니다 | 이름이 checkout-api인 service 엔터티를 정확히 찾습니다 |
entity_type, name, search, urn, filters, page_size, page_index |
읽기 전용 |
owl.catalog.entity_get |
urn으로 단일 엔터티 상세를 가져옵니다 |
이 urn에 해당하는 엔터티 상세를 조회합니다 |
urn |
읽기 전용 |
owl.catalog.entity_create |
기존 엔터티 유형 아래에 엔터티를 생성합니다 | 이름이 checkout-api인 서비스 엔터티를 생성합니다 |
request_id, entity_type, name, display_name, attributes, relation_modes |
쓰기 |
owl.catalog.entity_modify |
지정된 엔터티의 표시 이름, 속성 또는 관계를 수정합니다 | 서비스 엔터티의 표시 이름을 수정하고 다른 구성은 유지합니다 | request_id, urn, display_name, attributes, relation_modes |
쓰기 |
owl.catalog.entity_topology_query |
단일 엔터티와 연결된 토폴로지 관계를 조회합니다 | 이 호스트 엔터티의 업스트림/다운스트림 토폴로지를 확인합니다 | urn |
읽기 전용 |
entity_query는 반드시 entity_type을 지정해야 합니다. name은 정확한 일치에 사용하고, search는 이름, 표시 이름 또는 URN의 부분 검색에 사용하며, 두 가지를 동시에 사용할 수 없습니다. 전체 urn 또는 filters로 범위를 좁힐 수도 있습니다.
엔터티 생성 및 수정¶
OWL을 연결한 후 도구 호출을 지원하는 AI 클라이언트에서 다음과 같이 명확한 요구 사항을 제시할 수 있습니다:
- “먼저 service 유형에 필요한 속성을 확인한 다음, 이름이 checkout-api인 엔터티를 생성해 주세요. 쓰기 전에 확인할 구성을 나열해 주세요.”
- “checkout-api 엔터티의 표시 이름을 정산 서비스로 변경하고, 다른 속성과 관계는 그대로 유지해 주세요.”
먼저 엔터티 유형의 필드 요구 사항을 조회한 다음 대상 엔터티를 찾는 것이 좋습니다. 생성에는 owl.catalog.entity_create를 사용하고, 수정에는 조회에서 반환된 전체 urn으로 owl.catalog.entity_modify를 호출합니다. 소속 팀을 설정해야 하는 경우 먼저 owl.workspace.member.group_list를 통해 팀 이름을 가져옵니다. 완료 후 플랫폼의 통합 카탈로그로 돌아가 엔터티를 확인할 수 있습니다.
생성 시에는 request_id, entity_type, name을 반드시 제공해야 하며, 유형 요구 사항에 따라 attributes를 보완해야 합니다. 수정 시에는 request_id와 urn을 반드시 제공하고, 동시에 수정할 항목을 하나 이상 지정해야 합니다. request_id는 이번 작업을 식별하는 UUID를 사용합니다. 표시 이름에는 display_name을 사용하며, 수정 도구는 엔터티 이름이나 유형 변경을 지원하지 않습니다.
수정 시 제출하지 않은 속성과 관계는 유지됩니다. 의존성, 구성 요소 등의 관계를 수정하려면 relation_modes를 설정해야 합니다. add는 추가, replace는 전체 교체, replace와 빈 배열의 조합은 비우기를 의미합니다. 필드, 관계 및 소속 팀 이름은 현재 워크스페이스의 실제 구성을 기준으로 해야 합니다.
결과에서 확인 대기 상태가 표시되면 원래 request_id와 파라미터를 유지하고 반환된 안내에 따라 확인하세요. UUID를 변경하여 생성 또는 수정을 반복하지 마세요. 결과에서 감사 상태가 불확실하다고 표시되면 먼저 관리자에게 문의하여 확인해야 합니다.
주의: 대시보드 도구(
owl.dashboard.create/owl.dashboard.replace/owl.dashboard.get)는 OWL CLI에서만 제공되며 MCP 도구 목록에는 표시되지 않습니다. 관련 사용법은 OWL CLI 문서를 참조하세요.
Data¶
v1.6.0에서는 13자리 정수 밀리초 타임스탬프를 통일적으로 검증하며, 종료 시간이 시작 시간보다 커야 합니다. 쌍으로 제공해야 하는 파라미터는 한쪽만 전달할 수 없습니다. 필수 요구 사항과 최대 범위는 각 도구 schema를 기준으로 합니다. owl.data.query의 시간 범위는 최대 7일입니다.
v1.5.0부터 owl.metric/rum/apm/network/profile/logging/billing.list 및 owl.infrastructure.list/get에는 13자리 밀리초 단위 start_time / end_time을 반드시 전달해야 하며, 시간 범위는 7일을 초과할 수 없습니다. owl.llm.list의 시간 범위는 선택 사항이며, 둘 다 생략하면 최근 24시간을 사용합니다.
owl.data.show_dql_namespace가 반환하는 dql_namespace는 조회 별칭이며 백엔드의 원시 유형 이름이 아닙니다. owl.data.query를 호출할 때는 dql_namespace에 전달하고, simple query 또는 로그 클러스터링 도구를 호출할 때는 동일한 값을 그대로 namespace에 전달합니다.
권한이 부여된 조회 워크스페이스는 owl.workspace.data_authorized.list를 통해 탐색할 수 있으며, region_code, search, page_index, page_size를 지원하고 사이트별로 독립적으로 페이지네이션됩니다. workspace_uuid와 region_code를 owl.data.simple_query의 workspace_uuids와 target_region에 전달하면 동일한 대상 사이트 내의 여러 권한 부여 워크스페이스를 조회할 수 있습니다. 자세한 내용은 워크스페이스 간 조회 설명을 참조하세요.
DQL namespace 탐색, 데이터 소스 및 필드 탐색, 외부 데이터 소스 읽기 전용 SQL, 로그 인덱스 탐색, SLO 조회, 로그 클러스터링 분석, 동일 조직 내 워크스페이스 간 Trace 조회, 그리고 MCP 클라이언트용 간편 데이터 조회에 사용합니다. 현재 MCP 측에서는 간편 조회 및 조회 보조 도구를 제공하며, 전체 DQL 또는 PromQL 사용자 정의 실행 도구는 포함하지 않습니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.data.show_dql_namespace |
현재 지원되는 DQL namespace를 나열하고 index 지원 여부를 표시합니다 |
현재 지원되는 DQL namespace를 나열합니다 | 없음 | 읽기 전용 |
owl.data.simple_query |
간소화된 파라미터로 조회 문을 자동 구성합니다 | 간단한 조회 방식으로 최근 30분 CPU 사용률을 집계합니다 | namespace, start_time, end_time, source, select_clause, where_clause, group_by_clause, index, workspace_uuids, target_region, limit |
읽기 전용 |
owl.external_datasource.list |
현재 워크스페이스에서 액세스하고 조회할 수 있는 외부 데이터 소스를 탐색합니다 | 이름이 orders인 구성된 외부 데이터 소스를 찾습니다 | keyword, source_type, page_index, page_size |
읽기 전용 |
owl.external_datasource.query |
구성된 외부 데이터 소스 하나에 대해 제한된 읽기 전용 SQL 한 건을 실행합니다 | orders 데이터 소스에서 최근 주문 20건을 조회합니다 | datasource_uuid, sql, timeout_seconds, max_rows |
읽기 전용 |
owl.data.same_org.trace.query |
trace_id로 현재 또는 동일 조직 워크스페이스의 Trace를 조회합니다 |
여러 동일 조직 워크스페이스에 걸친 Trace를 조회합니다 | trace_id, workspace_uuids, start_time, end_time, where_clause, source, limit, cursor_time, cursor_token |
읽기 전용 |
owl.metric.list |
메트릭 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
메트릭 영역에서 사용 가능한 source를 나열합니다 | mode, start_time, end_time |
읽기 전용 |
owl.rum.list |
RUM 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
RUM 영역에서 사용 가능한 필드를 나열합니다 | mode, start_time, end_time |
읽기 전용 |
owl.apm.list |
APM 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
APM 영역에서 사용 가능한 source를 조회합니다 | mode, start_time, end_time |
읽기 전용 |
owl.network.list |
Network 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
Network 영역에서 사용 가능한 필드를 나열합니다 | mode, start_time, end_time |
읽기 전용 |
owl.profile.list |
Profile 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
Profile 영역에서 사용 가능한 source를 확인합니다 | mode, start_time, end_time |
읽기 전용 |
owl.logging.list |
로그 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
로그 영역에서 사용 가능한 source를 나열합니다 | mode, source, start_time, end_time |
읽기 전용 |
owl.logging.cluster_task.create |
로그 클러스터링 분석 비동기 작업을 생성하고 task_id를 반환합니다 |
최근 오류 로그를 유사한 메시지 기준으로 클러스터링합니다 | timeRange, analysisField, namespace, conditions, query, indexes |
읽기 전용 |
owl.logging.cluster_task.get |
task_id로 로그 클러스터링 분석 결과를 가져옵니다 |
이 로그 클러스터링 작업의 결과를 조회합니다 | task_id |
읽기 전용 |
owl.billing.list |
클라우드 청구 조회에 사용 가능한 source 또는 필드를 탐색합니다 |
클라우드 청구에서 사용 가능한 source를 나열합니다 | mode, source, start_time, end_time |
읽기 전용 |
owl.slo.list |
현재 워크스페이스의 SLO 목록을 조회하며, 이름 또는 모니터 UUID로 검색할 수 있습니다 | 현재 워크스페이스의 SLO를 나열합니다 | search, page_size, page_index |
읽기 전용 |
owl.log_index.list |
로그 조회에 사용 가능한 인덱스를 나열합니다 | 현재 로그 인덱스를 나열합니다 | 없음 | 읽기 전용 |
owl.log_index.get |
단일 로그 인덱스 상세를 조회합니다 | 이 로그 인덱스 UUID의 상세를 조회합니다 | index_uuid |
읽기 전용 |
owl.field_schema.get |
현재 필드 카탈로그를 조회하여 조회 필드를 보완합니다 | 현재 사용 가능한 필드 카탈로그를 나열합니다 | 없음 | 읽기 전용 |
owl.field_schema.search |
필요에 따라 필드, 메트릭 및 measurement 구성을 검색합니다 | 유형, 단위 출처 및 페이지네이션 정보를 반환합니다 | kind, search, namespace, measurement, page_index, page_size |
읽기 전용 |
owl.data.same_org.trace.query의workspace_uuids를 생략하거나 빈 배열로 전달하면 현재 워크스페이스만 조회합니다. 동일 조직 내 워크스페이스 간 조회 기능이 비활성화된 경우 현재 워크스페이스만 조회할 수 있으며, 다른 워크스페이스 UUID를 전달하면 파라미터 오류가 반환됩니다.
Errors¶
오류 센터의 이슈 목록 조회와 댓글 추가, 조회 및 업데이트에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.errors.list |
오류 센터 이슈 목록을 조회합니다 | 최근 24시간의 오류 이슈 목록을 조회합니다 | start_time, end_time, page_size, page_index, conditions, assigner, issue_status |
읽기 전용 |
owl.errors.comment.add |
오류 이슈에 댓글을 추가합니다 | 이 오류 이슈에 문제 해결 댓글을 추가합니다 | issue_id, comment, attachment_uuids, extend |
쓰기 |
owl.errors.comment.list |
오류 이슈의 댓글 목록을 조회합니다 | 이 오류 이슈의 댓글 기록을 확인합니다 | issue_id, page_size, page_index |
읽기 전용 |
owl.errors.comment.update |
기존 오류 댓글을 업데이트합니다 | 이 오류 댓글의 내용을 업데이트합니다 | comment_uuid, comment, attachment_uuids, extend |
쓰기 |
Event¶
이벤트 센터 목록 조회 및 이벤트 상세 조회에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.event.list |
이벤트 목록을 조회합니다 | 최근 1시간의 critical 이벤트를 조회합니다 | start_time, end_time, status, limit, offset |
읽기 전용 |
owl.event.get |
단일 이벤트 상세를 조회하며 이벤트 시간 범위를 지정할 수 있습니다 | 지정된 시간 범위에서 이 이벤트 doc_id의 상세를 조회합니다 |
doc_id, timeRange |
읽기 전용 |
owl.event.resolve |
이벤트 문서 ID, 이벤트 또는 인시던트 ID, 링크를 기준으로 이벤트 상세를 확인합니다 | 이벤트 문서 ID, 이벤트 또는 인시던트 ID, 링크를 기준으로 이벤트 상세를 확인합니다 | doc_id, timeRange |
읽기 전용 |
owl.event.list는start_time과end_time을 반드시 제공해야 합니다.status의 선택 가능한 값은fatal,critical,error,warning,nodata이며,limit의 기본값은 20, 최댓값은 100입니다. 반환 항목에는 이벤트 차원 태그 필드df_dimension_tags가 포함될 수 있습니다.owl.event.get의timeRange는 선택적 2요소 배열[start, end]이며, 각 요소는 13자리 밀리초 타임스탬프이고end는start보다 커야 합니다. 파라미터 이름은timeRange이며time_range로 바꾸지 마세요.
이벤트 ID 및 링크 확인¶
owl.event.get의 doc_id는 비어 있거나 모두 공백이어서는 안 되며, owl.event.list가 반환한 data.items[].doc_id 원래 값을 사용합니다. 이벤트 ID, 인시던트 ID, 호환되는 불투명 ID 또는 HTTP(S) 이벤트 링크는 owl.event.resolve에 전달할 수 있습니다. 링크는 식별자와 시간을 추출하는 데만 사용되며 액세스되지 않고, 워크스페이스나 자격 증명을 전환하지 않습니다. 링크의 시간과 명시적 timeRange는 반드시 일치해야 합니다.
문서 ID와 불투명 ID는 먼저 상세를 직접 읽으려고 시도합니다. 빈 결과가 확인된 경우에만 검색을 계속하며, 이벤트 또는 인시던트 ID는 정확한 식별자 검색으로 바로 진행합니다. 검색에서 시간을 생략하면 최근 7일을 사용하고, 명시적 검색 범위는 최대 7일이며, 최대 20개의 후보를 반환합니다. 직접 상세 읽기는 7일 상한의 제한을 받지 않습니다. 범위가 너무 길어 상세가 비어 있으면 중지하며 검색 범위를 좁히지 않습니다. resolution_status, candidates, may_have_more를 확인하세요. multiple_matches는 여전히 모호성이 있음을 의미하며, 함께 제공된 최신 후보 상세를 유일한 확인 결과로 사용할 수 없습니다.
{
"tool_name": "owl.event.resolve",
"parameters": {
"doc_id": "event-example",
"timeRange": [1792548000000, 1792551600000]
}
}
Incident¶
owl.incident.get는 인시던트 UUID(incident_*)를 받아 상세 및 related_event_refs를 반환합니다. 관련 참조는 페이지당 기본값과 최댓값이 100이며, page_info.has_more와 next_page_index에 따라 다음 페이지를 읽은 후 이벤트 참조를 기반으로 owl.event.get을 호출합니다. 인시던트 UUID를 이벤트 문서 ID로 사용하지 마세요. 참조 총수는 인시던트에서 보고된 이벤트 총수와 다를 수 있으므로 누락된 증거를 보존하고 설명해야 합니다.
인시던트 목록과 상세, 관련 이벤트 참조, 인시던트 댓글, 작업 기록 및 온콜 일정 조회에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.incident.list |
인시던트 목록을 조회합니다 | 현재 모든 인시던트를 조회합니다 | search, page_size, page_index |
읽기 전용 |
owl.incident.get |
인시던트 상세 및 페이지네이션된 관련 이벤트 참조를 조회합니다 | 인시던트 출처, 발생 시간 및 관련 이벤트를 가져옵니다 | incident_uuid, page_size, page_index |
읽기 전용 |
owl.incident_comment.list |
인시던트 댓글 목록을 조회합니다 | 이 인시던트의 댓글 기록을 확인합니다 | incident_uuid, page_index, page_size |
읽기 전용 |
owl.incident_comment.add |
인시던트에 댓글을 추가합니다 | 이 인시던트에 처리 진행 상황을 추가합니다 | incident_uuid, comment |
쓰기 |
owl.incident_operation.list |
인시던트 작업 기록을 조회합니다 | 이 인시던트의 작업 이력을 확인합니다 | incident_uuid, page_size, page_index |
읽기 전용 |
owl.incident_schedule.list |
온콜 일정 목록을 조회합니다 | 현재 온콜 일정 목록을 조회합니다 | search, page_size, page_index |
읽기 전용 |
owl.incident_schedule.get |
온콜 일정 상세를 조회합니다 | 이 온콜 일정의 상세 구성을 조회합니다 | schedule_uuid |
읽기 전용 |
Infrastructure¶
호스트, 컨테이너, 프로세스 등 리소스 객체를 포함한 인프라 객체 목록 및 상세 조회에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.infrastructure.list |
인프라 객체 목록을 조회합니다 | 현재 모든 호스트 객체를 조회합니다 | resource_type, limit, filters, start_time, end_time, cursor_time, cursor_token |
읽기 전용 |
owl.infrastructure.get |
단일 인프라 객체 상세를 조회합니다 | 이 컨테이너 객체의 상세 정보를 조회합니다 | resource_type, identity_value, start_time, end_time, cursor_time, cursor_token |
읽기 전용 |
owl.infrastructure.list의 limit 기본값은 20이고 범위는 1–100입니다. 각 filters 항목에는 field, op, value가 반드시 포함되어야 하며, op는 =, !=, in만 지원합니다. in의 값은 비어 있지 않은 배열이어야 합니다. 나머지 연산자는 null이 아닌 문자열, 숫자 또는 불리언 값을 사용합니다. 값은 JSON으로 전달하며, 미리 DQL로 결합하거나 이스케이프하지 마세요.
LLM¶
LLM 관측 가능성 애플리케이션 목록 조회에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.llm.list |
LLM 애플리케이션 목록을 조회합니다 | 현재 모든 LLM 애플리케이션을 나열합니다 | search, type, page_size, page_index, start_time, end_time, app_type |
읽기 전용 |
Workspace¶
워크스페이스 간 데이터 조회 권한 범위 탐색과 현재 워크스페이스 멤버 및 팀 조회에 사용합니다. 멤버는 이름, 이메일 키워드로 검색할 수 있고, 팀은 이름 키워드로 검색할 수 있습니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.workspace.data_authorized.list |
현재 워크스페이스에 데이터 조회 권한을 부여한 워크스페이스를 나열합니다 | 워크스페이스 간 조회 전에 조회 가능한 워크스페이스를 확인합니다 | region_code, search, page_index, page_size |
읽기 전용 |
owl.workspace.member.list |
워크스페이스 멤버 목록을 조회합니다 | 이메일에 alice가 포함된 멤버를 검색합니다 |
search, page_size, page_index |
읽기 전용 |
owl.workspace.member.group_list |
현재 워크스페이스의 팀을 조회하고 팀 이름, UUID 및 멤버 수를 반환합니다 | 엔터티의 소속 팀으로 설정할 수 있는 Platform 팀을 찾습니다 |
search |
읽기 전용 |
owl.member.list는 명시적 호출을 위한 호환 별칭으로 유지되며 독립 도구로 나열되지 않습니다. CLI는 별칭을 지원하는 버전으로 업그레이드한 후 owl sync를 실행해야 합니다.
owl.workspace.member.group_list에서 search를 전달하지 않으면 페이지네이션 없이 모든 표시 가능한 팀을 반환합니다. 무료 플랜 워크스페이스는 이 도구를 지원하지 않습니다. owl.member.group_list는 호환 별칭입니다.
Monitor¶
모니터 목록 조회, 상세 조회, 생성 또는 업데이트, 외부 이벤트 수신에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.monitor.list |
모니터 목록을 조회합니다 | 현재 활성화된 모니터를 조회합니다 | search, status_list, page_size, page_index |
읽기 전용 |
owl.monitor.upsert |
모니터를 생성하거나 기존 모니터를 업데이트합니다 | 외부 이벤트 모니터를 새로 생성합니다 | json_script, rule_uuid, status, secret, alert_policy_uuids, tags |
쓰기 |
owl.monitor.receive |
기존 수신 대상으로 외부 이벤트를 전송하거나, 수신기를 먼저 생성한 후 이벤트를 전송합니다 | 이 모니터에 테스트 이벤트를 전송합니다 | event, target, monitor, extra_data |
쓰기 |
owl.monitor.get |
모니터 상세를 조회합니다 | 이 모니터 규칙의 전체 구성을 조회합니다 | rule_uuid |
읽기 전용 |
노트¶
현재 API Key 계정에서 볼 수 있는 노트를 관리하는 데 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.nbook_note.list |
표시 가능한 노트 요약을 조회하며 Markdown 본문은 반환하지 않습니다 | 제목 또는 본문에 지정된 내용이 포함된 노트를 검색하거나 유형, 태그로 필터링합니다 | page_index, page_size, search, tags, tagkv_query, type |
읽기 전용 |
owl.nbook_note.get |
note_uuid로 노트 상세 및 Markdown 본문을 가져옵니다 |
이 노트의 전체 Markdown 본문을 읽습니다 | note_uuid |
읽기 전용 |
owl.nbook_note.add |
노트를 생성하고 노트 요약을 반환합니다 | 태그가 있는 Markdown 노트를 생성합니다 | title, content, tags, tag_kv, type |
쓰기 |
owl.nbook_note.modify |
note_uuid로 노트를 수정하고 업데이트된 요약을 반환합니다 |
이 노트의 제목, 본문 또는 태그를 업데이트합니다 | note_uuid, title, content, tags, tag_kv, expected_etag |
쓰기 |
owl.nbook_note.delete |
note_uuid로 노트를 삭제합니다 |
이 노트를 삭제합니다 | note_uuid, expected_etag |
쓰기 |
owl.nbook_note.list의page_index기본값은 1,page_size기본값은 20, 최댓값은 100입니다.owl.nbook_note.get은 Markdown 본문content를 반환하는 유일한 노트 도구이지만path,etag또는version은 반환하지 않습니다.list,add,modify는 요약만 반환하며content,path, ETag 또는 버전 정보를 반환하지 않습니다.delete응답은 백엔드의 기존 간결 구조를 유지합니다.type은normal과runbook을 지원합니다.owl.nbook_note.list는type으로 필터링할 수 있으며, 생략하면 유형을 필터링하지 않습니다.owl.nbook_note.add는type을 설정할 수 있으며, 생략하면 백엔드에서normal노트를 생성합니다.get과modify의 응답에는type이 포함되지만get,modify,delete는 모두type입력 파라미터를 받지 않으며, 기존 노트 유형은 수정할 수 없습니다.owl.nbook_note.add는title과content를 반드시 제공해야 하며path는 허용하지 않습니다.created_source는 서버에서ai로 고정 설정되며, 생성 계정은 현재 API Key에서 가져옵니다.owl.nbook_note.modify는note_uuid외에title,content,tags,tag_kv중 하나 이상을 제공해야 합니다.content를 생략하면 기존 본문을 유지합니다.- 조회, 수정 및 삭제에는 모두 목록이 반환한
note_uuid를 사용합니다.path,etag,if_match,version,creator,created_source등 백엔드가 관리하는 필드를 전달하지 마세요. tagkv_query는 목록 도구에서 사용하는 TagKV 표현식 문자열입니다.tag_kv는 생성 및 수정 도구에서 사용하는 키-값 객체입니다. 둘을 혼용하지 마세요.
Pipeline¶
Pipeline 목록 조회 및 샘플 검증에 사용합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
owl.pipeline.list |
Pipeline 목록을 조회하고 디코딩된 콘텐츠를 반환합니다 | 이름에 nginx가 포함된 Pipeline을 나열합니다 | search, scope, categories |
읽기 전용 |
owl.pipeline.validate |
샘플 데이터로 Pipeline 처리 결과를 검증합니다 | 이 로그 샘플로 이 Pipeline이 올바르게 파싱되는지 검증합니다 | content, testData, dataType |
읽기 전용 |
mdsearch¶
통합 문서 코퍼스를 검색하고, id 또는 path로 전체 문서를 읽으며, 코퍼스 디렉터리 구조를 탐색하는 데 사용합니다. 중국어, 영어 및 혼합 조회를 지원합니다.
| 도구 이름 | 기능 | 질문 예시 | 주요 파라미터 | 권한 |
|---|---|---|---|---|
mdsearch_search |
통합 문서 코퍼스를 검색하고 정렬된 후보 문서를 반환합니다 | “DQL 시간 범위”가 포함된 문서를 검색합니다 | q, top, path_prefix, tags, mode, sort |
읽기 전용 |
mdsearch_document |
id 또는 path로 전체 문서를 읽습니다 |
이 문서 id의 전체 콘텐츠를 읽습니다 | id, meta |
읽기 전용 |
mdsearch_catalog |
문서 코퍼스의 최상위 디렉터리와 대표 문서를 탐색합니다 | 문서 코퍼스에 어떤 디렉터리가 있는지 확인합니다 | 없음 | 읽기 전용 |
MCP 사용 경로¶
다음 단계는 기본 facade 모드를 예로 듭니다. 서버에서 static 모드를 활성화한 경우 exec_tool을 거치지 않고 동일한 이름의 비즈니스 도구를 직접 호출할 수 있습니다.
데이터 조회 관련 질문¶
“메트릭, 로그, RUM, APM, Network, Profile 데이터 조회” 등의 질문에 적용됩니다.
exec_tool을 통해owl.data.show_dql_namespace를 호출하여 데이터 namespace를 확인합니다.- 데이터 영역에 따라
exec_tool을 통해 탐색 도구를 호출합니다: - 메트릭:
owl.metric.list - RUM:
owl.rum.list - APM:
owl.apm.list - Network:
owl.network.list - Profile:
owl.profile.list - 로그:
owl.logging.list - 클라우드 청구:
owl.billing.list - 로그 인덱스:
owl.log_index.list - 필드 카탈로그:
owl.field_schema.get - 필요한
source,field,index를 얻은 후exec_tool을 통해owl.data.simple_query를 호출하여 조회를 실행합니다.
외부 데이터 소스 조회¶
- connector 데이터 소스 ID 또는 이름만 있는 경우 먼저
owl.external_datasource.list를 호출합니다.datasource_id의 정확한 일치를 우선하고, 그렇지 않으면 이름의 정확한 일치를 사용하여 고유한datasource_uuid를 확인합니다. 일치하는 항목이 없거나 여러 개인 경우 추측하지 마세요. - 테이블 또는 필드가 명확하지 않은 경우 데이터 소스가 반환하는 기능이 허용할 때만 제한된 탐색 문을 실행합니다. Func MySQL은 현재
select/with만 선언하므로 필드와 행 수를 제한한information_schema.tables/columns조회를 사용해야 하며, 선언되지 않은SHOW/DESCRIBE/EXPLAIN을 시도하지 마세요. - 원시 행을 조회할 때는 결정적인
ORDER BY와 SQLLIMIT을 사용합니다.max_rows는 응답 보호일 뿐입니다.truncated=true는 결과가 불완전함을 의미합니다. datasource_id는 탐색에만 사용하며, 조회 시에는 목록이 반환한datasource_uuid를 제출해야 합니다. DSN, 비밀번호, 연결 URL, server ID 또는 workspace 식별자를 제출하지 마세요.
인시던트 트러블슈팅 관련 질문¶
“인시던트 조회, 인시던트 처리 과정 추적, 인시던트 댓글 보완” 등의 질문에 적용됩니다.
- 인시던트 UUID를 알고 있는 경우
exec_tool을 통해owl.incident.get을 호출합니다. 대상이 확정되지 않은 경우 먼저owl.incident.list를 호출합니다. - 반환된 페이지네이션 정보에 따라 모든 관련 이벤트 참조를 읽은 후
owl.event.get을 호출하여 이벤트 내용을 가져옵니다. owl.incident_comment.list로 댓글을 확인하고,owl.incident_operation.list로 작업 기록을 확인합니다.- 처리 정보를 보완해야 하는 경우
exec_tool을 통해owl.incident_comment.add를 호출합니다.
리소스 객체 식별 관련 질문¶
“호스트, 컨테이너, 프로세스 등 인프라 객체 상세 조회” 질문에 적용됩니다.
exec_tool을 통해owl.infrastructure.list를 호출하여 대상 객체를 찾습니다.- 반환 결과의 식별자 정보를 기반으로
exec_tool을 통해owl.infrastructure.get을 호출하여 객체 상세를 가져옵니다.
워크스페이스 간 Trace 조회 관련 질문¶
“trace_id로 동일 조직의 여러 워크스페이스에 걸친 Trace 하나를 조회”하는 질문에 적용됩니다.
- 현재 워크스페이스의 Trace는 직접 조회합니다. 다른 동일 조직 워크스페이스가 필요하고 UUID가 확정되지 않은 경우
exec_tool을 통해owl.account.workspace.same_org.list를 호출하여 후보 워크스페이스를 탐색합니다. - 반환 결과에서
workspace_uuid를 가져옵니다(workspace_id를 가져오지 않음). exec_tool을 통해owl.data.same_org.trace.query를 호출하고 필수trace_id를 전달하며, 선택한workspace_uuid를workspace_uuids로 전달합니다. 생략하거나 빈 배열로 전달하면 현재 워크스페이스만 조회합니다.- 추가 필터가 필요한 경우 바깥쪽 중괄호를 포함하지 않은
where_clause를 사용하고,trace_id조건을 중복 추가하지 마세요. 워크스페이스 간 Trace 조회에서는owl.data.simple_query로 대체하지 마세요.
노트 관리 관련 질문¶
“노트 검색, 읽기, 생성, 수정 또는 삭제” 등의 질문에 적용됩니다.
exec_tool을 통해owl.nbook_note.list를 호출하여 노트를 검색하고note_uuid를 얻습니다.- Markdown 본문을 읽어야 하는 경우
owl.nbook_note.get을 호출합니다. - 노트를 생성할 때는
owl.nbook_note.add를 호출하고, 업데이트할 때는owl.nbook_note.modify를 호출합니다. - 삭제할 때는
owl.nbook_note.delete를 호출합니다.add,modify,delete는 쓰기 도구이므로 실행 전에 클라이언트에서 수동 확인을 거쳐야 합니다.
모니터 관리 관련 질문¶
“모니터 조회, 모니터 생성 또는 업데이트, 외부 이벤트 전송” 등의 질문에 적용됩니다.
exec_tool을 통해owl.monitor.list를 호출하여 모니터를 조회합니다.- 반환 결과의
rule_uuid를 기반으로exec_tool을 통해owl.monitor.get을 호출하여 모니터 상세를 확인합니다. - 모니터를 생성하거나 업데이트해야 하는 경우
exec_tool을 통해owl.monitor.upsert를 호출합니다. - 외부 이벤트를 전송해야 하는 경우
exec_tool을 통해owl.monitor.receive를 호출합니다.