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¶

전체 데이터 쿼리 및 쿼리 보조 기능을 제공하며, 로그, 메트릭, RUM, APM, Network, Profile, Billing 및 객체 스토리지로 전송된 데이터를 포함합니다.

데이터 전송 비동기 쿼리¶

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

owl.data.same_org.trace.query는 trace_id로 현재 또는 동일 조직 워크스페이스의 Trace를 조회하는 전용 도구입니다. 워크스페이스 간 조회 시 먼저 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¶

인시던트 센터의 이슈 목록 조회 및 댓글 추가, 조회, 업데이트에 사용됩니다.

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¶

인시던트 목록, 인시던트 댓글, 작업 기록 및 온콜 일정 조회에 사용됩니다.

Infrastructure¶

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

LLM¶

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

Member¶

워크스페이스 멤버 목록 조회 및 이름, 이메일 키워드 검색에 사용됩니다.

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를 실행하여 대상 네임스페이스를 확인합니다.

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. 먼저 owl.incident.list를 호출하여 인시던트를 조회합니다.

2. incident_uuid를 기반으로 계속 호출:

   • owl.incident_comment.list: 댓글 확인
   • owl.incident_operation.list: 작업 기록 확인
   • 처리 진행 상황을 추가해야 하는 경우 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를 호출합니다.