콘텐츠로 이동

OWL CLI 도구 목록


이 문서에서는 현재 OWL CLI에서 직접 실행할 수 있는 비즈니스 도구 기능을 소개하며, 도구 범위, 권한 유형, CLI 사용 규칙, 도구 요약, 분류별 도구 설명을 포함합니다.

도구의 표시 범위와 실행 결과는 현재 OWL_TOKEN에 해당하는 API Key의 권한에 따라 달라집니다. API Key에 해당 리소스 또는 작업 권한이 없으면 해당 도구 실행이 실패하거나 빈 결과가 반환될 수 있습니다.

주의

이 문서는 owl exec를 통해 직접 호출할 수 있는 비즈니스 도구만 설명하며, owl init, owl login, owl sync, owl list, owl show, owl data list 등 CLI 명령 자체는 포함하지 않습니다.

v1.8.0에서는 필드 검색, 페이지네이션, 노트 expected_etag가 추가되었습니다. 전체 파라미터는 현재 도구 schema를 기준으로 합니다. 업그레이드 순서와 쓰기 복구 규칙은 v1.8.0 업데이트 설명을 참고하세요.

도구 범위

OWL CLI에서 노출되는 도구는 플랫폼 기능에 따라 지속적으로 업데이트됩니다. 실제 표시되는 도구는 로컬에서 owl sync를 완료한 후 owl list를 통해 반환되는 도구 카탈로그를 기준으로 합니다.

이 문서에서는 다음 비즈니스 분류를 다룹니다:

분류 설명
account 동일 조직 워크스페이스 검색
catalog 통합 카탈로그 엔터티 조회, 생성, 수정 및 토폴로지 관계 조회
dashboard 대시보드 생성, 교체 및 상세 정보 조회
data DQL namespace 탐색, 로그/메트릭/RUM/APM/Network/Profile/Billing 데이터 검색, DQL 문서 조회, DQL 검증, 전체 쿼리, 데이터 전송 비동기 쿼리, 동일 조직 교차 워크스페이스 Trace 쿼리 및 프로파일링 분석
errors 오류 센터 문제 조회 및 댓글 관리
event 이벤트 목록 조회 및 이벤트 상세 정보 조회
incident 인시던트 목록 및 상세, 관련 이벤트 참조, 인시던트 댓글, 작업 기록 및 온콜 일정
infrastructure 통합 카탈로그 리소스 조회
llm LLM 관측 가능성 애플리케이션 목록 조회
workspace 교차 워크스페이스 데이터 쿼리 권한 범위 검색, 현재 워크스페이스 멤버 및 팀 조회
mdsearch 통합 문서 검색(검색, 문서 읽기, 디렉터리 탐색)
monitor 모니터 조회, 생성, 업데이트 및 외부 이벤트 수신
nbook_note 일반 노트와 Runbook 조회, 읽기, 생성, 수정 및 삭제
pipeline Pipeline 목록 조회 및 샘플 검증

권한 유형

권한 유형 의미 사용 권장 사항
읽기 전용 조회, 목록, 상세 정보 조회, 샘플 검증 등 워크스페이스 리소스를 수정하지 않는 작업 일상적인 문제 해결 및 자동화된 읽기 전용 실행에 적합합니다
쓰기 생성, 업데이트, 댓글 추가, 외부 이벤트 수신 등 워크스페이스 리소스를 수정하는 작업 프로덕션 환경에서 사용하기 전에 파라미터와 영향 범위를 먼저 확인하는 것이 좋습니다
로컬 보조 로컬 DQL 문서 검색, 로컬 구문 검증 등 워크스페이스 리소스를 수정하지 않는 보조 기능 정식 쿼리 실행 전에 사용하는 것이 적합합니다

CLI 사용 규칙

권한이 부여된 교차 워크스페이스 쿼리에서 대상이 확정되지 않은 경우 먼저 owl.workspace.data_authorized.list를 호출한 다음 workspace_uuids와 target_region을 owl.data.query 또는 owl.data.simple_query_file에 전달합니다. 한 번의 쿼리는 하나의 대상 사이트로 제한되며, 범위 파라미터를 생략하면 현재 워크스페이스를 쿼리합니다. 목록 페이지 번호와 데이터 커서는 각각 처리합니다. 자세한 내용은 교차 워크스페이스 쿼리 설명을 참고하세요.

