コンテンツにスキップ

同一組織のトレースクエリ



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

概要

traceId で現在のワークスペースまたは同一組織内の指定ワークスペースのトレーシングデータをクエリします

呼び出し前と使用手順

  1. APM のトレース詳細または報告データの trace_id フィールドから、完全なトレース ID をコピーします。初回クエリでは、現在のワークスペースとデフォルトの時間範囲を使用できます。
  2. サイトが同一組織のクエリをサポートしている場合は、同一組織のワークスペース一覧の content.data[].workspaceUUID から対象の UUID を選択します。workspaceUUIDs を省略するか空配列を渡した場合、現在のワークスペースのみをクエリします。
  3. ループクエリでは、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 を確認してください。一時的なエラーの場合は遅延して再試行できます。

フィードバック

このページは役に立ちましたか?