service map¶

GET /api/v1/tracing/service_map_v2

概要¶

指定したワークスペースと時間範囲におけるサービスノード、呼び出し関係、統計データを返します。レスポンスは JSON です。一括エクスポートでは、まずワークスペースをページングで取得し、その後ワークスペースごとにクエリを実行して結果を整理する必要があります。External API でサービスマップをエクスポートを参照してください。

Query リクエストパラメータ¶

パラメータ名	タイプ	必須	説明
workspaceUUID	string	Y	ワークスペースID
start	integer	Y	開始時間、単位 ms
end	integer	Y	終了時間、単位 ms
search	string		サービス名フィルター
filters	string		tag フィルター。検索および ES querydata インターフェースと同等
isServiceSub	boolean		後方互換の旧パラメータ。groupBy/group_by 未指定の場合、true で env と version の2つのグルーピングディメンションを追加し、旧 Project・Cluster スイッチと組み合わせ可能
serviceMapList	boolean		後方互換の履歴パラメータ。現在の実装ではこのパラメータによる追加リストは生成されないため、エクスポート時はレスポンスの maps と services を参照してください
showOnlyMatches	boolean		現在の検索またはフィルター条件に一致するサービスのみを表示するかどうか
showFullChain	boolean		フィルターに一致したサービスが属する完全な接続コンポーネントを返すかどうか。showOnlyMatches とは独立して転送され、両方が true の場合は Full Chain のセマンティクスが優先されます
groupBy	commaArray		サービスマップのグルーピングディメンション配列。project、cluster_name_k8s、env、version の任意の組み合わせをサポート。service_sub は後方互換として env と version に展開。複数の値は英字カンマで区切り、未指定または有効な値がない場合は service のみでグループ化
group_by	commaArray		groupBy の後方互換パラメータ名
groupByProject	boolean		後方互換の旧パラメータ。groupBy/group_by 未指定の場合、true で project のグルーピングディメンションを追加
group_by_project	boolean		groupByProject の後方互換パラメータ名
groupByClusterNameK8s	boolean		後方互換の旧パラメータ。groupBy/group_by 未指定の場合、true で cluster_name_k8s のグルーピングディメンションを追加
groupByClusterNameK8S	boolean		groupByClusterNameK8s の後方互換パラメータ名
group_by_cluster_name_k8s	boolean		groupByClusterNameK8s の後方互換パラメータ名
centralService	string		中心サービスの名前。先頭と末尾の空白を除去します
centralProject	string		中心サービスの project。未指定の場合はマッチングに参加しません。明示的に空または空白のみを渡した場合は project 未設定として完全一致でマッチします
centralClusterNameK8s	string		中心サービスの cluster_name_k8s。未指定の場合はマッチングに参加しません。明示的に空または空白のみを渡した場合はクラスター未設定として完全一致でマッチします
centralWorkspaceUUID	string		中心サービスが属するワークスペース。先頭と末尾の空白を除去します
centralEnv	string		中心サービスの env。未指定の場合はマッチングに参加しません。明示的に空または空白のみを渡した場合は env 未設定として完全一致でマッチします
centralVersion	string		中心サービスの version。未指定の場合はマッチングに参加しません。明示的に空または空白のみを渡した場合は version 未設定として完全一致でマッチします

パラメータ補足説明¶

クエリと認証¶

workspaceUUID では毎回1つのワークスペースを指定し、* や複数の UUID で単一のワークスペース ID を代替することはできません。 start、end はミリ秒のタイムスタンプです。署名ヘッダー X-Df-Timestamp は現在の秒単位のタイムスタンプです。 External API の AK/SK 署名を使用します。読み取り権限を持つアカウントで呼び出せます。ワークスペース OpenAPI の DF-API-KEY で代替することはできません。署名バージョンは X-Df-SVersion: v20240417 です。リクエストごとに、最終パスとクエリ文字列に基づいて署名を再生成します。

ワークスペース全体をクエリする場合は、centralService、search、制限付きの filters を渡さないでください。コンソールの単一サービス上流・下流ビューを、ワークスペース全体のトポロジーとして直接扱うことはできません。複数のワークスペースでは、同じ時間範囲と groupBy の基準を使用してください。このインターフェースには、呼び出しエッジのページネーションやファイルダウンロード機能はありません。

レスポンスフィールド¶

フィールド	説明
`content.services`	サービスノードのリスト。ノードの統計データは `data` に格納されます
`content.maps`	有向の呼び出しエッジリスト。`source` が `target` を呼び出します
`services[].workspace_uuid`	ノードが属するワークスペース。レスポンスでは保持する必要があります
`maps[].source_workspace_uuid` / `target_workspace_uuid`	呼び出しエッジの両端が属するワークスペース。サービス名のみでノードを区別しないでください
`services[].id`、`maps[].source_id` / `target_id`	ノードとエッジ端点の関連識別子。関連付けと重複排除の際は、ワークスペースの ID とグループディメンションを保持します
`maps[].total_count`	選択した時間範囲における当該呼び出しエッジのリクエスト数。サービスノードの総リクエスト数とは統計範囲が異なります
`maps[].avg_per_second`、`error_count`、`error_rate`	1秒あたりの平均リクエスト数、エラー数、エラー率。`error_rate=0.01` は 1% を意味します
`maps[].avg_resp_time`、`p50`、`p75`、`p90`、`p95`、`p99`	呼び出しエッジの平均応答時間と応答時間のパーセンタイル。レスポンス例では元の数値を保持しています