유형 규칙
도구 동기화 처음 사용하거나 플랫폼 도구가 업데이트된 후에는 먼저 owl sync를 실행합니다
분류 및 도구 탐색 owl category list, owl list, owl list -c <category>를 사용하여 도구 카탈로그를 탐색합니다
도구 정의 확인 실행 전에 owl show <tool name>으로 파라미터 정의를 확인하는 것이 좋습니다
도구 실행 도구 실행 시 항상 owl exec <tool name> [parameters]를 사용합니다
파라미터 전달 --key value, key=value, -p '<json>', --stdin 네 가지 방식을 지원합니다
시간 범위 항상 13자리 밀리초 타임스탬프를 사용합니다
페이지네이션 파라미터 일반적으로 page_size와 page_index를 사용합니다
상세 조회 일반적으로 목록 도구가 반환한 UUID, ID, URN 등의 식별자를 사용하여 추가 조회합니다
데이터 쿼리 먼저 검색 도구를 호출하여 source, field, tag, index를 가져온 후 정식 쿼리를 실행하는 것이 좋습니다
데이터 결과 파일 도구 출력 유형이 data이면 결과가 자동으로 로컬 데이터 디렉터리에 기록되며, owl data list, owl data show <file-id>와 함께 사용하여 확인할 수 있습니다

데이터 결과 파일의 샘플링 필드

도구 출력 유형이 data이면 CLI는 데이터 파일을 기록함과 동시에 실행 결과에 선택적으로 sample 필드를 포함할 수 있습니다:

  • sample: 숫자(부동 소수점)로, 이번 쿼리의 샘플링 비율을 나타냅니다(예: 0.0077은 약 0.77% 샘플링). 백엔드가 샘플링 정보를 반환했거나 데이터 파일 내용에서 샘플링 비율을 파싱할 수 있는 경우에만 나타나며, 샘플링 정보가 없으면 이 필드는 생략됩니다.
  • sample을 확인했다면 결과가 샘플링 데이터를 기반으로 추정된 것이므로, 개수 집계, 합계 등 집계 해석 시 샘플링 비율에 따라 환산한 후 규모를 판단해야 합니다.

자주 사용하는 CLI 명령 예시:

owl sync
owl list
owl list -c data
owl show owl.data.query
owl exec owl.metric.list --mode source --start_time 1792548000000 --end_time 1792551600000
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

도구 요약

도구 세트 도구 기능 권한
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 단일 엔터티와 연결된 토폴로지 관계 조회 읽기 전용
catalog owl.catalog.all_topology_query 전역 토폴로지 그룹화 결과 조회 읽기 전용
dashboard owl.dashboard.create 대시보드 생성 쓰기
dashboard owl.dashboard.replace 기존 대시보드 내용 교체 쓰기
dashboard owl.dashboard.get 대시보드 상세 정보 조회 읽기 전용
data owl.data.show_dql_namespace DQL namespace 목록 및 인덱스 지원 여부 확인 읽기 전용
data owl.data.query 전체 DQL 또는 PromQL 쿼리 실행 읽기 전용
data owl.data.simple_query_file namespace + 시간 범위 등 간소화된 파라미터로 쿼리를 실행하고 데이터 파일로 저장하며, limit 값 범위는 1-10000입니다 읽기 전용
data owl.external_datasource.list 현재 워크스페이스에서 액세스 가능한 외부 데이터 소스 검색 읽기 전용
data owl.external_datasource.query 구성된 외부 데이터 소스에 대해 제한된 읽기 전용 SQL 실행 읽기 전용
data owl.data.same_org.trace.query trace_id로 현재 또는 동일 조직 워크스페이스의 Trace 조회 읽기 전용
data owl.data.search_dql_docs Registry 서버의 DQL 문서 스니펫 검색 읽기 전용
data owl.data.read_dql_docs 문서 참조 및 버전별로 본문을 페이지 단위로 읽기 읽기 전용
data owl.data.check_dql 후보 DQL 문 구문 검증 로컬 보조
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 로그 클러스터(cluster) 비동기 분석 작업 생성 읽기 전용
data owl.logging.cluster_task.get 로그 클러스터 비동기 분석 작업 결과 조회 읽기 전용
data owl.data_forwarding.rule.list 현재 계정에서 쿼리 가능한 데이터 전송 규칙 검색 읽기 전용
data owl.data_forwarding.query.create 오브젝트 스토리지 데이터 전송 비동기 쿼리 작업 생성 읽기 전용
data owl.data_forwarding.query.get 데이터 전송 비동기 작업 상태를 조회하고, 마스킹된 결과를 로컬 데이터 파일에 기록 읽기 전용
data owl.billing.list Billing 쿼리에 사용 가능한 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 구성을 필요에 따라 검색 읽기 전용
data owl.profiling.get_summary 프로파일링 레코드 요약 정보 조회 읽기 전용
data owl.profiling.parse 프로파일링 레코드 상세 내용 분석 읽기 전용
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 또는 경로로 단일 문서 전체 읽기 로컬 보조
mdsearch mdsearch_catalog 통합 문서 라이브러리 디렉터리 구조 탐색 로컬 보조
monitor owl.monitor.list 모니터 목록 조회 읽기 전용
monitor owl.monitor.get 모니터 상세 정보 조회 읽기 전용
monitor owl.monitor.upsert 모니터 생성 또는 업데이트 쓰기
monitor owl.monitor.receive 외부 이벤트 전송 쓰기
nbook_note owl.nbook_note.list 현재 계정에서 볼 수 있는 일반 노트 및 Runbook 기본 정보 조회 읽기 전용
nbook_note owl.nbook_note.get 노트 또는 Runbook 상세 정보 및 Markdown 본문 조회 읽기 전용
nbook_note owl.nbook_note.add 일반 노트 또는 Runbook 생성 쓰기
nbook_note owl.nbook_note.modify 일반 노트 또는 Runbook 수정 쓰기
nbook_note owl.nbook_note.delete 일반 노트 또는 Runbook 삭제 쓰기
pipeline owl.pipeline.list Pipeline 목록 조회 읽기 전용
pipeline owl.pipeline.validate 샘플 데이터로 Pipeline 처리 결과 검증 읽기 전용

