フロントエンド・バックエンド連携トレースによる API エラーの診断 - Application Real-Time Monitoring Service

ブラウザ監視では API リクエストの応答時間は表示されますが、ネットワークパフォーマンスやバックエンドの呼び出しトレースは可視化されないため、API の問題のトラブルシューティングが困難です。フロントエンド・バックエンド連携トレースは、フロントエンドの API 呼び出しをバックエンドのトレース全体にリンクさせることでこの問題を解決し、リクエストのライフサイクル全体を可視化します。

前提条件

Application Real-Time Monitoring Service (ARMS) のブラウザ監視とアプリケーション監視を有効化済みであること。詳細については、「ARMS の有効化」をご参照ください。ARMS のアプリケーション監視には、バージョン 2.4.5 以降が必要です。設定の詳細については、「アプリケーション監視とは」をご参照ください。

背景情報

アプリケーション監視では、バックエンド API のパフォーマンスと呼び出しトレースは明らかになりますが、実際のユーザーエクスペリエンスはわかりません。ブラウザ監視では、API リクエストの合計時間とステータスのみが表示され、バックエンドの詳細は省略されます。フロントエンド・バックエンド連携トレースは、フロントエンドのユーザー操作をバックエンドサービスにリンクさせることでこのギャップを埋め、統一されたエンドツーエンドのトラブルシューティング体験を創出します。

ARMS ブラウザ監視の設定

同一オリジン API リクエスト

フロントエンドサイトとバックエンドアプリケーションの間にマッピングが存在することを確認します。
API の自動レポートが有効になっていることを確認します。

enableLinkTrace パラメーターを true に設定して、フロントエンド・バックエンド連携トレースを有効にします。以下のコードは設定例です。

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxx",imgUrl:"https://arms-retcode.aliyuncs.com/r.png?", enableLinkTrace: true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
</script>

クロスオリジン API リクエスト

フロントエンドサイトとバックエンドアプリケーションの間にマッピングが存在することを確認します。

enableLinkTrace と enableApiCors パラメーターを true に設定します。

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxx",imgUrl:"https://arms-retcode.aliyuncs.com/r.png?", 
enableLinkTrace: true, enableApiCors: true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
</script>

重要

enableApiCors パラメーターを true に設定した場合、バックエンドサービス側でもクロスオリジンリクエストとカスタムヘッダー値をサポートする必要があります。統合テスト中にすべてのリクエストが正しく動作することを確認してください。そうしない場合、リクエストが失敗する可能性があります。以下に Nginx の設定例を示します。

