同一組織のトレースクエリ¶
POST /api/v1/df/same_org/trace/query
概要¶
traceId で現在のワークスペースまたは同一組織内の指定ワークスペースのトレーシングデータをクエリします
呼び出し前と使用手順¶
- APM のトレース詳細または報告データの trace_id フィールドから、完全なトレース ID をコピーします。初回クエリでは、現在のワークスペースとデフォルトの時間範囲を使用できます。
- サイトが同一組織のクエリをサポートしている場合は、同一組織のワークスペース一覧の content.data[].workspaceUUID から対象の UUID を選択します。workspaceUUIDs を省略するか空配列を渡した場合、現在のワークスペースのみをクエリします。
- ループクエリでは、traceId、時間範囲、フィルター条件を一致させたまま、カーソルのみを更新します。cursorTime / cursorToken を優先して使用し、next_cursor_time が 0 未満になった時点で終了します。
クエリの時間スパンはデフォルトで 24 時間を超えません。重複排除後のワークスペース間 UUID 数はデフォルトで最大 20 個です。2 つの上限はサイト設定によって調整される場合があります。新しいカーソルまたは旧ページネーションパラメータのいずれかを使用します。以下のパラメータ表にある 2 種類のカーソル例は、それぞれ別のリクエストで使用します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | AK 識別子、AK UUID 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理で、この API の権限を持つ Key を作成または取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| traceId | string | Y | トレース ID、最大長は 512 null 許容: False 例: 032d15aa2ac166254744efd440987bdd取得または入力方法: APM のトレース詳細または trace_id フィールドから取得します。 |
| workspaceUUIDs | array | 任意、同一組織のワークスペース UUID リストを指定します。単一 UUID の最大長は 128 です。指定しない場合、または空配列の場合は現在のワークスペースをクエリします null 許容: True 例: ["wksp_example"]取得または入力方法: 同一組織のワークスペース一覧からワークスペース UUID を絞り込んでコピーします。ワークスペース間の機能はサイトで有効化する必要があります。 |
|
| startTime | integer | 任意、クエリ開始時間、13 桁のミリ秒タイムスタンプ null 許容: True 例: 1772516100000取得または入力方法: クエリ開始時間を Unix ミリ秒に変換します。省略した場合、デフォルトでサーバーの現在時刻の 1 時間前になります。この時刻例は、実際のトレースが存在する時刻に置き換えてください。 |
|
| endTime | integer | 任意、クエリ終了時間、13 桁のミリ秒タイムスタンプ。指定しない場合、終了時間は自動補完されません null 許容: True 例: 1772519700000取得または入力方法: クエリ終了時間を Unix ミリ秒に変換します。開始時間より後で、サーバーの現在時刻以前である必要があります。省略時の検証では、サーバーの現在時刻が終了上限として使用されます。 |
|
| source | string | 任意、tracing source。指定しない場合はすべての source をクエリします。具体的な source 名または * のみをサポートし、最大長は 128 です null 許容: True 例: web取得または入力方法: APM データに既存の tracing source 名を使用します。サービス名をそのまま source として扱わないでください。省略するか * を渡すと、すべての source をクエリできます。 |
|
| whereClause | string | 任意、追加の DQL where 条件フラグメント、最大長は 4096、外側の中括弧を含まず、サーバー側でパーサー検証が行われます null 許容: True 例: service = 'checkout'取得または入力方法: DQL のフィルター条件フラグメントを入力し、APM で既知のフィールドを使用して、外側の中括弧を省略します。 |
|
| limit | integer | 任意、返却件数の制限。指定しない場合は DQL のデフォルトページサイズを使用し、明示的に指定する場合のデフォルト最大値は 1000 で、サイト設定によって制御されます null 許容: True 例: 50取得または入力方法: クライアントで表示する件数に応じて正の整数を入力します。明示的な上限はサイト設定によって制御されます。 |
|
| searchAfter | array | 任意、旧ページネーション互換フィールド。Doris クエリではこのフィールドを使用しません。__docid に基づいて独自に構築しないでください null 許容: True 例: [1772519400000, "cursor-example"]取得または入力方法: 旧ページネーション互換方式です。クエリ結果で旧式カーソルが返された場合にのみ指定します。1 番目は 13 桁の Unix ミリ秒、2 番目は空でない文字列です。Doris では cursorTime / cursorToken を使用します。 |
|
| cursorTime | integer | 任意、スクロールページネーションカーソル。初回クエリでは 13 桁のミリ秒タイムスタンプを使用でき、2 回目以降はレスポンス内の 16 桁のマイクロ秒 next_cursor_time をそのまま渡す必要があります null 許容: True 例: 1772519400000123取得または入力方法: 初回クエリでは省略できます。続きをクエリする場合は、直前のレスポンスの next_cursor_time をコピーします。 |
|
| cursorToken | string | 任意、レスポンス内の next_cursor_token をそのまま渡します。レスポンスが空の場合は省略するか空文字列を渡すことができ、最大長は 512 です null 許容: True 例: cursor-example取得または入力方法: 直前のレスポンスの next_cursor_token をコピーします。空値の場合は省略できます。 |
パラメータ補足説明¶
この API はトレースクエリ専用であり、汎用 DQL の q はサポートしません。
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| traceId | string | Y | トレース ID |
| workspaceUUIDs | array | 同一組織のワークスペース UUID リスト。単一 UUID の最大長は 128 です。指定しない場合、または空配列の場合は現在のワークスペースをクエリします | |
| startTime | integer | クエリ開始時間。指定しない場合、デフォルトで直近 1 時間の開始時間になります | |
| endTime | integer | クエリ終了時間。指定しない場合、内部の time_range には開始時間のみが含まれます | |
| source | string | tracing source。指定しない場合はすべての source をクエリします。具体的な source 名または * のみをサポートし、最大長は 128 です |
|
| whereClause | string | 追加の DQL where 条件フラグメント、最大長は 4096、外側の中括弧を含まず、サーバー側でパーサー検証が行われます | |
| limit | integer | 返却件数の制限。指定しない場合は DQL のデフォルトページサイズを使用し、明示的に指定する場合のデフォルト最大値は 1000 で、サイト設定によって制御されます | |
| searchAfter | array | 旧ページネーション互換フィールド。Doris クエリではこのフィールドを使用しません。__docid に基づいて独自に構築しないでください |
|
| cursorTime | integer | スクロールページネーションカーソル。初回クエリでは 13 桁のミリ秒タイムスタンプを使用でき、2 回目以降はレスポンス内の 16 桁のマイクロ秒 next_cursor_time をそのまま渡す必要があります |
|
| cursorToken | string | レスポンス内の next_cursor_token をそのまま渡します。レスポンスが空の場合は省略するか空文字列を渡すことができ、最大長は 512 です |
OpenAPI パラメータはローワーキャメルケースのままです。selectClause と offset はサポートしません。ページネーションには cursorTime / cursorToken を使用し、next_cursor_time が 0 未満の場合は終了します。
リクエスト例¶
curl 'https://openapi.guance.com/api/v1/df/same_org/trace/query' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"traceId":"032d15aa2ac166254744efd440987bdd","limit":50}'
レスポンス¶
HTTP 200、application/json。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | array | クエリ結果リスト。この API は 1 件のトレースクエリを送信します。 |
| content.data[*].series | array | 実際のデータシリーズ。columns にはフィールド名、values には同じ順序のレコードが格納されます。 |
| content.data[*].next_cursor_time | integer | 次ページの時間カーソル。返された場合はそのまま使用し、負の値はこれ以上データがないことを示します。 |
| content.data[*].next_cursor_token | string | 次ページに対応する Token。空の場合も、返されない場合もあります。 |
{
"code": 200,
"content": {
"data": [
{
"series": [
{
"columns": [
"trace_id",
"service"
],
"values": [
[
"TRACE-XXXX",
"api"
]
]
}
],
"next_cursor_time": 1772519400000123,
"next_cursor_token": ""
}
]
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-XXXX"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーの詳細は共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | フィールドの型、必須、制約がパラメータ表に一致しない | リクエストフィールドの検証に失敗しました。メッセージにフィールドまたはルールが示されます。 | フィールド、型、制約を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラーです。 | content 内の reason、line、column を読み取って修正してください。 |
| 406 | ft.ParameterCheckFailed | 時間またはカーソルの形式、前後関係、範囲が無効 | 時間エラーには content.field、reason、serverTime、receivedTime が含まれる場合があります。 | 時間の精度、順序を確認するか、前ページの cursor をそのままコピーしてください。 |
| 406 | ft.ParameterCheckFailed | 同一組織のクエリが有効化されていない、指定ワークスペースが一致しない、または source / フィルター条件が受け入れられない | 汎用的なパラメータチェック失敗の情報を返します。 | まず現在のワークスペースでクエリし、その後、対象ワークスペース、source、whereClause を項目ごとに確認してください。 |
| 403 | ft.ForbiddenQuery | 対象ワークスペースまたは APM データをクエリする権限がない | クエリ権限が不足しています。 | API Key が属するワークスペースと APM のクエリ権限を確認してください。 |
| 503 | ft.QueryServiceUnavailable | 依存するクエリサービスが一時的に利用できない | クエリサービスが一時的に利用できません。しばらくしてから再試行してください。 | content.retryable を確認してください。一時的なエラーの場合は遅延して再試行できます。 |