Account

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 조회에만 사용하며, 이 목록은 일반 데이터 쿼리 권한을 부여하지 않습니다.

도구 이름 기능 질문 예시 주요 파라미터 권한
owl.account.workspace.same_org.list 현재 워크스페이스와 동일 조직의 워크스페이스를 workspace id 내림차순으로 나열 현재 워크스페이스와 동일 조직의 워크스페이스 나열 workspace_uuids, page_size, before_workspace_id 읽기 전용
owl exec owl.account.workspace.same_org.list -p '{"page_size":20}'

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 읽기 전용
owl.catalog.all_topology_query 전역 토폴로지 그룹화 결과 조회 현재 통합 카탈로그의 전역 토폴로지 구조 조회 groupByFields 읽기 전용

entity_query에는 반드시 entity_type을 지정해야 합니다. name은 정확히 일치하는 항목을 찾는 데 사용하고, search는 이름, 표시 이름 또는 URN을 퍼지 검색하는 데 사용하며, 두 파라미터를 동시에 사용할 수 없습니다. 전체 urn 또는 filters로 범위를 좁힐 수도 있습니다.

엔터티 생성 및 수정

  1. owl.catalog.entity_type_query를 호출하여 사용 가능한 유형과 해당 유형의 필드 요구 사항을 확인합니다. 소속 팀을 설정해야 하는 경우 먼저 owl.workspace.member.group_list로 팀 이름을 찾습니다.
  2. owl.catalog.entity_query를 호출하여 대상을 찾고 중복 생성을 방지합니다. 기존 엔터티를 수정할 때는 조회에서 반환된 전체 urn을 사용하고 owl.catalog.entity_get으로 현재 구성을 확인합니다.
  3. 기록할 내용을 확인한 후 owl.catalog.entity_create 또는 owl.catalog.entity_modify를 호출합니다. 완료 후 플랫폼의 통합 카탈로그로 돌아가 엔터티를 확인할 수 있습니다.

생성 시에는 request_id, entity_type, name을 반드시 제공해야 하며, 유형 요구 사항에 따라 attributes를 보완해야 합니다. 수정 시에는 request_id와 urn을 반드시 제공해야 하며, 동시에 수정할 항목을 하나 이상 지정해야 합니다. request_id는 이번 작업을 식별하는 UUID를 사용합니다. display_name은 표시 이름이며, 수정 도구는 엔터티 이름이나 유형 변경을 지원하지 않습니다. 제출되지 않은 속성과 관계는 유지되며, 소속 팀 owner는 팀 이름을 사용합니다.

의존성, 컴포넌트 등의 관계를 수정할 때는 제출하는 관계 필드에 relation_modes를 설정합니다. add는 추가, replace는 전체 교체를 의미하며, replace와 빈 배열을 함께 사용하면 비우기를 의미합니다. 엔터티 유형에서 지원하는 필드와 관계만 제출하세요.

결과가 확인 대기 상태를 나타내면 원래 request_id와 파라미터를 유지하고 반환된 안내에 따라 확인하세요. UUID를 바꿔 생성이나 수정을 반복하지 마세요. 결과에서 감사 상태가 불확실하다고 나타나면 먼저 관리자에게 문의하여 확인해야 합니다.

owl sync
owl show owl.catalog.entity_create
owl show owl.catalog.entity_modify
owl exec owl.catalog.entity_query -p '{"entity_type":"service","name":"checkout-api"}'

Dashboard

대시보드 생성, 교체 및 상세 정보 조회에 사용합니다.

도구 이름 기능 사용 예시 주요 파라미터 권한
owl.dashboard.create 대시보드 생성 “APM Overview”라는 이름의 대시보드 생성 name, dashboard_json 쓰기
owl.dashboard.replace 기존 대시보드 내용 교체 새 dashboard_json으로 지정된 대시보드 교체 dashboard_uuid, dashboard_json 쓰기
owl.dashboard.get 대시보드 상세 정보 조회 이 대시보드 UUID에 해당하는 전체 구성 조회 dashboard_uuid 읽기 전용

Data

v1.6.0에서는 13자리 정수 밀리초 타임스탬프를 일괄 검증하며, 종료 시간이 시작 시간보다 커야 합니다. 쌍으로 제공해야 하는 파라미터는 한쪽만 전달할 수 없습니다. 필수 요구 사항과 최대 범위는 각 도구 schema를 기준으로 합니다. owl.data.query의 시간 범위는 최대 7일입니다.

