OWL CLI 도구 목록¶

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

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

도구 범위¶

OWL CLI에서 제공하는 도구는 플랫폼 기능이 업데이트됨에 따라 지속적으로 변경됩니다. 실제로 확인 가능한 도구는 로컬에서 owl sync를 완료한 후 owl list를 통해 반환된 도구 디렉터리를 기준으로 합니다.

현재 문서는 다음 비즈니스 분류를 다룹니다.

권한 유형¶

CLI 사용 규칙¶

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

도구 출력 유형이 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
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

도구 개요¶

Catalog¶

통합 리소스 디렉터리의 엔터티 유형 발견, 엔터티 조회, 엔터티 상세 정보 조회 및 토폴로지 관계 조회에 사용됩니다.

Dashboard¶

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

Data¶

권한 기반 워크스페이스 간 DQL 쿼리는 필요할 때 owl.workspace.data_authorized.list로 대상을 검색한 후 workspace_uuids와 target_region을 전달합니다. 한 번에 하나의 사이트만 쿼리하며 범위를 생략하면 현재 워크스페이스를 쿼리합니다. CLI/MCP 예제와 페이지 처리는 워크스페이스 간 쿼리를 참조하세요.

전체 데이터 조회 및 조회 보조에 사용되며, 로그, 메트릭, RUM, APM, Network, Profile, Billing 및 객체 스토리지로 전송된 데이터를 다룹니다.

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이며, 상태 조회 시마다 새 로컬 데이터 파일이 생성됩니다.

다음 순서에 따라 한 번의 조회를 완료합니다.

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 조회¶

현재 워크스페이스는 직접 쿼리합니다. 동일 조직의 다른 워크스페이스는 UUID를 모를 때만 owl.account.workspace.same_org.list(CLI: owl workspace same-org list)로 검색합니다. 반환된 workspace_uuid를 owl.data.same_org.trace.query에 전달하고, 목록 페이지 처리 전용인 workspace_id는 사용하지 마세요.

• 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¶

오류 센터의 문제 목록 조회와 댓글 추가, 조회 및 업데이트에 사용됩니다.

Event¶

이벤트 센터 목록 조회 및 이벤트 상세 정보 조회에 사용됩니다.

• owl.event.list는 반드시 start_time과 end_time을 제공해야 합니다. status의 선택 가능한 값은 fatal, critical, error, warning 및 nodata이며, limit의 기본값은 20, 최대값은 100입니다. 반환 항목에는 이벤트 차원 태그 필드 df_dimension_tags가 포함될 수 있습니다.
• owl.event.get의 timeRange는 선택적 두 요소 배열 [start, end]이며, 요소는 모두 13자리 밀리초 타임스탬프이고 end는 start보다 커야 합니다. 매개변수 이름은 timeRange이며 time_range로 변경하지 마십시오.

Incident¶

owl.incident.get은 장애 UUID(incident_*)를 받아 상세 정보와 related_event_refs를 반환합니다. 참조는 페이지당 기본 및 최대 100개입니다. page_info.has_more와 next_page_index에 따라 가져온 뒤 장애 UUID가 아닌 이벤트 참조로 owl.event.get을 호출하세요. 제공 가능한 참조 수와 장애에 기록된 이벤트 수는 다를 수 있으므로 누락된 근거를 명시하세요.

Infrastructure¶

인프라스트럭처 객체 목록 및 상세 정보 조회에 사용되며, 호스트, 컨테이너, 프로세스 등 리소스 객체를 다룹니다.

LLM¶

LLM 관측 가능성 애플리케이션 목록 조회에 사용됩니다.

Workspace¶

워크스페이스 간 데이터 쿼리 권한 검색 및 현재 워크스페이스 멤버.

새 workspace 범주에는 owl.workspace.data_authorized.list와 owl.workspace.member.list가 포함됩니다. 이전 member 범주는 제거됩니다. owl.member.list는 동일한 매개변수와 권한 검사를 사용하는 호출 별칭으로 유지되지만 별도 도구로 표시되지 않습니다.

Monitor¶

모니터 목록 조회, 상세 정보 조회, 생성 또는 업데이트 및 외부 이벤트 수신에 사용됩니다.

노트 및 Runbook¶

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

• 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 목록 조회 및 샘플 검증에 사용됩니다.

mdsearch¶

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

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를 호출하여 정식 조회를 실행합니다.

Profiling 분석 유형 문제¶

"profile_id를 확보했으며, 요약 정보를 확인하거나 상세 스택 정보를 파싱하려는" 등의 문제에 적합합니다.

1. 먼저 owl.data.query를 통해 Profiling 데이터 도메인에서 대상 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를 호출합니다.