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 を渡します。1 回のクエリは 1 サイトに限定し、範囲パラメータを省略すると現在のワークスペースをクエリします。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 は、クエリ可能なルールを検出し、ルールを介してオブジェクトストレージに書き込まれたデータをクエリするために使用されます。これらの 3 つのツールはすべて単一のアトミック呼び出しであり、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 はオプションの 2 要素配列 [start, end] で、要素は 13 桁のミリ秒タイムスタンプであり、end は start より大きくなければなりません。パラメータ名は timeRange で、time_range に書き換えないでください。

Incident¶

owl.incident.get はインシデント UUID（incident_*）を受け取り、詳細と related_event_refs を返します。参照は 1 ページあたりデフォルトおよび最大 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 のうち少なくとも 1 つを指定する必要があります。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 を呼び出します。