owl.data.query의 DQL은 인라인 시간 창을 생략할 수 있으며, start_time / end_time으로 쿼리 창을 제공합니다. 인라인 절대 창은 외부 창과 일치해야 하며, 상대 창은 거부됩니다. PromQL 범위 선택자는 룩백 기간을 나타내며 쿼리 창으로 사용되지 않고 DQL 검증에도 포함되지 않습니다. Registry에는 사용 가능한 dqlcheck가 필요합니다. 검증을 사용할 수 없으면 DQL 쿼리를 실행하지 않습니다. 요청 창은 백엔드의 실제 실행 시간 범위나 결과가 커버하는 시간 범위와 동일하지 않습니다.

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에 그대로 전달합니다.

전체 데이터 쿼리 및 쿼리 보조에 사용하며, 로그, 메트릭, RUM, APM, Network, Profile, Billing, 구성된 외부 데이터 소스, 오브젝트 스토리지로 전송된 데이터를 포함합니다.

외부 데이터 소스 쿼리는 먼저 list로 datasource_id 또는 이름을 기준으로 데이터 소스를 검색한 다음, 유일한 결과의 datasource_uuid를 query에 그대로 전달해야 합니다. datasource_id는 UUID를 대체할 수 없습니다. 원시 행 쿼리에는 결정적인 ORDER BY와 SQL LIMIT을 포함해야 하며, truncated=true는 일부 결과만 있음을 의미합니다. 문 유형은 list가 반환하는 capabilities.statement_types를 기준으로 해야 합니다.

도구 이름 기능 사용 예시 주요 파라미터 권한
owl.data.show_dql_namespace 현재 지원되는 DQL namespace 목록을 나열하고 index 지원 여부를 표시 현재 어떤 DQL namespace를 지원하는지 확인 없음 읽기 전용
owl.data.query 전체 DQL 또는 PromQL 쿼리 실행 최근 1시간 nginx 로그의 500 오류 조회 dql_namespace, start_time, end_time, query_mode, query_text, source, select, index, workspace_uuids, target_region 읽기 전용
owl.data.simple_query_file namespace + 시간 범위 등 간소화된 파라미터로 쿼리를 실행하고 결과를 데이터 파일로 저장 전체 DQL을 직접 작성하지 않고 namespace와 필터 조건으로 로그를 조회하여 파일로 저장 namespace, start_time, end_time, index, source, select_clause, where_clause, group_by_clause, limit, workspace_uuids, target_region 읽기 전용
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.data.search_dql_docs Registry 서버의 DQL 문서 스니펫 검색 Registry 서버의 DQL 문서 스니펫 검색 query, limit 읽기 전용
owl.data.read_dql_docs 문서 참조 및 버전별로 본문을 페이지 단위로 읽기 문서 참조 및 버전별로 본문을 페이지 단위로 읽기 document_id, version, start_line, line_count 읽기 전용
owl.data.check_dql 후보 DQL 문이 구문에 맞는지 검증 직접 작성한 DQL이 올바른지 검증 query_text, start_time, end_time 로컬 보조
owl.metric.list 메트릭 쿼리에 사용 가능한 source, 필드 또는 태그 키 검색 메트릭 영역에서 사용 가능한 measurement 또는 tag 나열 mode, source, start_time, end_time 읽기 전용
owl.rum.list RUM 쿼리에 사용 가능한 source 또는 필드 검색 RUM 영역에서 사용 가능한 필드 나열 mode, source, start_time, end_time 읽기 전용
owl.apm.list APM 쿼리에 사용 가능한 source 또는 필드 검색 APM 영역에서 사용 가능한 source 조회 mode, source, start_time, end_time 읽기 전용
owl.network.list Network 쿼리에 사용 가능한 source 또는 필드 검색 Network 영역에서 사용 가능한 필드 나열 mode, source, start_time, end_time 읽기 전용
owl.profile.list Profile 쿼리에 사용 가능한 source 또는 필드 검색 Profile 영역에서 사용 가능한 source 확인 mode, source, start_time, end_time 읽기 전용
owl.logging.list 로그 쿼리에 사용 가능한 source 또는 필드 검색 로그 영역에서 사용 가능한 source 나열 mode, source, start_time, end_time 읽기 전용
owl.logging.cluster_task.create 로그 클러스터(cluster) 비동기 분석 작업을 생성하고, 유사한 로그 또는 필드 기준으로 그룹화 최근 일정 기간의 로그를 지정된 필드 기준으로 클러스터링하고 task_id 반환 timeRange, analysisField, namespace, conditions, query, indexes 읽기 전용
owl.logging.cluster_task.get 로그 클러스터 비동기 분석 작업 결과 조회 cluster_task.create가 반환한 task_id로 클러스터 결과 가져오기(task_status=ok는 완료를 의미) task_id 읽기 전용
owl.data_forwarding.rule.list 현재 계정에서 읽을 수 있는 데이터 전송 규칙을 나열하며, 기본적으로 AIAPI를 통해 쿼리 가능한 규칙만 반환 쿼리 생성 전에 정확한 rule_name을 찾고 규칙 쿼리 가능 여부 확인 search, data_type, store_type, queryable_only, page_index, page_size 읽기 전용
owl.data_forwarding.query.create 지정된 데이터 전송 규칙에 대해 오브젝트 스토리지 비동기 쿼리 작업을 한 번 생성 데이터 전송 규칙 forward-rule이 지정된 시간 범위에 전송한 오류 레코드를 조회하고 task_id 반환 rule_name, start_time, end_time, search, page_size, token 읽기 전용
owl.data_forwarding.query.get 데이터 전송 비동기 작업 상태를 조회하고, 워크스페이스에서 마스킹된 응답을 로컬 데이터 파일에 기록 create가 반환한 task_id로 결과 파일을 가져온 다음, 그 안의 task_status, items, next_token 확인 task_id 읽기 전용
owl.billing.list Billing 쿼리에 사용 가능한 source 또는 필드 검색 Billing 영역에서 사용 가능한 필드 나열 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.profiling.get_summary 프로파일링 레코드 요약 정보 조회 이 profile_id의 요약 정보 확인 profile_id, timeRange 읽기 전용
owl.profiling.parse 프로파일링 레코드 상세 내용 분석 이 프로파일링 레코드의 상세 스택 정보 분석 profile_id, language, type, profile_start, profile_end 읽기 전용