以下のレスポンス例は、テスト環境の成功レスポンスに含まれる2つの接続ノードと1つの呼び出しエッジです。選択したレコードのフィールドと統計値を保持し、ワークスペース、サービス、ノード ID、traceId はマスキング済みです。フィールドはバージョン、サービス種別、グループ化の方法によって変化します。たとえば、例では最初のノードのみ data.apdex を含みます。フィールドが欠落していても、ゼロ値を意味するわけではありません。エッジの端点が services に含まれない場合があります。この場合も maps の端点情報を保持し、呼び出しエッジを破棄しないでください。 HTTP とビジネスステータスがともに成功し構造が正常な場合、空の services、maps はその時間範囲にトポロジーデータがないことを示します。失敗や構造の欠落を空の結果として扱ってはなりません。複数のワークスペースを集計する場合、元の JSON、失敗したワークスペース、traceId を保持してください。同じ呼び出しエッジが重複して現れる可能性があるため、重複するエッジのリクエスト数や P99 の平均を直接合算しないでください。

フィルター条件¶

filters の例は次のとおりです。

name="__codelineno-0-1">{ "tags": [ { "name": "__tags.__isError.keyword", "value": [ "true" ], "operation": "=", "condition": "and" }, { "condition": "and", "name": "__tags.__serviceName", "operation": "=~", "value": [ ".*04.*" ] } ] }

リクエスト例¶

curl 'https://external-api.guance.com/api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000' \
  -H 'X-Df-Access-Key: <AK>' \
  -H 'X-Df-SVersion: v20240417' \
  -H 'X-Df-Timestamp: <現在の秒タイムスタンプ>' \
  -H 'X-Df-Nonce: <今回のランダム一時コード>' \
  -H 'X-Df-Signature: <最終リクエストパスに基づいて計算された署名>'

Endpoint、ワークスペース、時間範囲を置き換え、有効な署名を生成してください。プレースホルダーはそのまま実行できません。

レスポンス¶

{
    "code": 200,
    "content": {
        "services": [
            {
                "alias": "demo-web",
                "cluster_name_k8s": "",
                "data": {
                    "apdex": 0.9994428969359331,
                    "avg_per_second": 0.7255555555555555,
                    "avg_resp_time": 104885.94027565084,
                    "cluster_name_k8s": "",
                    "env": "",
                    "error_count": 13,
                    "error_rate": 0.0049770290964777945,
                    "key": "demo-web",
                    "language": "",
                    "max_duration": 3819430,
                    "p50": 108049,
                    "p75": 134638,
                    "p90": 174617,
                    "p95": 245331,
                    "p99": 680374,
                    "project": "",
                    "service": "demo-web",
                    "source_type": "web",
                    "sum_resp_time": 273962076,
                    "total_count": 2612,
                    "version": "",
                    "workspace_uuid": "wksp_example_1"
                },
                "filter_matched": true,
                "id": "node_demo_web",
                "name": "demo-web",
                "project": "",
                "type": "web",
                "workspace_name": "示例空间",
                "workspace_uuid": "wksp_example_1"
            },
            {
                "alias": "demo-db",
                "cluster_name_k8s": "",
                "data": {
                    "avg_per_second": 3.873611111111111,
                    "avg_resp_time": 34123.73811401936,
                    "cluster_name_k8s": "",
                    "env": "",
                    "error_count": 3,
                    "error_rate": 0.00021513087128002868,
                    "key": "demo-db",
                    "language": "",
                    "max_duration": 5601590,
                    "p50": 1086,
                    "p75": 1686,
                    "p90": 18220,
                    "p95": 185415,
                    "p99": 591486,
                    "project": "",
                    "service": "demo-db",
                    "source_type": "db",
                    "sum_resp_time": 475855528,
                    "total_count": 13945,
                    "version": "",
                    "workspace_uuid": "wksp_example_1"
                },
                "filter_matched": true,
                "id": "node_demo_db",
                "name": "demo-db",
                "project": "",
                "type": "db",
                "workspace_name": "示例空间",
                "workspace_uuid": "wksp_example_1"
            }
        ],
        "maps": [
            {
                "avg_per_second": 0.0725,
                "avg_resp_time": 1134.478927203065,
                "error_count": 0,
                "error_rate": 0,
                "p50": 267.77212581584365,
                "p75": 1064.416823688738,
                "p90": 1901.1261103999313,
                "p95": 6064.699952926481,
                "p99": 10831.996616037464,
                "source": "demo-web",
                "source_alias": "demo-web",
                "source_cluster_name_k8s": "",
                "source_id": "node_demo_web",
                "source_project": "",
                "source_workspace_name": "示例空间",
                "source_workspace_uuid": "wksp_example_1",
                "sum_resp_time": 296099,
                "target": "demo-db",
                "target_alias": "demo-db",
                "target_cluster_name_k8s": "",
                "target_id": "node_demo_db",
                "target_project": "",
                "target_workspace_name": "示例空间",
                "target_workspace_uuid": "wksp_example_1",
                "total_count": 261
            }
        ]
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-EXAMPLE"
}