upstream test {
        server 192.168.220.123:9099;
        server 192.168.220.123:58080;
    }
    server {
        listen    5800;
        server_name  192.168.220.123;
        root         /usr/share/nginx/html;
        include /etc/nginx/default.d/*.conf;
        location / {
            proxy_pass http://test;
            proxy_set_header Host $host:$server_port;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Real-PORT $remote_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   EagleEye-TraceID $eagleeye_traceid;
            proxy_set_header   EagleEye-SessionID $eagleEye_sessionid;
            proxy_set_header   EagleEye-pAppName $eagleeye_pappname;
        }

ignore の設定については、「ignore」をご参照ください。設定は以下の通りです。

let whitelist = ['api.xxx','source3']; // ホワイトリスト。
let blacklist = ['source2','source6']; // ブラックリスト。
// ニーズに応じて、関数内で true または false を返すことで、ホワイトリストまたはブラックリストを選択します。
ignore: {
            ignoreApis: [
                function(str) {   // 関数。
                    if (whitelist.includes(str)) {
                        return false;
                    }
                    return true; // true を返すと無視されます。
                }]
         }

説明

ignore パラメーターはホワイトリストまたはブラックリストとして機能します。特定サードパーティリソースへのリクエストに対するヘッダーの変更を防ぎ、リクエストエラーを回避するのに役立ちます。

仕組み

API の自動レポートが有効になっている場合、SDK は同一オリジンに送信される API リクエストに `EagleEye-TraceID` と `EagleEye-SessionID` という 2 つのカスタムヘッダーを追加します。
API リクエストが異なるオリジンに送信される場合、SDK はこれらのカスタムヘッダーを追加しません。これにより、クロスオリジンリクエストがエラーなく送信されることが保証されます。
フロントエンド・バックエンド連携トレースの設定が有効であることを確認するには、ブラウザの開発者コンソールを開き、API 呼び出しのリクエストヘッダーを検査します。`EagleEye-TraceID` と `EagleEye-SessionID` ヘッダーが存在すれば、この機能は有効です。

警告
`EagleEye-TraceID` と `EagleEye-SessionID` の値には特定の意味があり、自動的に生成されます。手動で生成しないでください。

利用シーンと例

タイムラインは、高レイテンシーがネットワーク転送に起因するのか、バックエンドプロセスに起因するのかを判断するのに役立ちます。バックエンドアプリケーションのメソッドスタックをクリックすると、リクエストの完全なバックエンド呼び出しトレースが表示されます。

API がエラーコードを返すか、ビジネスロジックエラーが発生した場合、以下の手順で原因を特定します。
1. ARMS コンソールにログインします。左側のナビゲーションウィンドウで、ブラウザ監視 > ブラウザ監視を選択します。
2. ブラウザ監視ページで、上部のナビゲーションバーでリージョンを選択し、管理したいアプリケーションの名前をクリックします。
3. 左側のナビゲーションウィンドウで、API リクエストをクリックします。
4. 右側の [API リンクトレース (TOP 20)] セクションで、[API 失敗リスト] で関連する API またはトレース ID を見つけ、操作列で Tracing Analysis をクリックします。ビューが開き、フロントエンドの全体時間とバックエンド呼び出しのタイムラインが表示されます。
  
  トレース結果は、[呼び出しトレース] タブのテーブルに表示されます。列には、アプリケーション名、ログ時刻、ステータス、IP アドレス、呼び出しタイプ、サービス名、メソッドスタック、スレッドプロファイリング、タイムラインが含まれます。このテーブルでは、呼び出しタイプ (ブラウザや HTTP エントリなど)、ステータス (赤点はエラー、緑点は成功を示します)、および各スパンが要した時間の比較を確認できます。
5. タイムラインを使用して、高レイテンシーがネットワーク転送によるものか、バックエンド処理によるものかを判断します。
6. バックエンドアプリケーションについては、[メソッドスタック] 列の虫眼鏡アイコンをクリックして、このリクエストの完全なバックエンド呼び出しトレースを表示します。その後、ビジネスロジックに基づいて API エラーの原因を特定できます。
  
  呼び出しトレース詳細パネルには、各メソッドの呼び出し階層、行番号、拡張情報、およびタイムライン (ミリ秒単位) を示すテーブルが表示されます。レイテンシーが異常に高いメソッド名は赤色でハイライトされ、右側の青いバーは各メソッドの時間割合を視覚化し、パフォーマンスボトルネックを迅速に特定するのに役立ちます。
API リクエストのレイテンシーが高い場合、以下の手順で原因を特定します。
1. ARMS コンソールにログインします。左側のナビゲーションウィンドウで、ブラウザ監視 > ブラウザ監視を選択します。
2. ブラウザ監視ページで、上部のナビゲーションバーでリージョンを選択し、管理したいアプリケーションの名前をクリックします。
3. 左側のナビゲーションウィンドウで、API リクエストをクリックします。
4. 右側の API リンクのトレース (TOP 20) セクションで、API をリクエスト期間の降順でソートし、レイテンシーの高い API またはトレース ID を見つけます。
5. [操作] 列の Tracing Analysisリンクをクリックして、フロントエンドの全体時間とバックエンド呼び出しのタイムラインを表示します。
  - バックエンドの処理時間が短いにもかかわらず、全体の応答時間が長い場合は、ネットワークのレイテンシーが高いことを示しています。この場合、[詳細の表示] をクリックして、ネットワーク、リージョン、ブラウザ、デバイス、オペレーティングシステムなどのセッション詳細を検査します。
  - バックエンドの処理時間が長い場合は、パフォーマンスが低いことを示しています。[メソッドスタック] 列の虫眼鏡アイコンをクリックします。ローカルメソッドスタックのダイアログボックスで、バックエンドトレースを調べて最も時間のかかっている部分を見つけ、問題を特定します。