owl.data.simple_query_file의 limit은 선택적 정수이며 값 범위는 1에서 10000입니다. 생략하면 백엔드에서 기본값을 사용합니다. 범위를 벗어난 값은 요청 실행 전에 거부됩니다.

데이터 전송 비동기 쿼리

owl.data_forwarding.rule.list, owl.data_forwarding.query.create, owl.data_forwarding.query.get는 쿼리 가능한 규칙을 검색하고, 규칙을 통해 오브젝트 스토리지에 이미 기록된 데이터를 쿼리하는 데 사용합니다. 이 세 도구는 모두 단일 원자 호출이며, CLI가 규칙을 자동 선택하거나 작업을 폴링하거나 다음 데이터 배치를 계속 쿼리하지 않습니다. rule.list와 query.create는 텍스트 결과를 직접 반환합니다. query.get의 outputType은 data이며, 상태를 조회할 때마다 새로운 로컬 데이터 파일이 기록됩니다.

OWL CLI에서만 지원

데이터 전송 쿼리 도구는 OWL CLI를 통해서만 제공되며, Web의 Obsy Copilot 또는 MCP 도구 카탈로그에는 나타나지 않습니다.

다음 순서로 한 번의 쿼리를 완료합니다:

  1. 사용자가 정확한 규칙 이름을 제공하지 않았거나 규칙의 쿼리 가능 여부가 아직 확인되지 않은 경우 먼저 owl.data_forwarding.rule.list를 호출합니다. 쿼리 시나리오에서는 queryable_only=true를 유지하고, queryable=true인 결과에서 rule_name을 선택합니다. rule_uuid를 create에 전달하지 마세요.
  2. owl.data_forwarding.query.create를 호출하여 선택한 rule_name, 쿼리 시간 범위, 필터 조건을 그대로 전달하고 task_id를 받습니다.
  3. 해당 task_id로 owl.data_forwarding.query.get를 호출합니다. 실행 결과의 파일 객체에는 데이터 파일 ID가 포함되지 않습니다. owl data list -f json을 실행하여 해당 항목을 찾고 files[].id를 그대로 저장한 다음 owl data show <file-id>를 실행합니다. 경로를 기반으로 ID를 유도하거나 추측하지 마세요.
  4. 파일의 task_status를 확인합니다. 값이 created 또는 running이면 작업이 아직 완료되지 않은 것입니다. items가 비어 있더라도 최종 결과로 간주해서는 안 되며, 잠시 후 동일한 task_id로 계속 get을 호출한 다음 데이터 파일 목록 단계를 반복하여 최신 상태를 확인해야 합니다.
  5. task_status가 completed 또는 failed이면 폴링을 중지합니다. completed이면 마스킹된 items를 읽고, failed이면 반환된 실패 정보를 바탕으로 원인을 조사합니다.
  6. completed이고 next_token이 비어 있지 않으면 create를 다시 호출하여 다음 배치를 쿼리합니다. 원래 rule_name, start_time, end_time, search, page_size를 유지해야 하며, next_token을 token으로 전달합니다. 새로운 create는 새로운 task_id를 반환합니다.

쿼리 가능한 규칙 검색:

owl exec owl.data_forwarding.rule.list -p '{
  "queryable_only": true,
  "page_index": 1,
  "page_size": 20
}'

첫 번째 쿼리 작업 생성:

owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20
}'

작업 상태 및 결과 조회:

