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 は、クエリ可能なルールを探索し、ルールを通じてオブジェクトストレージに書き込まれたデータをクエリするために使用します。これら 3 つのツールはすべて単一のアトミック呼び出しであり、CLI が自動的にルールを選択したり、タスクをポーリングしたり、次のデータバッチをクエリしたりすることはありません。rule.list と query.create はテキスト結果を直接返します。query.get の outputType は data であり、ステータスクエリのたびに新しいローカルデータファイルが書き込まれます。

以下の順序で 1 回のクエリを実行します。

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 はオプションの 2 要素配列 [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 のうち少なくとも 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. 最初に 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 を呼び出します。