Apigee Edge は、API を介して送受信される幅広い運用データやビジネスデータを記録します。こうしたデータから得られる指標は、運用のモニタリングやビジネスのモニタリングに役立ちます。Edge API Analytics を使用すると、たとえばパフォーマンスが高いまたは低い API、大量のトラフィックを送信しているデベロッパー、バックエンド サービスで多くの問題を起こしているアプリを判別できます。
Edge ではこのような指標データに容易にアクセスできるよう、RESTful API を公開しています。自動化クライアントやスクリプトを使用して定期的に指標を取得するなど、特定のアナリティクス機能を自動化する必要がある場合は、この指標 API を利用できます。また、この API を使用して、カスタム ウィジェットという形で独自の可視化機能を作成し、そのウィジェットをポータルやカスタムアプリに埋め込むこともできます。
API Edge 管理 UI で Analytics を使用する方法については、API Analytics の概要をご覧ください。
指標 API について
Edge では次の 2 つの指標 API を用意しています。
Get metrics は、一定の期間（1 時間、1 日、1 週間など）にわたる組織と環境の指標を返します。
たとえば、前の週について次の指標を取得できます。
- ポリシーエラー数
- 平均応答時間
- トラフィックの総量
Get metrics organized by dimensions は、一定の期間にわたる組織と環境の指標を、ディメンション別にグループ分けして返します。
たとえば、ディメンションを使用して、前の週についての次の指標を API プロダクト、API プロキシ、デベロッパーのメールごとにグループ分けして取得できます。
- API プロダクトあたりのポリシーエラー数
- API プロキシあたりの平均応答時間
- デベロッパーのメールアドレスあたりのトラフィック総量
Get metrics organized by dimensions API は、Get metrics API ではサポートされていない次の機能をサポートしています。
指標 API の割り当てについて
Edge では、これらの呼び出しに次の割り当てが適用されます。呼び出しを処理する次のバックエンド サービスごとに割り当てが決められています。
- Postgres: 1 分あたり 40 回の呼び出し
- BigQuery: 1 分あたり 12 回の呼び出し
呼び出しを処理するバックエンド システムを確認するには、レスポンス オブジェクトを調べます。すべてのレスポンス オブジェクトには metaData プロパティがあり、Source プロパティで呼び出しを処理したサービスがリストされています。Postgres の場合の例を次に示します。
{
...
"metaData": {
"errors": [],
"notices": [
"Source:Postgres",
"Table used: xxxxxx.yyyyy",
"query served by:111-222-333"
]
}
}
BigQuery の場合、Source プロパティは次のようになります。
"Source:Big Query"
呼び出しの割り当てを超えた場合、API は HTTP 429 レスポンスを返します。
Management API を使用して指標を取得する
Get metrics API と Get metrics organized by dimensions API の間の主な違いは、前者は組織と環境全体の指標を未加工のまま返すのに対し、後者の API を使用すると、エンティティ タイプ（API プロダクト、デベロッパー、アプリなど）ごとに指標をグループ分けできるという点です。
Get metrics API のリクエスト URL は次のとおりです。
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats
Get metrics organized by dimensions API の場合、URL の /stats の後に、目的のディメンションを指定するリソースを追加します。
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension
たとえば、API プロキシごとにグループ分けされた指標を取得するには、次の URL を使用して Management API を呼び出します。
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy
返される指標を指定する
Get metrics API と Get metrics organized by dimensions API では、どちらも select クエリ パラメータを使用して、取得する指標とオプションの集計関数を指定します。形式は次のとおりです。
?select=metric
または
?select=aggFunction(metric)
ここで
- metric で、返されるデータを指定します。たとえば、API リクエスト数、キャッシュ ヒット数、またはポリシーエラー数を指定します。
selectクエリ パラメータで使用する指標の名前が明記されている表については、指標をご覧ください。 aggFunction で、指標に対して実行するオプションの集計関数を指定します。たとえば、処理レイテンシ指標では次の集計関数を使用できます。
avg: 平均処理レイテンシを返します。min: 最小処理レイテンシを返します。max: 最大処理レイテンシを返します。-
sum: すべての処理レイテンシの合計を返します。
すべての指標ですべての集計関数がサポートされるわけではありません。指標の名前と各指標でサポートされる関数（
sum、avg、min、max）が示されている表については、指標のドキュメントをご覧ください。
たとえば、1 秒あたりの平均トランザクション数、つまり API プロキシ リクエスト数を返すには、次のようにします。
?select=tps
上記の例に、集計関数は必要ありません。次の例では、集計関数を使用してキャッシュ ヒット数の合計を返します。
?select=sum(cache_hit)
1 回の API 呼び出しで複数の指標を返すこともできます。ポリシーエラーの合計数とリクエストの平均サイズの指標を取得するには、次のように指標のカンマ区切りリストを使用して select クエリ パラメータを設定します。
?select=sum(policy_error),avg(request_size)
期間を指定する
指標 API は指定された期間のデータを返します。期間を指定するには、次の形式の timeRange クエリ パラメータを使用します。
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
HH:MM の前にある %20 に注意してください。timeRange パラメータでは、MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM のように、HH:MM の前に URL エンコードされたスペース文字（+ 文字）を入れる必要があります。
例:
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
時刻として 24:00 を使用しないでください。24:00 は 00:00 に戻されるためです。代わりに 23:59 を使用してください。
API 呼び出しのサンプル
このセクションでは、Get metrics API と Get metrics organized by dimensions API を使用した例を記載します。他の例については、指標 API の例をご覧ください。
1 か月間に行われた API 呼び出しの合計数を返す
組織と環境で 1 か月間に行われた、すべての API に対する呼び出しの合計数を確認するには、次のように Get metrics API を使用します。
curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password
レスポンスの例:
{
"environments": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
"7.44944088E8"
]
}
],
"name": "prod"
}
],
...
}
2 日間にわたる API プロキシあたりのメッセージ合計数を取得する
この例では、すべての API プロキシが 2 日間にわたって受信したリクエストの合計数の指標を返します。select クエリ パラメータでは、apiproxy ディメンションの message_count 指標に対する集計関数 sum を定義しています。レポートは、UTC 時間の 2018 年 6 月 20 日から 2018 年 6 月 21 日までに受信したトラフィックを対象とした、すべての API のリクエスト メッセージ スループットを返します。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password
レスポンスの例:
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1498003200000,
"value" : "1100.0"
} ]
} ],
"name" : "target-reroute"
} ],
"name" : "test"
} ]...
}
このレスポンスには、2018 年 6 月 20 日から 2018 年 6 月 21 日までに、テスト環境で実行中の「target-reroute」という 1 つの API プロキシで 1,100 個のメッセージを受信したことが示されています。
他のディメンションの指標を取得するには、目的のディメンションを URI パラメータとして指定します。たとえば、developer_app ディメンションを指定すると、デベロッパー アプリに関する指標を取得できます。次の API 呼び出しにより、すべてのアプリを対象とした、指定された期間の合計スループット（受信メッセージ数）が返されます。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password
レスポンスの例:
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "886.0"
}
]
}
],
"name": "Test-App"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "6645.0"
}
]
}
],
"name": "johndoe_app"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "1109.0"
}
]
}
],
"name": "marys_app"
}
]...
}
相対ランキングを基準に結果を並べ替える
指標を取得するときに、データのすべてのセットではなく、その一部の結果を取得したい場合がよくあります。通常は、「最も処理速度が遅い 10 個の API」、「最もアクティブな 10 個のアプリ」といったように「上位 10」の結果を取得することが必要になります。それには、リクエストの一部として topk クエリ パラメータを使用します。
たとえば、スループットに基づいて測定した上位のデベロッパーや、レイテンシに基づいて測定した最もパフォーマンスが低い（つまり、最も処理速度の遅い上位の）ターゲット API などを把握したいことがあります。
topk（「上位 K」のエンティティ）を使用すると、特定の指標の最大値に関連付けられているエンティティに関するレポートを作成できます。これにより、指標をフィルタリングして、特定の条件の好例となるエンティティをリストできます。たとえば、過去 1 週間にわたり、最もエラーが起こりやすかったターゲット URL を調べるには、値を 1 に設定した topk パラメータをリクエストの末尾に追加します。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
-u email:password
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(is_error)",
"values": [
{
"timestamp": 1494201600000,
"value": "12077.0"
}
]
}
],
"name": "http://api.company.com"
}
]...
}
このリクエストの例では、最もバグが多い URL は http://api.company.com であることを示す一連の指標が返されます。
topk パラメータを使用して API を並べ替えて、最もスループットが高い API を確認することもできます。次の例では、過去 1 週間のスループットに基づき、上位にランキングされる API の指標を取得しています。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password
レスポンスの例
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1494720000000,
"value": "5750.0"
},
{
"timestamp": 1494633600000,
"value": "5752.0"
},
{
"timestamp": 1494547200000,
"value": "5747.0"
},
{
"timestamp": 1494460800000,
"value": "5751.0"
},
{
"timestamp": 1494374400000,
"value": "5753.0"
},
{
"timestamp": 1494288000000,
"value": "5751.0"
},
{
"timestamp": 1494201600000,
"value": "5752.0"
}
]
}
],
"name": "testCache"
}
],
"name": "test"
}
]...
}
結果をフィルタリングする
粒度を細かくするには、結果をフィルタリングして、返されるデータを制限するという方法があります。フィルタを使用する場合は、フィルタのプロパティとしてディメンションを使用する必要があります。
たとえば、HTTP リクエストの動詞を基準にフィルタリングして、バックエンド サービスのエラー数を取得するとします。目標は、バックエンド サービス別に、エラーの原因となった POST リクエストと PUT リクエストの数を調べることです。それには、フィルタ request_verb でディメンション target_url を使用します。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password
レスポンスの例:
{
"environments" : [
{
"dimensions" : [
{
"metrics" : [
{
"name" : "sum(is_error)",
"values" : [
{
"timestamp" : 1519516800000,
"value" : "1.0"
}
]
}
],
"name" : "testCache"
}
],
"name" : "test"
}
]...
}
結果をページ分割する
本番環境では、Edge Analytics API に対するリクエストによっては大量のデータセットが返されることがあります。UI ベースのアプリケーションのコンテキストで大量のデータセットを表示しやすくするために、この API ではページ分割をネイティブ サポートしています。
結果をページ分割するには、クエリ パラメータ offset と limit を使用し、さらに 並べ替えパラメータ sortby を使用して項目が一貫して順序付けられるようにします。
たとえば、次のリクエストでは過去 1 週間に本番環境のすべての API で発生したすべてのエラーの指標を取得するため、おそらく大量のデータが返されます。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password
UI ベースのアプリケーションでページあたり 50 件の結果を無理なく表示できる場合、limit クエリ パラメータの値を 50 に設定できます。0 は最初の項目として数えられるため、次の呼び出しでは項目 0～49 が降順で返されます（sort=DESC がデフォルトです）。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password
結果の 2 ページ目については、offset クエリ パラメータを次の例に示すように使用します。limit と offset が同一であることに注目してください。これは、0 は最初の項目として数えられるためです。上記の URL では limit の値が 50、offset の値が 0 に設定されているため、項目 0～49 が返されます。offset の値を 50 に設定することで、項目 50～99 が返されます。
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password