owl exec owl.data_forwarding.query.get -p '{"task_id":"task_xxx"}'
owl data list -f json
owl data show <保存的文件-ID>

다음 배치를 쿼리할 때 원래 쿼리 파라미터를 재사용하고 next_token을 전달합니다:

owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20,
  "token": "next_xxx"
}'

파라미터 및 제한 사항:

  • rule.list의 기본값은 queryable_only=true이며, 쿼리 가능한 규칙만 반환합니다. false로 설정하면 쿼리를 지원하지 않는 규칙도 반환되며, queryable과 unsupported_reason으로 원인을 판단해야 하고, 이러한 규칙에 대해 create를 계속 호출하여 쿼리할 수 없습니다.
  • rule.list는 search로 규칙 이름을 퍼지 검색할 수 있으며, data_type 또는 store_type으로 필터링할 수도 있습니다. 페이지네이션 범위는 page_index >= 1, page_size 1에서 100입니다.
  • rule_name은 rule.list가 반환한 정확한 값을 사용해야 하며, rule_uuid로 대체할 수 없습니다. 데이터 유형과 오브젝트 스토리지 구성은 백엔드에서 규칙에 따라 결정합니다.
  • start_time과 end_time은 13자리 밀리초 타임스탬프이며, end_time은 start_time보다 커야 합니다.
  • 쿼리 기간 상한은 워크스페이스 구성에 따라 결정되며 기본값은 24시간입니다. create 응답의 query_time_limit_hours는 현재 실제 적용되는 상한입니다.
  • search.conditions[].logic은 match와 notMatch만 지원합니다. 여러 조건은 search.operator의 and 또는 or로 결합합니다.
  • page_size 범위는 1에서 1000이며 기본값은 20입니다.
  • query.get은 전체 결과를 CLI에 직접 출력하지 않으며, 반환되는 파일 정보에는 ID가 포함되지 않습니다. owl data list -f json을 실행하여 해당 항목의 files[].id를 그대로 저장한 다음 owl data show <file-id>를 통해 작업 상태와 마스킹된 결과를 확인해야 합니다.
  • DF-API-KEY는 CLI에서 자동으로 주입되며 도구 파라미터로 전달해서는 안 됩니다. 무료 플랜 워크스페이스에서는 이 쿼리를 지원하지 않습니다.
  • S3, OSS, OBS, GCS 및 TOS 표준 스토리지를 지원합니다. Kafka, 플랫폼 내장 스토리지, 콜드 스토리지 및 아카이브 데이터는 지원하지 않습니다.

동일 조직 교차 워크스페이스 Trace 쿼리

owl.data.same_org.trace.query는 trace_id로 현재 또는 동일 조직 워크스페이스의 Trace를 조회하는 전용 도구입니다. 현재 워크스페이스의 경우 목록을 조회하지 않고 직접 호출합니다. 다른 동일 조직 워크스페이스를 쿼리해야 하고 UUID가 확정되지 않은 경우 owl workspace same-org list를 실행하여 후보 워크스페이스를 가져온 후 쿼리합니다:

  • trace_id는 필수 파라미터이며, 서버에서 해당 조건을 강제로 추가하므로 where_clause에 중복으로 추가하지 마세요.
  • workspace_uuids는 선택적 문자열 배열이며, 목록 결과의 workspace_uuid 값을 사용합니다. workspace_id는 목록 페이지네이션에만 사용되며 쿼리에는 사용할 수 없습니다.
  • workspace_uuids를 생략하거나 빈 배열로 전달하면 현재 API Key가 속한 워크스페이스만 쿼리합니다.
  • 동일 조직 교차 워크스페이스 쿼리 기능이 비활성화된 경우 현재 워크스페이스만 쿼리할 수 있습니다. 다른 워크스페이스 UUID를 전달하면 파라미터 오류가 반환됩니다.
  • where_clause에는 추가 DQL 조건 조각만 전달하며, 외부 중괄호는 포함하지 않습니다.
  • start_time, end_time은 13자리 밀리초 타임스탬프를 사용합니다. source와 limit으로 쿼리 범위를 좁힐 수도 있습니다.
  • 반환 내용은 원본 DQL 쿼리 결과 구조를 유지합니다. 교차 워크스페이스 Trace 쿼리에서는 owl.data.query 또는 owl.data.simple_query_file로 대체하지 마세요.
owl workspace same-org list
owl exec owl.data.same_org.trace.query -p '{"trace_id":"TRACE-XXXX","workspace_uuids":["wksp_xxx"]}'

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는 여전히 모호함이 있음을 의미하며, 함께 제공된 최신 후보 상세 정보를 유일한 확인 결과로 사용할 수 없습니다.

owl exec owl.event.resolve -p '{"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.get 모니터 상세 정보 조회 이 모니터 규칙의 전체 구성 조회 rule_uuid 읽기 전용
owl.monitor.upsert 모니터 생성 또는 기존 모니터 업데이트 새 외부 이벤트 모니터 생성 json_script, rule_uuid, status, secret, alert_policy_uuids, tags 쓰기
owl.monitor.receive 수신 엔드포인트로 외부 이벤트 전송 이 모니터에 테스트 이벤트 전송 event, target, monitor, extra_data 쓰기

