APIエラーのアドバンストラブルシューティング構成を使用すると、APIエラー(ヘッダー、リクエスト/レスポンスボディのコンテンツ)に関する詳細情報を収集するルールを作成でき、4XX-5XX範囲内だけでなく、ステータスコードを持つAPIエラーを収集できるため、エラーのトラブルシューティングを迅速に行うことができます。
APIエラーのアドバンストラブルシューティングを使用して:
- HTTPステータスコードが400未満のネットワークリクエストのAPIエラーの収集を設定します。
- セッションリプレイのイベントストリームで次の種類の追加APIエラー詳細を確認します:
- リクエストとレスポンスのHTTPヘッダー
- ボディ(リクエストによって送信されたデータまたはレスポンスで受信したデータ)
- ボディ要素(リクエスト/レスポンスボディの特定の要素)
- リクエストエンドポイントのクエリパラメータ(要求する情報のURL)
- エラーのダッシュボード&アラートおよび分析のコンテキストで、レスポンスボディのコンテンツに基づいてエラーを監視、特定、定量的にするために、暗号化されていないレスポンスボディ要素を活用します。
構成が完了したら、APIエラーのトラブルシューティング詳細を活用する方法についてさらに詳しく学んでください。
個人データの保護
追加するカスタムヘッダーに応じて、トラブルシューティングの詳細には個人データが含まれる可能性があります。誰でも簡単に復号化できないようにデータを保護するために、個人データを含むカスタムヘッダーは暗号化することができますし、すべきです。
ヘッダーとボディ要素は、トラブルシューティングの詳細を公開する際の容易さと速度のために、暗号化されていない状態で収集するオプションがあります。このオプションは、追加するデータポイントに個人データが含まれていないことが確実な場合にのみ使用するべきです。
リクエストおよび/またはレスポンスボディ全体、ならびにクエリパラメータは、暗号化された状態でのみ収集できます。
個人データを含む特定のヘッダー(クッキー、認証、プロキシ認証ヘッダー)を収集することは許可されていません。これらは処理できない機密データを含んでいます。
詳細については、プライバシーと個人データに関する記事をご覧ください。
トラブルシューティングの詳細を暗号化する
暗号化設定の前提条件: 暗号化されたカスタムヘッダーのAPIトラブルシューティング詳細を追加および公開する前に、公開鍵/秘密鍵のペアを事前に設定する必要があります。
暗号化キーの設定に関する 手順はこちらで確認できます.
制限
ウェブ上では、私たちの暗号化メカニズムは、最も人気のあるブラウザによって広くサポートされている2つのブラウザAPI(CryptoKey APIおよびWeb Cryptography API)に依存しています。ただし、一部のブラウザや古いブラウザのバージョンはこれらをサポートしていません。その場合、タグは暗号化されたデータの収集を進めません。
APIエラーのトラブルシューティングタブの概要
1. プロファイルアイコンをクリックしてコンソールに移動し、次に'コンソール'をクリックします。
2. 'アドバンスエラーのトラブルシューティング'タブをクリックします。
APIエラー収集ルールの概要
リストされた各ルールについて、次の情報を確認できます(左から右へ):
- ルール名
- ルールのステータスコード
- リクエストURL
- ルールが作成された日付と最終更新日(および著者の名前)
新しいルールを作成するか、既存のルールを編集するかを決定するために、以下のアクションを使用してください:
- ルールを検索: 名前に含まれる用語やドメインのステータスコードに基づいて既存のルールを検索します。
- ルールを並べ替え: カラムの見出しをクリックして、名前、ステータスコード、ドメイン、または日付(作成日または最終更新日)でルールを並べ替えます。
-
ルールの詳細を表示: ルールの右側にある“目”アイコンをクリックしてサイドパネルを開き、収集条件と収集されたデータポイントを確認します。
「デフォルトルール」
このルールは、4XX-500範囲のステータスコードを持つすべてのネットワークリクエストを収集するデフォルトの行動を表し、デフォルトのデータポイント(リクエストURL、ステータスコード、メソッド)のみを持ちます。編集または削除することはできません。
定義済みルール
これらの定義済みルールは、すでにプロジェクトに含まれており、APIエラーおよびAPIエラーの詳細を自動的に収集することを可能にします:
- GraphQL: このルールは、通常はステータスコードが200であるためデフォルトでは収集されない基本的なGraphQLエラーを収集するために設計されています。このルールは必要に応じて編集および削除できます。
- すべてのエンドポイントのヘッダー: このルールは、すべてのAPI 4XX-5XXエラーのヘッダー収集を設定するために使用されます。ヘッダーのリストは編集できますが、ルールは削除できません。
新しいルールの作成
ステップ1: ルールの名前付けと条件の追加
1. ‘+ 新しいルール’ボタンをクリックします。
2. ルール名: ルール名フィールドにルールの名前を付けます。この名前は一意でなければなりません。
3. リクエストURL: ルールは、URLがフィールドに追加した値を含むすべてのリクエストに一致します。注意してください、他の既存のルールと全く同じ条件のコレクションを使用することはできません。
例(リクエストURLに一致させたい場合): https://subdomain.domain.com/path/sub-path?query=param
次の値が一致します:
- 完全なURL: https://subdomain.domain.com/path/sub-path?query=param
- ドメイン&HTTPプロトコル: https://subdomain.domain.com
- ドメインのみ: domain.com
- パスのみ: /path/sub-path
- ドメイン + パス: subdomain.domain.com/path/sub-path
4. ステータスコード: 4XX-5XXグループを選択してHTTPステータスコードのエラーをカバーするか、特定のステータスコードを定義できます。
5. レスポンスボディコンテンツ: このルールが収集されるために、ボディコンテンツフィールドにレスポンスのボディに書かれるべき内容を指定します。最大64文字を入力できます。このフィールドはすべてのステータスコードに対してオプションですが、「200」ステータスコードが指定されている場合は、エラーを特定するためにレスポンスボディコンテンツを指定する必要があります。これは、すべてのネットワークリクエストをAPIエラーとして収集するのを避けるために行われます。
レスポンスボディコンテンツのロジックと制限
これはフィルタリングロジックであり、ロジックは「含む」ため、正確なテストは必要ありません。レスポンスボディコンテンツは大文字と小文字を区別しません(「invalid」は「INVALID_CODE」のような値に一致します)。
例:
レスポンスにエラーが含まれているときにリクエストを収集したい。
レスポンスボディサンプル:
{ "errors": [ { "message": "Cannot query field 'age' on type 'Customer'.", "code": "1003" } ], "data": { "customer": { "id": "123", "name": "John Doe" } } }
使用するボディコンテンツ値: errors
使用するボディコンテンツ値(特殊文字を含む): errors\"\:\[\{
レスポンスボディコンテンツの制限:
- Androidモバイルアプリでは、レスポンスボディが最大1MBの場合にボディコンテンツの一致が機能します。
- iOSモバイルアプリでは、レスポンスボディコンテンツサイズに制限はありません。
- ウェブでは、レスポンスボディコンテンツサイズに制限はありません。
6. ‘次へ’をクリックしてルールの作成を継続します。
ステップ2: 収集したデータポイントの追加
名前、条件、リクエストURLをルールに入力した後(ステータスコードが200の場合はボディコンテンツも)、収集したデータポイントを追加できます。デフォルトでは、ContentsquareはリクエストURL、ステータスコード、およびメソッドを収集します。
ヘッダー
1. “+ 追加”をクリックします。注意してください、同じ条件(リクエストまたはレスポンス、暗号化または非暗号化)を共有する場合は、「+」ボタンをクリックして複数のヘッダーを一度に追加できます。
2. ヘッダー名を入力します。
3. 暗号化:
- 暗号化が設定されている場合、デフォルトの状態は「暗号化済み」になります。ヘッダーを暗号化されていない状態で収集するには、オフに切り替えてください。
- 暗号化が設定されていない場合、ヘッダーは暗号化されていない状態でのみ収集できます。個人情報を含むヘッダーを収集しないようにしてください。
4. デフォルトでは「リクエスト」が選択されています。これを更新して、代わりにレスポンスを収集することができます。
5. 「適用」をクリックします。
ボディ要素
JSON形式でリクエストまたはレスポンスボディの特定の要素を収集することで、活用したいデータポイントに対する柔軟性を高めることができます。JSON Pathベースのクエリ言語を使用してください。
注: ボディ要素を編集することはできませんが、削除して再作成することはできます。
JSON Pathの長さは60文字に制限されています。
分析のためのレスポンスボディ要素
エラーのグループ化やフィルタリング(分析のコンテキスト内)およびダッシュボードウィジェットやアラートの作成に使用される、暗号化されていない状態で収集されるレスポンスボディの要素です。
分析のために収集するレスポンスボディ要素を定義するには:
1. 「+ 追加」をクリックします。
2. 収集したい要素のJSONパスを入力します。「+」ボタンをクリックすることで、複数のエントリを一度に追加することもできます。
3. 「適用」をクリックします。
トラブルシューティングのためのレスポンスボディ要素
セッションリプレイの個別イベントレベルで表示される、トラブルシューティングのために収集したいリクエスト/レスポンスボディの要素です。
トラブルシューティングのために収集するレスポンスボディ要素を定義するには:
1. 「+ 追加」をクリックします。
2. 収集したい要素のJSONパスを入力します。「+」ボタンをクリックすることで、複数のエントリを一度に追加することもできます。
3. 暗号化:
- 暗号化が設定されている場合、デフォルトの状態は「暗号化済み」になります。ボディ要素を暗号化されていない状態で収集するには、オフに切り替えてください。
- レスポンスの場合: トラブルシューティングのためのボディ要素は暗号化された状態でのみ収集でき、暗号化されていないレスポンスボディ要素は分析のために追加されます(上記のセクションにて)。
- 暗号化が設定されていない場合、リクエストボディ要素のみが暗号化されていない状態で収集できます。個人情報を含むボディ要素を収集しないようにしてください。
4. デフォルトでは「レスポンス」が選択されています。レスポンスまたはリクエストのボディ要素を収集することができます。
5. 「適用」をクリックします。
サポートされているボディの種類
ボディ要素のコレクションは、以下の条件の下でリクエスト/レスポンスボディに対して利用可能です:
ウェブ | モバイルアプリ |
‘content-type’ヘッダーは‘application/json’または‘application/graphql’に設定する必要があります | ボディフォーマットは任意のJSONタイプである必要があります |
サイズは64,000バイト未満でなければなりません | サイズは64,000バイト未満でなければなりません |
ボディ要素の例:
“errors[0].message”は暗号化されていないエラーメッセージを収集します
“errors[0].code”は暗号化されていないエラーコードを収集します
“data.emailAddress”は個人データとして暗号化されたEメールアドレスを収集します
全体のボディ(暗号化済み)
リクエストまたはレスポンスボディ、またはその両方を収集するためにボックスにチェックを入れてください。表示または追跡できない機密データを含むエンドポイントやフィールドを含めないようにしてください。この情報は許可されていません。
サポートされているボディの種類と制限
ウェブ | モバイルアプリケーション |
application/json |
SDKは、フォーマットに関係なくボディを文字列として解析しようとします
|
全体のボディコレクションの制限:
リクエストボディは、そのサイズが64 KBを超えない場合に収集されます。
レスポンスボディは、そのサイズが5 KBを超えない場合に収集されます
クエリパラメータ(暗号化済み)
クエリパラメータを収集するためにボックスにチェックを入れてください。クエリパラメータは、そのサイズが2 KBを超えない場合に収集されます。
デフォルトデータポイント
デフォルトでは、リクエストURL、ステータスコード、メソッドを収集します。
ルールの編集と削除
ルールリストから、ルールの右側にある“目”アイコンをクリックしてルールサイドパネルを開きます。
編集するには:
1. ルール名または条件セクションの鉛筆アイコンをクリックします。
2. ステップ1でルールモーダルを開きます。
3. 収集されたデータポイントセクションの鉛筆アイコンをクリックして、ステップ2でルールモーダルを開きます。
4. 任意の変更を適用します。
5. 必要に応じて他のモーダルに移動して追加の変更を適用します。
6. “保存”をクリックして変更を適用します。
削除するには:
1. 下部の“ルールを削除”ボタンをクリックします。
2. “削除”を再度クリックして削除アクションを確認します。
よくある質問
エラーのトラブルシューティングの詳細を遡って追跡できますか?
いいえ、エラーのトラブルシューティングの詳細は、セットアップが定義された後にのみ収集されます。
リクエストが承認された制限を超えた場合はどうなりますか?
以下の制限を持つ3つのデータポイントがあります:
- クエリパラメータの制限:2 KB
- リクエストボディサイズの制限:64 KB
- レスポンスボディサイズの制限:5 KB
これらのデータポイントはそれぞれ独立して評価されます。制限に達した場合、データは収集されません。それぞれについて、"..."を暗号化されずにプッシュします。これはリプレイのトラブルシューティングの詳細に反映されます。
リクエストまたはレスポンスボディが復号化後もエンコードされているように見えるのはなぜですか?
これは、リクエストにTransfer-Encoding
がgzip
に設定されている場合に発生する可能性があります。Chrome DevToolsは自動的にボディを解凍するため、使用しているときには目立ちません。しかし、プレイヤートラブルシュートモーダルで見ると、ボディは自動的に解凍されません。サードパーティツールを使用して、復号化後に解凍することができます。