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 クエリ、Profiling 解析 |
errors |
エラーセンターの Issue クエリとコメント管理 |
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 に渡します。1 回のクエリは 1 つの対象サイト内に制限され、範囲パラメータを省略した場合は現在のワークスペースがクエリされます。一覧のページ番号とデータカーソルは別々に処理します。詳細はクロスワークスペースクエリの説明を参照してください。
| タイプ | 規約 |
|---|---|
| ツール同期 | 初回使用時またはプラットフォームツールの更新後は、先に 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 の 4 方式をサポート |
| 時間範囲 | 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 |
Profiling レコードのサマリー情報をクエリ | 読み取り専用 |
data |
owl.profiling.parse |
Profiling レコードの詳細内容を解析 | 読み取り専用 |
errors |
owl.errors.list |
エラーセンターの Issue 一覧をクエリ | 読み取り専用 |
errors |
owl.errors.comment.add |
エラー Issue にコメントを追加 | 書き込み |
errors |
owl.errors.comment.list |
エラー Issue のコメント一覧をクエリ | 読み取り専用 |
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 |
読み取り専用 |
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 で範囲を絞り込むこともできます。
エンティティの作成と変更¶
owl.catalog.entity_type_queryを呼び出し、使用可能なタイプとそのタイプのフィールド要件を確認します。所属チームを設定する必要がある場合は、先にowl.workspace.member.group_listでチーム名を検索します。owl.catalog.entity_queryを呼び出して対象を検索し、重複作成を避けます。既存エンティティを変更する場合は、クエリが返した完全なurnを使用し、owl.catalog.entity_getで現在の設定を確認します。- 書き込む内容を確認した後、
owl.catalog.entity_createまたはowl.catalog.entity_modifyを呼び出します。完了後、プラットフォームの統合カタログに戻ってエンティティを確認できます。
作成時は request_id、entity_type、name を必ず指定し、タイプの要件に応じて attributes を補完します。変更時は request_id と urn を必ず指定し、同時に変更する内容を少なくとも 1 つ指定します。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 |
指定したデータ転送ルールに対してオブジェクトストレージの非同期クエリタスクを 1 回作成 | データ転送ルール 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 |
Profiling レコードのサマリー情報をクエリ | この profile_id のサマリー情報を表示 |
profile_id、timeRange |
読み取り専用 |
owl.profiling.parse |
Profiling レコードの詳細内容を解析 | この Profiling レコードの詳細なスタック情報を解析 | 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 は、クエリ可能なルールを検出し、ルールによってオブジェクトストレージに書き込まれたデータをクエリするために使用します。これら 3 つのツールは単一のアトミック呼び出しであり、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に渡さないでください。 owl.data_forwarding.query.createを呼び出し、選択したrule_name、クエリ時間範囲、フィルター条件をそのまま渡してtask_idを取得します。- その
task_idを使用してowl.data_forwarding.query.getを呼び出します。実行結果のファイルオブジェクトにはデータファイル ID が含まれません。owl data list -f jsonを実行して対応するエントリを見つけ、files[].idをそのまま保存し、owl data show <file-id>を実行します。パスから ID を導出したり推測したりしないでください。 - ファイル内の
task_statusを確認します。値がcreatedまたはrunningの場合、タスクはまだ完了していません。itemsが空でも最終結果と見なしてはいけません。後で同じtask_idを使用してgetを呼び出し、その後データファイル一覧の手順を繰り返して最新状態を確認します。 task_statusがcompletedまたはfailedの場合はポーリングを停止します。completedの場合はマスキング済みのitemsを読み取ります。failedの場合は返された失敗情報に基づいて調査します。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¶
エラーセンターの Issue 一覧クエリ、およびコメントの追加、クエリ、更新に使用します。
| ツール名 | 機能 | 使用例 | 主なパラメータ | 権限 |
|---|---|---|---|---|
owl.errors.list |
エラーセンターの Issue 一覧をクエリ | 直近 24 時間のエラー Issue 一覧をクエリ | start_time、end_time、page_size、page_index、conditions、assigner、issue_status |
読み取り専用 |
owl.errors.comment.add |
エラー Issue にコメントを追加 | このエラー Issue に調査コメントを追加 | issue_id、comment、attachment_uuids、extend |
書き込み |
owl.errors.comment.list |
エラー Issue のコメント一覧をクエリ | このエラー Issue のコメント記録を表示 | 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 を返します。関連参照は 1 ページあたりデフォルトおよび上限が 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のうち少なくとも 1 つを指定する必要があります。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 またはパスで単一ドキュメントの全文を読み取る |
候補結果のうち 1 篇のドキュメントの完全な内容を読み取る | id、meta |
ローカル補助 |
mdsearch_catalog |
統合ドキュメントライブラリのトップレベルディレクトリと代表的なドキュメントを閲覧 | ドキュメントライブラリ全体の構造を把握 | なし | ローカル補助 |
CLI の使用フロー¶
データクエリ系の質問¶
「メトリクス、ログ、RUM、APM、Network、Profile、Billing データをクエリする」などの質問に適しています。
- まず
owl.data.show_dql_namespaceを実行して対象 namespace を確認します。 -
データドメインに応じて検出ツールを呼び出します:
- メトリクス:
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
- メトリクス:
-
DQL 構文を確認する必要がある場合は、先に
owl.data.search_dql_docsを呼び出してドキュメントを検索します。 - 完全な DQL を手書きした後、先に
owl.data.check_dqlを呼び出してローカル検証を行います。 - 最後に
owl.data.queryを呼び出して正式なクエリを実行します。
Profiling 分析系の質問¶
「profile_id を取得済みで、サマリーを確認したい、または詳細なスタック情報を解析したい」などの質問に適しています。
- まず
owl.data.queryを通じて Profiling データドメインで対象のprofile_idを特定します。 owl.profiling.get_summaryを呼び出してサマリー情報を取得します。- サマリー結果の
language、type、profile_start、profile_endを再利用し、owl.profiling.parseを呼び出して詳細内容を解析します。
インシデント調査系の質問¶
「インシデントをクエリする、処理過程を追跡する、コメントを追加する」などの質問に適しています。
- インシデント UUID が既知の場合は
owl.incident.getを呼び出します。対象が未確定の場合は先にowl.incident.listを呼び出します。 - 返されたページング情報に従ってすべての関連イベント参照を読み取り、その後
owl.event.getを呼び出してイベント内容を取得します。 owl.incident_comment.listでコメントを確認し、owl.incident_operation.listで操作記録を確認します。- 処理進捗を追加する必要がある場合は、
owl.incident_comment.addを呼び出します。
ダッシュボード管理系の質問¶
「ダッシュボードを作成する、ダッシュボード内容を置換する、既存のダッシュボード設定を確認する」などの質問に適しています。
- 新しいダッシュボードを作成する場合は
owl.dashboard.createを呼び出します。 - 既存のダッシュボードを置換する場合は
owl.dashboard.replaceを呼び出します。 - 現在の設定を確認する必要がある場合は
owl.dashboard.getを呼び出します。
ノートと Runbook 管理系の質問¶
「通常ノートと Runbook を検索、読み取り、作成、変更、削除する」などの質問に適しています。
- まず
owl.nbook_note.listを呼び出して内容を検索し、note_uuidを取得します。範囲を絞り込む必要がある場合は、type=normalまたはtype=runbookでフィルターします。 - Markdown 本文を読み取る必要がある場合は、
owl.nbook_note.getを呼び出します。 - ノートを作成する場合は
owl.nbook_note.addを呼び出し、typeでnormalまたはrunbookを作成できます。更新する場合はowl.nbook_note.modifyを呼び出します。既存ノートのタイプは変更できません。 - 削除する場合は
owl.nbook_note.deleteを呼び出します。書き込み操作を実行する前に、対象のノートまたは Runbook とその影響範囲を確認する必要があります。
モニター管理系の質問¶
「モニターを表示する、モニターを作成する、モニターを更新する、テストイベントを送信する」などの質問に適しています。
- まず
owl.monitor.listを呼び出して対象モニターを閲覧します。 - 詳細が必要な場合は
owl.monitor.getを呼び出します。 - 作成または更新する場合は
owl.monitor.upsertを呼び出します。 - 外部イベントを送信して受信経路を検証する必要がある場合は
owl.monitor.receiveを呼び出します。
DQL ドキュメント検索と本文読み取り¶
owl.data.search_dql_docs は Registry サーバー側で実行され、results 内の断片、document_id、version、read_reference を返します。references_dir は互換性のために保持されているサーバー側の診断パスであり、Agent のローカルディレクトリではありません。read_file、cat、grep に渡さないでください。
選択した結果の 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 を維持し、必要なセクションが完全になるか has_more=false になるまで、start_line を next_start_line に設定します。ここでは行単位でページングし、ファイル読み取りの next_offset は使用しません。
document.version_changed が発生した場合は再検索して新しい参照を使用します。version を省略して検証を回避したり、異なるバージョンのページを混在させたりしないでください。空の results は一致する断片がないことのみを示します。ツールはパストラバーサル、シンボリックリンク、非 Markdown または非 UTF-8 ファイル、4 MiB を超えるドキュメント、および 65536 バイトを超える単一行を拒否します。この機能は CLI ドキュメント補助ツールに属し、すべての MCP 公開モードで表示されることは保証されません。