노트 및 Runbook

현재 API Key 계정에서 볼 수 있는 일반 노트와 Runbook을 관리하는 데 사용합니다. 일반 노트는 결론과 참고 정보를 기록하는 데 적합하고, Runbook은 반복 사용 가능한 운영 절차를 저장하는 데 적합합니다.

도구 이름 기능 사용 예시 주요 파라미터 권한
owl.nbook_note.list 표시되는 노트 및 Runbook 기본 정보를 조회하며 Markdown 본문은 반환하지 않음 유형, 제목, 본문 또는 태그로 내용 필터링 page_index, page_size, search, tags, tagkv_query, type 읽기 전용
owl.nbook_note.get note_uuid로 노트 또는 Runbook 상세 정보 및 Markdown 본문 조회 지정된 내용의 전체 본문 읽기 note_uuid 읽기 전용
owl.nbook_note.add 일반 노트 또는 Runbook을 생성하고 기본 정보 반환 태그가 있는 Markdown Runbook 생성 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.list의 type 선택 가능한 값은 normal과 runbook이며, 생략하면 두 유형 모두 반환합니다.
  • owl.nbook_note.get은 Markdown 본문 content를 반환하는 유일한 도구이지만 path, etag, version은 반환하지 않습니다. list, add, modify는 제목, 유형, 태그 등 기본 정보만 반환하며 content, path, ETag 또는 버전 정보도 반환하지 않습니다. delete는 삭제 작업의 간결한 결과를 반환합니다.
  • owl.nbook_note.add에는 title과 content를 반드시 제공해야 합니다. type 선택 가능한 값은 normal과 runbook이며, 생략하면 일반 노트를 생성합니다. 이 도구는 path를 받지 않습니다. created_source는 서버에서 ai로 고정되며, 생성 계정은 현재 API Key에서 가져옵니다.
  • owl.nbook_note.modify는 note_uuid 외에 title, content, tags, tag_kv 중 하나 이상을 제공해야 합니다. content를 생략하면 원래 본문을 유지합니다.
  • 콘텐츠 유형은 생성 후 수정할 수 없습니다. get, modify, delete는 모두 type을 받지 않습니다. 유형을 변경해야 하는 경우 대상 유형으로 다시 생성하세요.
  • 조회, 수정, 삭제에는 모두 목록에서 반환된 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

통합 문서 라이브러리 검색, 단일 문서 읽기, 디렉터리 탐색에 사용하며, 중국어, 영어 및 혼합 언어 쿼리를 지원합니다.

도구 이름 기능 사용 예시 주요 파라미터 권한
mdsearch_search 통합 문서 라이브러리를 검색하고 정렬된 후보 문서 반환 특정 통합의 연동 문서 검색 q, top, path_prefix, tags, mode, sort 로컬 보조
mdsearch_document id 또는 경로로 단일 문서 전체 읽기 후보 결과에서 특정 문서의 전체 내용 읽기 id, meta 로컬 보조
mdsearch_catalog 통합 문서 라이브러리의 최상위 디렉터리와 대표 문서 탐색 문서 라이브러리의 전체 구조 파악 없음 로컬 보조

CLI 사용 경로

데이터 쿼리 관련 문제

“메트릭, 로그, RUM, APM, Network, Profile, Billing 데이터 쿼리” 등의 문제에 적용됩니다.

  1. 먼저 owl.data.show_dql_namespace를 실행하여 대상 namespace를 확인합니다.
  2. 데이터 영역별로 검색 도구를 호출합니다:

    • 메트릭: owl.metric.list
    • RUM: owl.rum.list
    • APM: owl.apm.list
    • Network: owl.network.list
    • Profile: owl.profile.list
    • Logging: owl.logging.list
    • Billing: owl.billing.list
    • 로그 인덱스: owl.log_index.list
    • 필드 카탈로그: owl.field_schema.get
  3. DQL 구문을 확인해야 할 때는 먼저 owl.data.search_dql_docs를 호출하여 문서를 검색합니다.

  4. 전체 DQL을 직접 작성한 후 먼저 owl.data.check_dql을 호출하여 로컬 검증을 수행합니다.
  5. 마지막으로 owl.data.query를 호출하여 정식 쿼리를 실행합니다.

프로파일링 분석 관련 문제

“profile_id를 확보했고 요약을 확인하거나 상세 스택 정보를 분석하려는 경우” 등의 문제에 적용됩니다.

  1. 먼저 owl.data.query를 통해 프로파일링 데이터 영역에서 대상 profile_id를 찾습니다.
  2. owl.profiling.get_summary를 호출하여 요약 정보를 가져옵니다.
  3. 요약 결과의 language, type, profile_start, profile_end를 재사용한 다음 owl.profiling.parse를 호출하여 상세 내용을 분석합니다.

