一覧取得¶
POST /api/v1/error_track/list
概要¶
時間ウィンドウに基づいてエラー集約とその処理ステータスを検索します。
呼び出し前の準備と使用手順¶
現在の Key には errorCenter.errorTrackQuery が必要で、Key が所属するワークスペースのみをクエリします。まずミリ秒のウィンドウを指定し、次に conditions でテレメトリフィールドを絞り込みます。レスポンスの issue_id は詳細、ステータス、コメントの各パスで使用する業務識別子であり、refData.uuid に置き換えないでください。
まず最大 10000 件の EH エラー候補を取得し、その後ローカルで担当者/ステータスによる絞り込みとページネーションを行います。totalCount はこの上限を超える全エラー件数ではありません。ウィンドウ/条件を絞ってからページネーションしてください。最新の代表レコードと件数は同じウィンドウでクエリされます。複数回のクエリの間に新しいデータが追加されると、ページネーションがずれる可能性があります。issueStatusCountInfo は担当者によるフィルタリング後、ステータスフィルタリング前に集計され、件数があるステータスキーのみが表示されます。ローカルメタデータが未初期化のエラーは Triage としてカウントされますが、refData は {} のままです。
各項目は、現在のウィンドウ内の最新テレメトリレコード 1 件の動的フィールドに、refData、app_info、service_info を加えたものです。すべての生のエラーイベントではありません。一覧では、すべての項目に対してローカルメタデータが作成されるわけではありません。content はオブジェクトのまま保持され、data 配列は content.data に、pageInfo はレスポンスのトップレベルにあります。共通宣言は content.declaration のみで、data 項目のフィールドではありません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、当該操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| assigner | string | 任意の単一担当者 ID。ローカルの assigner の包含関係で絞り込みます。カンマ区切り/配列はサポートしません。省略または空文字列の場合はフィルタリングしません。メタデータがない項目は担当者フィルタリング時に除外されます。 null を許可: False 例: group_example取得または入力方法: ワークスペースメンバーから acnt_ を取得するか、チーム一覧から本ワークスペースの group_ を取得します。 |
|
| conditions | string | 任意の DQL 条件文字列。省略または空白の場合、追加のフィルタリングは行いません。完全な DQL/SQL ではなく、JSON 条件オブジェクトでもありません。候補、件数、最新レコードのクエリに使用されます。実際のフィールドを使用し、文字列を正しくエスケープしてください。信頼できない入力を直接連結しないでください。 空文字列を許可: True null を許可: False 例: service = 'payment-api'取得または入力方法: 実際の EH フィールドに基づいて DQL フィルタ式を構築してください。必要に応じて先にクエリツールで検証できます。 |
|
| endTime | integer | Y | 必須の整数。ウィンドウの終点です。Unix 秒/ナノ秒を渡さないでください。 null を許可: False 例: 1785427200000取得または入力方法: 呼び出し元で対象の時間ウィンドウを Unix ミリ秒に変換します。 |
| issueStatus | commaArray | 任意のカンマ区切り文字列。Triage/Assigned/Working/Resolved/Ignored の組み合わせを推奨します。省略または空文字列の場合はフィルタリングしません。JSON 配列ではありません。各項目は trim されず、大文字と小文字が区別されます。未知の値は通常、列挙エラーではなく単に一致なしとなります。 null を許可: False 例: Triage,Working取得または入力方法: エラーセンターのステータスに従って選択します。詳細の issueStatus に由来します。 |
|
| pageIndex | integer | 任意の整数。省略時は 1 です。現在のこれらの ErrorTrack エントリポイントでは正数/最大値の制限が宣言されていないため、クライアントは正の整数のみを使用してください。 null を許可: False 例: 1取得または入力方法: 呼び出し元でページネーションを制御し、1 から開始します。 |
|
| pageSize | integer | 任意の整数。省略時は 10 です。宣言に上限はありません。小さなページサイズでの読み取りを推奨します。0 や負数を渡して実装の動作に依存しないでください。 null を許可: False 例: 10取得または入力方法: 呼び出し元が表示/バッチ処理の規模に応じて選択します。 |
|
| startTime | integer | Y | 必須の整数。ウィンドウの起点です。endTime より小さいことを確認してください。宣言ではウィンドウ長/時間の前後関係を制限していません。広いウィンドウは候補の切り捨てやコスト増加につながる可能性があります。 null を許可: False 例: 1785423600000取得または入力方法: 呼び出し元で対象の時間ウィンドウを Unix ミリ秒に変換します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/error_track/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"startTime":1785423600000,"endTime":1785427200000,"conditions":"service = '"'"'payment-api'"'"'","pageIndex":1,"pageSize":10}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | data、issueStatusCountInfo、共通宣言を含みます。 |
| content.data | array<object> |
本ページのエラー集約。一致なしの場合は []。 |
| content.data[].time | integer | 現在の集約の代表レコードの Unix ミリ秒時間。 |
| content.data[].issue_id | string | エラー集約 ID。以降の詳細/ステータス/コメントのパスではこの値を使用します。 |
| content.data[].count | number | リクエストウィンドウ内の集約出現回数。統計が欠落している場合は互換性のため 1 を返します。全履歴の累計ではありません。 |
| content.data[].__docid | string | データエンジンのレコード ID。代表レコードに応じて変化する可能性があり、管理パスには使用しません。 |
| content.data[].__source | string | テレメトリソースのメタ情報。省略される場合があります。 |
| content.data[].source | string | 一般的な値は logging/tracing/rum です。実際の収集レコードによって決まります。 |
| content.data[].app_id | string | RUM の公開 appId。RumCfg の内部 UUID ではありません。RUM 以外では存在しない場合があります。 |
| content.data[].app_name | string | 収集されたアプリケーション名。現在の設定と異なる場合があります。 |
| content.data[].service | string | サービス名。サービス設定の UUID ではありません。 |
| content.data[].env | string | 収集環境。 |
| content.data[].version | string | 収集バージョン。 |
| content.data[].error_type | string | 収集されたエラータイプ。 |
| content.data[].error_message | string | エラーメッセージ。複数行を含む場合があります。 |
| content.data[].error_stack | string | エラースタック。SourceMap で復元済みであることは保証されません。 |
| content.data[].fingerprint | string | 収集されたエラーフィンガープリント。 |
| content.data[].resource | string | エラーリソース名。 |
| content.data[].log_index | string | ソースインデックス名。 |
| content.data[].session_id | string | RUM セッション ID。 |
| content.data[].view_id | string | RUM ページ ID。 |
| content.data[].trace_id | string | トレースの trace ID。API の traceId とは異なります。 |
| content.data[].span_id | string | トレースの span ID。 |
| content.data[].create_time | integer | 収集時の初回作成時間。Unix ミリ秒。 |
| content.data[].create_at | JSON または null | ソースの予約フィールド。型および存在有無はテレメトリソースに依存し、固定の時間単位を前提としません。 |
| content.data[].date | integer | ソースの時間フィールド。一般的には Unix ミリ秒ですが、収集フィールドの定義に従います。 |
| content.data[].date_ns | integer | ソースの Unix ナノ秒時間。 |
| content.data[].time_us | integer | ソースの Unix マイクロ秒時間。 |
| content.data[].* | number | 一部の集約互換フィールド。存在しない場合があり、安定した業務識別子として使用しません。 |
| content.data[].其他采集字段 | JSON | クエリウィンドウ内の最新代表レコードのその他の列をそのまま展開します。フィールドは欠落/null/収集ソースによる型変更があり得るため、クライアントは耐障害性を備える必要があります。 |
| content.data[].refData | object | ローカルステータスメタデータ。未初期化の場合は {} であり、エラーが存在しないと見なすことはできません。 |
| content.data[].app_info | object | 現在アクティブな RUM アプリケーションの jsonContent。一致しない場合は {}。Client Token は含みません。 |
| content.data[].app_info.name | string | 現在のアプリケーション表示名。 |
| content.data[].app_info.type | string | 現在のアプリケーションプラットフォームタイプ。 |
| content.data[].app_info.extend | object | 任意のアプリケーション動的表示拡張。 |
| content.data[].app_info.extend.自定义键 | JSON | アプリケーション設定に保存された拡張値。 |
| content.data[].service_info | object | 現在アクティブなサービス管理の概要。一致しない場合は {}。 |
| content.data[].service_info.service | string | サービス名。 |
| content.data[].service_info.type | string | サービス分類。 |
| content.data[].service_info.colour | string | サービスの表示色。 |
| content.data[].service_info.language | string または null | サービス言語。設定が空の場合は null になることがあります。 |
| content.data[].refData.id | integer または null | データベース行 ID。パス定位には使用しません。送信前スナップショットでは null になる場合があります。 |
| content.data[].refData.uuid | string | ローカルリソース UUID。詳細メタデータは isset_、操作レコードは issetoper_、コメントは issetcomment_ です。 |
| content.data[].refData.status | integer | リソースステータス。通常は 0。論理削除の 3 はクエリから除外されます。 |
| content.data[].refData.creator | string | 作成主体。メタデータの自動初期化時は sys、Key による書き込み主体は wsak_ です。 |
| content.data[].refData.updator | string | 最終更新主体。未更新の場合は空になることがあります。 |
| content.data[].refData.createAt | integer | Unix 秒の作成時間。 |
| content.data[].refData.updateAt | integer | Unix 秒の更新時間。未更新の場合は -1 になることがあります。同じ値でのステータス/担当者更新では必ずしも更新されません。 |
| content.data[].refData.deleteAt | integer | Unix 秒の削除時間。未削除の場合は通常 -1。 |
| content.data[].refData.workspaceUUID | string | 現在の Key が所属するワークスペース。 |
| content.data[].refData.issueID | string | テレメトリの issue_id 業務識別子。ローカルの uuid とは異なります。 |
| content.data[].refData.assigner | array<string> |
担当者アカウントの acnt_ またはチームの group_。現在の保存順序で、空配列は未割り当てです。 |
| content.data[].refData.assigner[] | string | 単一の担当者識別子。保存成功のみでアカウントの存在や通知可能であると判断することはできません。 |
| content.data[].refData.issueStatus | string | Triage/Assigned/Working/Resolved/Ignored。 |
| content.data[].refData.extend | object または null | ローカルメタデータ拡張。過去の異常値に対する耐障害性が必要です。 |
| content.data[].refData.extend.errorType | string | 初期化時に取得したエラータイプ。クエリ失敗/データなしの場合は空になることがあります。 |
| content.data[].refData.extend.firstTime | integer | 初期化時に直近 30 日間の create_time(Unix ミリ秒)をクエリします。クエリ失敗/データなしの場合は現在のミリ秒を返し、全履歴での初回であることは保証されません。 |
| content.data[].refData.extend.statusChangeRecords | array<object> |
ステータス変更レコード。各項目は保存履歴の順序に従います。 |
| content.data[].refData.extend.statusChangeRecords[].status | string | 上記ステータスのいずれか。 |
| content.data[].refData.extend.statusChangeRecords[].time | integer | ステータスへの遷移時間。Unix 秒。 |
| content.data[].refData.extend.statusChangeRecords[].operator | string | 操作主体の UUID/システム識別子。 |
| content.data[].refData.extend.其他键 | JSON | 過去に保存されたその他の拡張キー。固定の実行パラメータではありません。 |
| content.data[].refData.duration | integer | 秒。過去の完全なサイクルの時間差の合計に、現在時刻から最後の Triage サイクル開始時点を減じたものを加算します。Resolved/Ignored でも増加し続ける可能性があり、厳密な MTTR ではありません。計算異常時は欠落する場合があります。 |
| content.data[].refData.statusDuration | object | 直近の Triage サイクルにおけるステータス遷移時間のマッピング。各ステータスの継続秒数ではありません。計算異常時は省略される場合があります。 |
| content.data[].refData.statusDuration.状态 | integer | Triage/Assigned/Working/Resolved/Ignored のうち実際に出現し、増加条件を満たす Unix 秒時間。 |
| content.data[].refData.creatorInfo | object | 作成主体の概要。一致しない場合は {}。システム主体ではフィールドがアカウントより少ない場合があります。 |
| content.data[].refData.updatorInfo | object | 更新主体の概要。一致しない場合は {}。 |
| content.data[].refData.assignerInfo | array<object> |
解決可能な担当者概要。無効なアカウントは表示されない場合があり、assigner と同じ長さであることは保証されません。 |
| content.data[].refData.assignerInfo[].uuid | string | アカウントまたはチームの UUID。 |
| content.data[].refData.assignerInfo[].name | string | 表示名。チーム概要は uuid/name のみです。 |
| content.data[].refData.creatorInfo.uuid | string | 主体 UUID。アカウント、Key、またはシステム識別子の場合があります。 |
| content.data[].refData.creatorInfo.status | integer | 主体ステータス。 |
| content.data[].refData.creatorInfo.wsAccountStatus | integer | 現在のワークスペースメンバー関係ステータスの概要。 |
| content.data[].refData.creatorInfo.username | string | ログイン名または Key 名。 |
| content.data[].refData.creatorInfo.name | string | 表示名。 |
| content.data[].refData.creatorInfo.iconUrl | string | アバター URL。空の場合があります。 |
| content.data[].refData.creatorInfo.email | string | メールアドレス。Key 主体の場合は自身の UUID になることがあり、配信可能であることは保証されません。 |
| content.data[].refData.creatorInfo.mobile | string | 携帯電話番号。空の場合があります。 |
| content.data[].refData.creatorInfo.countryCode | string | 電話の国番号。空の場合があります。 |
| content.data[].refData.creatorInfo.acntWsNickname | string | 現在のワークスペースでのニックネーム。空の場合があります。 |
| content.data[].refData.updatorInfo.uuid | string | 主体 UUID。アカウント、Key、またはシステム識別子の場合があります。 |
| content.data[].refData.updatorInfo.status | integer | 主体ステータス。 |
| content.data[].refData.updatorInfo.wsAccountStatus | integer | 現在のワークスペースメンバー関係ステータスの概要。 |
| content.data[].refData.updatorInfo.username | string | ログイン名または Key 名。 |
| content.data[].refData.updatorInfo.name | string | 表示名。 |
| content.data[].refData.updatorInfo.iconUrl | string | アバター URL。空の場合があります。 |
| content.data[].refData.updatorInfo.email | string | メールアドレス。Key 主体の場合は自身の UUID になることがあり、配信可能であることは保証されません。 |
| content.data[].refData.updatorInfo.mobile | string | 携帯電話番号。空の場合があります。 |
| content.data[].refData.updatorInfo.countryCode | string | 電話の国番号。空の場合があります。 |
| content.data[].refData.updatorInfo.acntWsNickname | string | 現在のワークスペースでのニックネーム。空の場合があります。 |
| content.data[].refData.assignerInfo[].status | integer | 主体ステータス。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].wsAccountStatus | integer | 現在のワークスペースメンバー関係ステータスの概要。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].username | string | ログイン名または Key 名。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].iconUrl | string | アバター URL。空の場合があります。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].email | string | メールアドレス。Key 主体の場合は自身の UUID になることがあり、配信可能であることは保証されません。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].mobile | string | 携帯電話番号。空の場合があります。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].countryCode | string | 電話の国番号。空の場合があります。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.data[].refData.assignerInfo[].acntWsNickname | string | 現在のワークスペースでのニックネーム。空の場合があります。アカウント概要のみで、チームにはこのキーが含まれません。 |
| content.issueStatusCountInfo | object | 担当者フィルタリング後の候補エラーのステータス件数マッピング。issueStatus によるフィルタリングでは縮小されません。 |
| content.issueStatusCountInfo.状态 | integer | Triage/Assigned/Working/Resolved/Ignored のうちデータがあるステータスの件数。キーの欠落はレスポンス破損を意味しません。 |
| pageInfo | object | ページネーションのメタ情報。OpenAPI ではトップレベルにあり、content はオブジェクトのままです。 |
| pageInfo.count | integer | 本ページの実際の件数。 |
| pageInfo.totalCount | integer | フィルタ条件を満たす候補/ローカルレコードの総数。テレメトリ一覧は 10000 件の候補上限の影響を受けます。 |
| pageInfo.pageIndex | integer | ページ番号。1 から始まります。 |
| pageInfo.pageSize | integer | 今回の 1 ページあたりのリクエスト件数。 |
| content.declaration | object または null | 現在のワークスペースの共通宣言。content の親オブジェクトにのみ追加され、data 項目に再帰的に追加されません。 |
{
"code": 200,
"content": {
"data": [
{
"time": 1785427200000,
"issue_id": "err_payment_timeout",
"count": 8,
"__docid": "doc_example",
"source": "rum",
"app_id": "payment_web",
"service": "payment-api",
"env": "production",
"version": "1.0.0",
"error_type": "js_error",
"error_message": "Request timed out",
"error_stack": "at pay @ https://cdn.example.com/app.js:1:1",
"refData": {},
"app_info": {
"name": "支付Web",
"type": "web"
},
"service_info": {
"service": "payment-api",
"type": "web",
"colour": "#3F94DC",
"language": "python"
}
}
],
"issueStatusCountInfo": {
"Triage": 1
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"count": 1,
"totalCount": 1,
"pageIndex": 1,
"pageSize": 10
}
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
EH クエリの下流業務 4xx は、実際の HTTP/errorCode/message に従って返される場合があります。traceId を保持し、クエリエラーに応じて時間範囲を狭めるか conditions を修正してください。未認識/非透過の 5xx は通常 500 に統一されます。DQL クエリチェーンのみ、復旧可能な 503 は ft.QueryServiceUnavailable(content.retryable=true)に正規化されます。ステータスが Resolved になった後の通常の同期呼び出しでは、同じ正規化は保証されません。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンス説明 | 処理方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではない | 一部の JSON ファイル形式エラー | パラメータオブジェクトを送信してください。 |
| 503 | ft.QueryServiceUnavailable | EH DQL クエリチェーンの上流が一時的に利用不可で、503 正規化がトリガーされた | クエリサービスが一時的に利用できません。しばらくしてから再試行してください。 | content.retryable を確認してバックオフしてください。ウィンドウを狭め、traceId を保持してください。 |
| 500 | ft.InternalServerError | データベース読み取り、履歴 JSON 構造、または関連概要の構築で未処理の例外が発生 | 内部エラー | traceId を保持してバックオフしてください。継続的に失敗する場合は、管理者が関連する履歴レコードと設定を確認してください。 |