apm サービス一覧¶
GET /api/v1/tracing/list
概要¶
指定された時間ウィンドウ内のワークスペースの APM サービス統計をページングして一覧表示し、登録済みサービスリストと監視ステータスを補足します。
呼び出し前の準備と使用手順¶
r または w 権限を持つサイトの External 認証情報を使用します。認証については External API 署名認証 を参照してください。まずアクティブな workspaceUUID と実際のミリ秒ウィンドウを取得します。この API は 1 回に 1 ワークスペースのみを対象とし、複数ワークスペースの場合は同じウィンドウで順次リクエストします。デフォルトは pageIndex=1、pageSize=50(1~100)で、p99 の降順に並び、明示的な order では最初のソートオブジェクトのみを使用します。content.buckets と content.pageInfo を読み取ります。max_* は同じ時間ウィンドウ内の全サービスを比較する上限であり、filters/serviceTypes を追加しても分母は再計算されません。統計に対応するインデックスがない場合、空になることがあります。失敗を空データとして扱わないでください。External には個人 creator がないため、お気に入りフィールドは呼び出し元の個人のお気に入りを表しません。loading=true は登録済みサービスの追加ステータスキャッシュがまだ読み込み中であることを示し、後で再クエリできます。読み取りリクエストはステータス更新タスクを投入する場合があります。dfStatus=ok/空の checkerInfo は完全なアラート検証の代わりにはなりません。サービス登録情報の uuid とサービス名 service は異なります。パフォーマンス時間の生値はマイクロ秒で、ミリ秒に変換するには 1000 で除算します。この API は CSV ファイルをエクスポートしません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエスト本文の署名バージョン。省略したまま本ページのアルゴリズムを使用し続けることはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 読み取り API では r または w の認証情報を使用でき、書き込み API では w の認証情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字のメソッド、nonce、元の完全なパス、timestamp、および元の UTF-8 リクエスト本文をスペースで連結し、HMAC-SHA256 を適用して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証 に従って対応する SK を使用して計算します。完全に実行可能なテンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイトに設定された署名有効時間ウィンドウ内である必要があり、例の時刻を再利用することはできません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| filters.tags | array | tags オブジェクトを含む形式の条件リスト。この配列を直接 filters JSON のルートとして使用することもできます。 例: [{"name": "service", "operation": "in", "value": ["checkout-api"], "condition": "and"}]取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| filters.tags[*] | json | リーフ条件、または filters を含む再帰的なグループオブジェクト。 例: {"name": "service", "operation": "in", "value": ["checkout-api"], "condition": "and"}取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| filters.tags[*].name | string | リーフのフィールド名。実際に収集されたタグから取得します。必須で、空にはできません。 例: service取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| filters.tags[*].operation | string | リーフの演算子。通常は =、!=、in、notin、=~、wildcard、exists などを使用し、ダウンストリームのサポートに応じて選択します。互換用の op も使用できますが、両方を省略すると内部エラーになります。 例: in取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| filters.tags[*].value | array | リーフの一致値配列。実際のフィールド型に従って入力します。必須であり、空の配列はワイルドカードとして扱われません。 例: ["checkout-api"]取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| filters.tags[*].condition | string | 前の項目との論理関係(and/or)。デフォルトは and です。互換用の logic も使用できます。 例: and取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| filters.tags[*].filters | array | グループ化された子条件の配列。再帰構造は外側と同じです。空でないグループは condition で結合されます。 例: [{"name": "service", "operation": "in", "value": ["checkout-api"], "condition": "and"}]取得または入力方法: 実際の APM タグと検証済みのクエリ条件から構築します。このパスは filters 文字列をデコードした後の構造を表します。 |
|
| end | integer | Y | 必須の終了ミリ秒整数。ウィンドウには実際のトレース収集データが存在する必要があります。 例: 1785430800000取得または入力方法: 同じ時間基準の実際のウィンドウ終点を Unix ミリ秒で使用します。 |
| filters | json | 任意の JSON 文字列。tags 配列を含むオブジェクト、または条件オブジェクトの配列を使用できます。省略するとフィルタリングしません。[] は空条件です。fields オブジェクトや {} だけを渡さないでください。現在の正規化ではオブジェクトが残り、条件配列として扱われない可能性があります。operation/op および condition/logic は互換です。無効な JSON やオブジェクト構造は 500 になる可能性があります。これはリクエスト JSON 本文ではありません。 例: {"tags":[{"name":"service","operation":"in","value":["checkout-api"],"condition":"and"}]}取得または入力方法: 収集済みの APM サービス/タグ結果から service、env、version などの実際のフィールドと値を選択します。JSON 文字列全体を urlencode でエンコードします。 |
|
| order | string | 任意のソート用 JSON 配列文字列。デフォルトは p99 の降順です。現在は配列の最初のオブジェクトのみを読み取ります。よく使用する key、total_count、avg_resp_time、avg_per_second、error_count、error_rate、sum_resp_time、max_duration、p50/p75/p90/p95/p99 と、方向 asc/desc を使用できます。無効な JSON、空の配列、または誤った構造は 500 になる可能性があり、自動的にフォールバックしません。 例: [{"p99":"desc"}]取得または入力方法: 許可されたフィールドから 1 つを選択し、必要に応じて asc または desc を選択します。単一要素の JSON 配列文字列を渡します。 |
|
| pageIndex | integer | ページ番号。デフォルトは 1 です。 null を許可: False $minValue: 1 例: 1取得または入力方法: 1 から開始し、後続のリクエストではページ番号を増やし、フィルタと時間ウィンドウを一致させます。 |
|
| pageSize | integer | 1 ページあたりの件数。デフォルトは 50 です。 null を許可: False $maxValue: 100 $minValue: 1 例: 50取得または入力方法: 必要に応じて 1~100 の整数を入力します。 |
|
| serviceTypes | array | 任意の JSON 配列文字列。source_type でサービスをフィルタリングします。省略するとフィルタリングしません。カンマ区切り文字列ではなく、同じ名前のパラメータを重複して渡すこともできません。誤った JSON または配列以外の値はダウンストリーム/内部エラーになる可能性があります。 例: ["web","db"]取得または入力方法: サービス一覧の content.buckets[].source_type/type から実際の型を読み取り、文字列配列にシリアライズします。 |
|
| start | integer | Y | 必須の開始ミリ秒整数。end より小さい必要があります。署名の timestamp には別途現在の Unix 秒を使用します。 例: 1785427200000取得または入力方法: 実際の収集データウィンドウの起点を Unix ミリ秒に変換します(例:JavaScript の Date.getTime())。 |
| workspaceUUID | string | Y | 必須の単一ワークスペース UUID。* やカンマで複数の UUID を連結することはできません。このサイトの External はサイトレベルの認証情報であり、通常メンバーの OpenAPI Key で対象ワークスペースを決定するものではありません。 例: wksp_example001取得または入力方法: ワークスペース一覧 の content.data[].uuid からアクティブなワークスペースを取得します。 |
パラメータ補足説明¶
JSON フィルタ文字列は完全な URL エンコードを使用し、署名に含まれます。正常な空結果では content.buckets=[]、pageInfo.totalCount=0、loading=false になることがあり、max_* キーは省略される場合があります。サービスリストの設定フィールドと実際の収集統計は同じリソースではありません。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/tracing/list'
query = {'workspaceUUID': 'wksp_example001', 'start': 1785427200000, 'end': 1785430800000, 'pageIndex': 1, 'pageSize': 50}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP200、application/json の標準 External エンベロープで、データは content 内にあります。このモジュールは OpenAPI declaration を自動的に追加せず、content.pageInfo をトップレベルに昇格させることもありません。レスポンスの統計フィールドは実際のダウンストリームのバージョン/データによって変化します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.max_duration | number | 全サービスの最大応答時間の上限(マイクロ秒)。 |
| content.max_total_count | integer | 全サービス中の最大総リクエスト数。 |
| content.max_per_second | number | 全サービス中の最大 1 秒あたりリクエスト数(req/s)。 |
| content.max_avg_duration | number | 全サービス中の最大平均応答時間(マイクロ秒)。 |
| content.max_sum_duration | number | 全サービス中の最大累計応答時間(マイクロ秒)。 |
| content.max_p50 | number | 全サービス中の最大 P50 応答時間(マイクロ秒)。 |
| content.max_p75 | number | 全サービス中の最大 P75 応答時間(マイクロ秒)。 |
| content.max_p90 | number | 全サービス中の最大 P90 応答時間(マイクロ秒)。 |
| content.max_p95 | number | 全サービス中の最大 P95 応答時間(マイクロ秒)。 |
| content.max_p99 | number | 全サービス中の最大 P99 応答時間(マイクロ秒)。 |
| content.buckets | array<object> |
現在のページのサービス統計。統計フィールドは存在するデータに応じて提供されます。 |
| content.buckets[].key | string | グループ化されたサービス名。通常は service と同じです。 |
| content.buckets[].service | string | 収集データ内のサービス名。単一サービス検索時の serviceName でもあります。 |
| content.buckets[].source_type | string | 収集されたサービスのソース種別。 |
| content.buckets[].type | string | 互換フィールド。source_type と同じです。 |
| content.buckets[].version | string | サービスバージョン。この統計ディメンションが存在する場合に返されます。 |
| content.buckets[].env | string | サービス環境。この統計ディメンションが存在する場合に返されます。 |
| content.buckets[].total_count | integer | 統計ウィンドウ内のリクエスト数。 |
| content.buckets[].avg_per_second | number | 1 秒あたりの平均リクエスト数(単位: req/s)。 |
| content.buckets[].avg_resp_time | number | 平均応答時間(マイクロ秒)。ミリ秒に換算する場合は 1000 で除算します。 |
| content.buckets[].sum_resp_time | number | リクエスト応答時間の累計(マイクロ秒)。 |
| content.buckets[].max_duration | number | リクエスト応答時間の最大値(マイクロ秒)。 |
| content.buckets[].p50 | number | 応答時間の第 50 パーセンタイル(マイクロ秒)。 |
| content.buckets[].p75 | number | 応答時間の第 75 パーセンタイル(マイクロ秒)。 |
| content.buckets[].p90 | number | 応答時間の第 90 パーセンタイル(マイクロ秒)。 |
| content.buckets[].p95 | number | 応答時間の第 95 パーセンタイル(マイクロ秒)。 |
| content.buckets[].p99 | number | 応答時間の第 99 パーセンタイル(マイクロ秒)。 |
| content.buckets[].error_count | integer | エラーリクエスト数。 |
| content.buckets[].error_rate | number | エラー率(0~1)。パーセント表示にする場合は 100 を乗算します。 |
| content.buckets[].apdex | number または string | バックエンドが提供する場合に返される Apdex 満足度。 |
| content.buckets[].serviceCatelog | object | 対応する登録済みサービスの TOML 設定を解析したオブジェクト。設定がない場合は {} です。現在のトレース一覧では originStr の切り替えは提供されません。一覧にないカスタム/履歴キーは元の設定に従って返されます。 |
| content.buckets[].checkerInfo | array<object> |
関連付けられたモニターの一覧。 |
| content.buckets[].checkerInfo[].name | string | モニター名。 |
| content.buckets[].checkerInfo[].uuid | string | モニター UUID。 |
| content.buckets[].checkerInfo[].type | string | モニタータイプ。 |
| content.buckets[].dfStatus | string | サービスの現在のイベントステータス(ok、critical など)。ステータス記録がない場合は ok です。 |
| content.buckets[].__docid | string | サービスステータスに対応するイベントドキュメント ID。対応するイベントがない場合は空文字列です。 |
| content.buckets[].isFavorite | integer または null | お気に入りフラグ(0/1 または null)。External は個人 creator を渡さないため、現在の特定の実アカウントのお気に入り状態としては使用できません。 |
| content.buckets[].uuid | string | 登録済みサービス設定の UUID。未登録サービスの場合は空文字列になることがあります。 |
| content.buckets[].language | string | 登録された収集 SDK の言語。未登録の場合は空になることがあります。 |
| content.pageInfo | object | ページング情報は content 内にあります。 |
| content.pageInfo.pageIndex | integer | 現在のページ番号。 |
| content.pageInfo.pageSize | integer | 1 ページあたりの件数。 |
| content.pageInfo.count | integer | 現在のページの実際の件数。 |
| content.pageInfo.totalCount | integer | 一致するサービスの総数。 |
| content.loading | boolean | 追加ステータスがまだ非同期で読み込み中かどうか。 |
| content.buckets[].serviceCatelog.Team | object | サービスとチームの設定。 |
| content.buckets[].serviceCatelog.Team.service | string | サービス名。 |
| content.buckets[].serviceCatelog.Team.type | string | サービスの分類。書き込み時は API のルールに従って無効な分類を処理します。 |
| content.buckets[].serviceCatelog.Team.colour | string | サービスの表示色。 |
| content.buckets[].serviceCatelog.Team.team | string | 所属チーム名。 |
| content.buckets[].serviceCatelog.Team.oncall | array<object> |
連絡先。 |
| content.buckets[].serviceCatelog.Team.oncall[].name | string | 連絡先の表示名。 |
| content.buckets[].serviceCatelog.Team.oncall[].type | string | email、mobile または slack。 |
| content.buckets[].serviceCatelog.Team.oncall[].emails | array<string> |
email 連絡先のメールアドレス。 |
| content.buckets[].serviceCatelog.Team.oncall[].mobiles | array<string> |
mobile 連絡先の電話番号。 |
| content.buckets[].serviceCatelog.Team.oncall[].slack | string | Slack チャンネル URL。 |
| content.buckets[].serviceCatelog.Repos | array<object> |
コードリポジトリの一覧。 |
| content.buckets[].serviceCatelog.Repos[].name | string | リポジトリの表示名。 |
| content.buckets[].serviceCatelog.Repos[].link | string | リポジトリ URL。 |
| content.buckets[].serviceCatelog.Repos[].provider | string | プロバイダーの表示名。 |
| content.buckets[].serviceCatelog.Docs | array<object> |
操作ドキュメントの一覧。 |
| content.buckets[].serviceCatelog.Docs[].name | string | ドキュメントの表示名。 |
| content.buckets[].serviceCatelog.Docs[].link | string | ドキュメント URL。 |
| content.buckets[].serviceCatelog.Docs[].provider | string | ドキュメント提供者の表示名。 |
| content.buckets[].serviceCatelog.Related | object | 関連付けられたアプリケーション、組み込みビュー、およびシーンタグ。 |
| content.buckets[].serviceCatelog.Related.AppId | string | リアルユーザーモニタリング(RUM)アプリケーション ID。空になることがあります。 |
| content.buckets[].serviceCatelog.Related.DashboardUUIDs | array<string> |
関連付けられた組み込みビューの UUID。 |
| content.buckets[].serviceCatelog.Related.Tags | array<string> |
シーンタグ名。 |
| content.buckets[].serviceCatelog.その他の設定キー | JSON 値 | 元の TOML がサポートするその他の履歴/拡張内容。例のフィールド集合に固定されません。 |
{
"code": 200,
"content": {
"max_total_count": 250,
"max_per_second": 0.07,
"max_avg_duration": 12000,
"max_duration": 50000,
"buckets": [
{
"key": "checkout-api",
"service": "checkout-api",
"source_type": "web",
"type": "web",
"version": "",
"env": "",
"total_count": 250,
"avg_per_second": 0.06944444444444445,
"avg_resp_time": 12000,
"sum_resp_time": 3000000,
"max_duration": 50000,
"p50": 10000,
"p75": 14000,
"p90": 22000,
"p95": 30000,
"p99": 45000,
"error_count": 2,
"error_rate": 0.008,
"apdex": 0.98,
"serviceCatelog": {},
"checkerInfo": [],
"dfStatus": "ok",
"__docid": "",
"isFavorite": null,
"uuid": "",
"language": ""
}
],
"pageInfo": {
"pageIndex": 1,
"pageSize": 50,
"count": 1,
"totalCount": 1
},
"loading": false
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては 共通エラー定義 を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータの解析に失敗しました | パラメータの位置、フィールド名、型、および値を確認してください。 |
| 422 | ft.KodoAPMSummaryRowBudgetExceeded | サービス統計の集計スキャン予算を超過しています | APM サービスの集計データ量が処理上限を超えています。時間範囲を縮小して再試行してください。 | 時間ウィンドウを縮小してください。pageSize を小さくしても、全サービスの集計予算は減少しません。 |
| 429 | ft.KodoServerOverloaded | クエリサービスが過負荷またはビジーです | 現在のリクエスト頻度が高すぎます。しばらくしてから再試行してください。 | バックオフ間隔で再試行し、同時クエリ数を減らしてください。 |
| 500 | ft.InternalServerError | filters/serviceTypes/order の形式エラー、サービスリスト TOML の解析失敗、キャッシュ更新の送信失敗、または統計ダウンストリームの利用不可/通常の 5xx | 内部エラー | 例に従って JSON 文字列と有効な設定を使用してください。traceId を保持し、まず時間ウィンドウを縮小してから限定的に再試行してください。読み取りによってサービスステータスキャッシュの更新タスクがトリガーされる場合がありますが、サービスリストは変更されません。 |
| 406 | ft.KodoRequestDeadlineExceeded | クエリの実行がバックエンドで許可された時間を超えています | データクエリがタイムアウトしました。原因として、データ量が多すぎる、ネットワーク遅延、サーバー負荷が高いなどが考えられます。この問題は次の方法で解決できます。 1. フィルタ条件を追加するか、時間範囲を縮小してから再度クエリを実行してください。 2. しばらく待ってから再度クエリを試してください。 |
時間範囲を縮小し、フィルタ条件を追加してから再試行してください。 |
| 406 | ft.KodoTooManyRows | クエリ対象のデータ量がバックエンドの制限を超えています | クエリ対象のデータ量が最大件数制限を超えています。フィルタ条件を追加するか、時間範囲を縮小してから再度クエリを実行してください。 | 時間範囲を縮小するか、一致するサービスを減らしてから再試行してください。 |
| 406 | ft.KodoInvalidRegexPattern | 使用されている正規表現フィルタ式が無効です | 提供された正規表現パターンが無効です | 正規表現を修正するか、明確なサービス名の集合を使用してください。 |