인시던트 문제 해결 관련 문제

“인시던트 조회, 처리 과정 추적, 댓글 추가” 등의 문제에 적용됩니다.

  1. 인시던트 UUID를 알고 있으면 owl.incident.get을 호출합니다. 대상이 확정되지 않았으면 먼저 owl.incident.list를 호출합니다.
  2. 반환된 페이지네이션 정보에 따라 모든 관련 이벤트 참조를 읽은 다음 owl.event.get을 호출하여 이벤트 내용을 가져옵니다.
  3. owl.incident_comment.list로 댓글을 확인하고 owl.incident_operation.list로 작업 기록을 확인합니다.
  4. 처리 진행 상황을 추가해야 할 때 owl.incident_comment.add를 호출합니다.

대시보드 관리 관련 문제

“대시보드 생성, 대시보드 내용 교체, 기존 대시보드 구성 확인” 등의 문제에 적용됩니다.

  1. 새 대시보드를 생성할 때 owl.dashboard.create를 호출합니다.
  2. 기존 대시보드를 교체할 때 owl.dashboard.replace를 호출합니다.
  3. 현재 구성을 확인해야 할 때 owl.dashboard.get을 호출합니다.

노트 및 Runbook 관리 관련 문제

“일반 노트와 Runbook 검색, 읽기, 생성, 수정 또는 삭제” 등의 문제에 적용됩니다.

  1. 먼저 owl.nbook_note.list를 호출하여 내용을 검색하고 note_uuid를 얻습니다. 범위를 좁혀야 할 때는 type=normal 또는 type=runbook으로 필터링합니다.
  2. Markdown 본문을 읽어야 할 때 owl.nbook_note.get을 호출합니다.
  3. 노트를 생성할 때 owl.nbook_note.add를 호출하며, type으로 normal 또는 runbook을 생성할 수 있습니다. 업데이트할 때는 owl.nbook_note.modify를 호출하며, 기존 노트의 유형은 수정할 수 없습니다.
  4. 삭제할 때 owl.nbook_note.delete를 호출하며, 쓰기 작업을 실행하기 전에 대상 노트 또는 Runbook과 영향 범위를 확인해야 합니다.

모니터 관리 관련 문제

“모니터 조회, 모니터 생성, 모니터 업데이트, 테스트 이벤트 전송” 등의 문제에 적용됩니다.

  1. 먼저 owl.monitor.list를 호출하여 대상 모니터를 탐색합니다.
  2. 상세 정보가 필요하면 owl.monitor.get을 호출합니다.
  3. 생성 또는 업데이트 시 owl.monitor.upsert를 호출합니다.
  4. 외부 이벤트를 전송하여 수신 경로를 검증해야 할 때 owl.monitor.receive를 호출합니다.

DQL 문서 검색 및 본문 읽기

owl.data.search_dql_docs는 Registry 서버에서 실행되며, results의 스니펫, document_id, version, read_reference를 반환합니다. references_dir는 호환성을 위해 유지되는 서버 측 진단 경로이며 Agent의 로컬 디렉터리가 아니므로 read_file, cat, grep에 전달하지 마세요.

owl exec owl.data.search_dql_docs -p '{"query":"BY host","limit":1}' -f json

선택한 결과의 read_reference.arguments를 JSON 파라미터로 read_reference.tool에 그대로 전달합니다. CLI에서는 owl exec owl.data.read_dql_docs --stdin -f json을 사용할 수 있습니다. 서버 경로에서 document_id를 직접 구성하지 마세요. 검색 및 읽기 도구가 반환하는 .output은 JSON 텍스트이며, 그 자체에는 내부 success 필드가 없습니다.

읽기 파라미터는 document_id, 반환된 version, start_line(1부터 시작), line_count(기본값 80, 최대 200)입니다. 본문은 content에 있으며, 페이지당 최대 65536 UTF-8 바이트입니다. 후속 내용이 필요하고 has_more=true이면 동일한 ID/version을 유지하고 start_line을 next_start_line으로 설정하여 필요한 섹션이 완전해지거나 has_more=false가 될 때까지 진행합니다. 여기서는 줄 단위로 페이지네이션하며, 파일 읽기의 next_offset은 사용하지 않습니다.

document.version_changed가 발생하면 다시 검색하고 새 참조를 사용하세요. version을 생략하여 검증을 우회하거나 서로 다른 버전의 페이지를 혼합하지 마세요. 빈 results는 일치하는 스니펫이 없음만 의미합니다. 이 도구는 경로 범위를 벗어난 접근, 심볼릭 링크, Markdown이 아니거나 UTF-8이 아닌 파일, 4 MiB를 초과하는 문서, 65536바이트를 초과하는 단일 행을 거부합니다. 이 기능은 CLI 문서 보조 도구에 속하며 모든 MCP 노출 모드에서 표시된다고 보장하지 않습니다.

문서 평가

이 페이지가 도움이 되었나요?