同組織クロスワークスペース Trace クエリ利用ガイド¶

本ドキュメントでは、デプロイメントプラン版 Studio における同組織クロスワークスペース Trace クエリ機能のスイッチ設定、インターフェースの利用方法、およびよくある質問について説明します。

この機能は、同一組織内で指定された trace_id に基づき、複数のワークスペースにわたる分散型トレーシングデータをクエリするために使用します。これは Trace クエリシナリオに特化したものであり、通常の DQL クエリインターフェースのクロススペースセマンティクスを変更するものではありません。

使用前提¶

Studio バックエンドのバージョンに SameOrgTraceQuerySet 設定と同組織 Trace クエリ専用インターフェースが含まれている必要があります。
対象のワークスペースは、現在のワークスペースと同じ組織に属している必要があります。
現在のワークスペース以外をクエリする場合は、SameOrgTraceQuerySet.enable を有効にする必要があります。
Kodo 側のパラメータを個別に調整する必要はありません。Studio バックエンドが内部リクエストに対象ワークスペースのリストを付与します。

設定スイッチ¶

SameOrgTraceQuerySet は Studio バックエンドサービスの設定にあり、デフォルトでは無効です。

SameOrgTraceQuerySet:
  enable: false
  maxWorkspaceCount: 20
  maxLimit: 1000
  maxTimeRangeHours: 24
  workspaceListPageSizeMax: 100

設定項目の説明：

設定項目	デフォルト値	説明
`enable`	`false`	同組織クロスワークスペース Trace クエリを許可するかどうか。無効の場合は現在のワークスペースのみクエリ可能。
`maxWorkspaceCount`	`20`	1回のTraceクエリおよびワークスペース一覧フィルタリングで許可される最大ワークスペース UUID 数。
`maxLimit`	`1000`	1回のTraceクエリで明示的に `limit` を指定する際の最大値。
`maxTimeRangeHours`	`24`	1回のTraceクエリで許可される最大時間ウィンドウ（単位：時間）。
`workspaceListPageSizeMax`	`100`	同組織ワークスペース簡易情報一覧取得インターフェースで許可される最大ページサイズ。

設定を有効にした後、Studio バックエンド関連サービスを再起動する必要があります。

スイッチの動作¶

スイッチ無効時¶

SameOrgTraceQuerySet.enable=false の場合：

同組織ワークスペース簡易情報一覧取得インターフェースは引き続き正常に使用できます。
Trace クエリインターフェースは現在のワークスペースのみクエリ可能です。
リクエスト内の対象ワークスペース UUID リストに現在のワークスペース以外が含まれている場合、インターフェースは以下を返します：

{
  "code": 406,
  "errorCode": "ft.SameOrgTraceQueryDisabled",
  "message": "同組織クロスワークスペース Trace クエリスイッチが有効になっていません"
}

現在のワークスペース UUID のみを渡すか、ワークスペース UUID リストを渡さない場合は、現在のワークスペースの分散型トレーシングデータをクエリするのと同じ動作になります。

スイッチ有効時¶

SameOrgTraceQuerySet.enable=true の場合、Trace クエリインターフェースは同一組織内の複数のワークスペース UUID を指定して受け付けることができます。サーバー側はワークスペース数、時間ウィンドウ、クエリパラメータを検証し、内部クエリ時に対象ワークスペースのリストを付与します。

関連インターフェース¶

同組織ワークスペース簡易情報一覧の取得¶

このインターフェースは SameOrgTraceQuerySet.enable の制御を受けません。Trace クエリの対象ワークスペースを選択するために使用できます。

OpenAPI：

POST /api/v1/workspace/same_org/list

AIAPI：

POST /api/v1/account/workspace/same_org/list

よく使われるリクエストパラメータ：

パラメータ	説明
`workspaceUUIDs`	OpenAPI パラメータ、オプション。ワークスペース UUID リストでフィルタリング。
`workspace_uuids`	AIAPI パラメータ、オプション。ワークスペース UUID リストでフィルタリング。
`pageIndex` / `page_index`	ページ番号、デフォルト `1`。
`pageSize` / `page_size`	1ページあたりの件数、デフォルト `20`、最大値は `workspaceListPageSizeMax` で制御。

同組織 Trace クエリ¶

OpenAPI：

POST /api/v1/df/same_org/trace/query

AIAPI：

POST /api/v1/data/same_org/trace/query

OpenAPI パラメータはローワーキャメルケース、AIAPI パラメータはスネークケースを使用します。

OpenAPI パラメータ	AIAPI パラメータ	説明
`traceId`	`trace_id`	必須、トレース ID。
`workspaceUUIDs`	`workspace_uuids`	オプション、対象ワークスペース UUID リスト。指定しない場合は現在のワークスペースをクエリ。
`whereClause`	`where_clause`	オプション、DQL フィルタ条件を追加。`trace_id` 条件は不要。
`source`	`source`	オプション、Trace データソース。デフォルトですべてのソースをクエリ。
`startTime`	`start_time`	オプション、ミリ秒タイムスタンプ。指定しない場合のデフォルトは過去 1 時間。
`endTime`	`end_time`	オプション、ミリ秒タイムスタンプ。指定しない場合、内部 DQL `time_range` は開始時刻のみ。
`limit`	`limit`	オプション、返却件数の上限。指定しない場合は内部クエリのデフォルト値に従う。
`cursorTime`	`cursor_time`	オプション、スクロールページネーション用カーソル時刻。
`searchAfter`	`search_after`	オプション、スクロールページネーション用カーソル。

OpenAPI は selectClause および offset をサポートしません。ページネーションには cursorTime / searchAfter を使用してください。

OpenAPI リクエスト例¶

curl --location 'https://<studio-backend-host>/api/v1/df/same_org/trace/query' \
  --header 'Content-Type: application/json' \
  --header 'DF-API-KEY: <your-openapi-key>' \
  --data '{
    "traceId": "TRACE-XXXX",
    "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
    "startTime": 1772516130000,
    "endTime": 1772519730000,
    "limit": 100
  }'

AIAPI リクエスト例¶

{
  "trace_id": "TRACE-XXXX",
  "workspace_uuids": ["wksp_xxx", "wksp_yyy"],
  "where_clause": "`service` = 'api'",
  "start_time": 1772516130000,
  "limit": 100
}

よくある質問¶

エラー `ft.SameOrgTraceQueryDisabled` が返される¶

現在のサイトでは同組織クロスワークスペース Trace クエリスイッチが有効になっていないことを示しますが、リクエストに現在のワークスペース以外の UUID が含まれています。

対処方法：

現在のワークスペースのみをクエリする必要がある場合は、他のワークスペース UUID を削除してください。
クロスワークスペースクエリが本当に必要な場合は、Studio バックエンド設定で SameOrgTraceQuerySet.enable を有効にし、サービスを再起動してください。

元の `query_data` インターフェースで同組織ワークスペースリストを渡せますか？¶

サポートしていません。/api/v1/df/query_data、/api/v1/df/query_data_v1、/api/v1/df/asynchronous/query_data、および AIAPI の通常 DQL クエリインターフェースは、同組織クロスワークスペースのエントリパラメータを受け付けなくなりました。代わりに、同組織 Trace クエリ専用インターフェースを使用してください。

終了時刻を指定しない場合のクエリ方法¶

endTime / end_time を指定しない場合、サーバー側内部で構成される DQL time_range は開始時刻のみになります。開始時刻も指定しない場合、サーバー側はデフォルトで過去 1 時間の開始時刻を使用します。