同一組織内のクロスワークスペース Trace クエリ使用説明¶

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

この機能は、同一組織内で指定した trace_id に基づいて複数のワークスペースのトレースデータを照会するために使用します。Trace クエリのシナリオのみを対象としており、通常の DQL クエリ API のクロスワークスペースのセマンティクスは変更されません。

前提条件¶

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

設定スイッチ¶

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

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

設定項目の説明：

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

スイッチの動作¶

スイッチ無効時¶

SameOrgTraceQuerySet.enable=false の場合：

• 同一組織のワークスペース簡易情報リストを取得する API は引き続き正常に利用できます。
• Trace クエリ API では現在のワークスペースのみ照会できます。
• リクエスト内の対象ワークスペース UUID リストに現在のワークスペース以外が含まれる場合、OpenAPI は code=406、errorCode=ft.ParameterCheckFailed を返します。このエラーコードは他のパラメータ検証エラーでも使用されるため、エラーコードだけでスイッチの状態を判断することはできません。

現在のワークスペースの UUID のみを渡す場合、またはワークスペース UUID リストを渡さない場合は、現在のワークスペースのトレースデータを照会するのと同じです。

スイッチ有効時¶

SameOrgTraceQuerySet.enable=true の場合、Trace クエリ API は同一組織内の複数のワークスペース UUID を受け付けます。サーバー側はワークスペース数、時間ウィンドウ、クエリパラメータを検証し、内部クエリ時に対象ワークスペースのリストを含めます。

関連 API¶

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

この API は SameOrgTraceQuerySet.enable の制御を受けず、Trace クエリの対象ワークスペースを選択するために使用できます。

OpenAPI：

POST /api/v1/workspace/same_org/list

AIAPI：

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

主なリクエストパラメータ：

リストはワークスペース ID の降順で返されます。pageIndex / page_index は使用しません。ページネーションフィールドの対応は次のとおりです。

たとえば、OpenAPI の初回リクエストボディは次のとおりです。

{"pageSize": 20}

レスポンスで hasMore=true かつ nextBeforeWorkspaceId=12345 の場合、次のリクエストは次のとおりです。

{"pageSize": 20, "beforeWorkspaceId": 12345}

AIAPI の対応するリクエストは次のとおりです。

{"page_size": 20, "before_workspace_id": 12345}

ページネーション中は元のワークスペースのフィルタ条件を変更しないでください。hasMore / has_more が false になったら終了します。ワークスペース ID はリストのページネーションにのみ使用され、以降の Trace クエリではワークスペース UUID を使用します。

同一組織の Trace クエリ¶

OpenAPI：

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

AIAPI：

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

OpenAPI のパラメータは lower camelCase 形式、AIAPI のパラメータはスネークケース形式です。

OpenAPI は selectClause と offset をサポートしません。ページネーションには cursorTime / cursorToken を使用してください。具体的な手順は後述します。

OpenAPI リクエスト例¶

サンプル内のワークスペース、トレース ID、時間範囲は実際の値に置き換えてください。ページネーション中はこれらのクエリ条件を変更しないでください。

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
}

Trace のスクロールページネーション¶

OpenAPI の単一結果は content.data[0] にあり、AIAPI の対応する位置は data.data[0] です。その中の next_cursor_time と next_cursor_token を読み取ります。

1. 初回クエリではカーソルを省略できます。また、cursorTime / cursor_time をクエリ終了時間の 13 桁のミリ秒タイムスタンプに設定することもできます。
2. next_cursor_time < 0 の場合はページネーションを終了します。この負の値を API に戻さないでください。
3. 次のページが必要な場合は、next_cursor_time をそのまま渡し、空でない next_cursor_token も同時に渡します。後続のカーソルは 16 桁のマイクロ秒タイムスタンプの場合があるため、ミリ秒に変換しないでください。変換すると同じタイムスタンプ付近のデータが欠落する可能性があります。
4. next_cursor_token が空の場合は省略するか、空文字列を渡します。有効な next_cursor_time がない場合は、カーソルを独自に構築したり、リクエストを繰り返したりせず、レスポンスを記録して調査してください。

前のページで返された next_cursor_time が 1772519729000123、next_cursor_token が cursor_example の場合、OpenAPI の次ページのリクエストボディは次のとおりです。

{
  "traceId": "TRACE-XXXX",
  "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
  "startTime": 1772516130000,
  "endTime": 1772519730000,
  "limit": 100,
  "cursorTime": 1772519729000123,
  "cursorToken": "cursor_example"
}

上記のカーソルはあくまで例であり、実際のリクエストでは前のページのレスポンス値を使用する必要があります。AIAPI では cursor_time / cursor_token を使用し、その他のフィールドは前述のスネークケース命名に従います。startTime / endTime（または start_time / end_time）は元のミリ秒の時間範囲を維持し、ページネーションカーソルに合わせて換算しないでください。source やフィルタ条件を使用している場合も、ページ送り中は変更しないでください。

よくある質問¶

ft.ParameterCheckFailed が返る場合¶

同一組織内のクロスワークスペース Trace クエリスイッチが無効な状態で他のワークスペースをリクエストすると、OpenAPI はこのエラーを返します。対象ワークスペースが同一組織に属していない場合や、時間範囲や他のパラメータが不正な場合も同じエラーが返される可能性があるため、リクエストパラメータに基づいて調査してください。

対処方法：

• まず時間範囲、カーソル、ワークスペースの所属、サイト設定を確認します。
• 現在のワークスペースのみを照会する場合は、他のワークスペース UUID を削除します。
• どうしてもクロスワークスペースのクエリが必要な場合は、Studio バックエンドの設定で SameOrgTraceQuerySet.enable を有効にしてサービスを再起動します。

従来の query_data API で同一組織のワークスペースリストを渡せますか¶

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

終了時間を指定しない場合はどう照会しますか¶

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