翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # CloudWatch を使用した GraphQL API データのモニタリングとログ CloudWatch メトリクスと CloudWatch ログを使用して、GraphQL API のログとデバッグを行うことができます。これらのツールにより、デベロッパーはパフォーマンスのモニタリング、問題のトラブルシューティング、GraphQL オペレーションの最適化を効果的に行うことができます。 CloudWatch メトリクスは、API のパフォーマンスと使用状況をモニタリングするための幅広いメトリクスを提供するツールです。これらのメトリクスは、2 つの主なカテゴリに分類されます。 1. **一般的な API メトリクス**: これには、クライアントとサーバーのエラーを追跡するための `4XXError` および `5XXError`、レスポンスタイムを測定するための `Latency`、API コールの合計をモニタリングするための `Requests`、リソース使用状況を追跡するための `TokensConsumed` が含まれます。 1. **リアルタイムサブスクリプションメトリクス**: これらのメトリクスは、WebSocket 接続とサブスクリプションアクティビティに焦点を当てています。これには、接続リクエスト、成功した接続、サブスクリプション登録、メッセージ発行、アクティブな接続とサブスクリプションのメトリクスが含まれます。 このガイドでは、リゾルバーのパフォーマンス、データソースインタラクション、個々の GraphQL オペレーションに関するより詳細なデータを提供する拡張メトリクスも紹介しています。これらのメトリクスは、より深いインサイトを提供しますが、追加コストが発生します。 CloudWatch Logs は、GraphQL API のログ機能を有効にするツールです。ログは API の 2 つのレベルで設定できます。 1. **リクエストレベルのログ**: HTTP ヘッダー、GraphQL クエリ、オペレーションの概要、サブスクリプション登録など、全体的なリクエスト情報をキャプチャします。 1. **フィールドレベルのログ**: リクエストとレスポンスのマッピング、各フィールドのトレース情報など、個々のフィールド解決に関する詳細情報を提供します。 ログ記録の設定、ログエントリの解釈、トラブルシューティングと最適化にログデータを使用できます。 AWS AppSync には、クエリの実行、解析、検証、フィールド解決データを明らかにするさまざまなログタイプが用意されています。 ## セットアップと設定 GraphQL API で自動ログ記録を有効にするには、 AWS AppSync コンソールを使用します。 1. にサインイン AWS マネジメントコンソール し、[AppSync コンソール](https://console.aws.amazon.com/appsync/)を開きます。 1. **API**] ページで、GraphQL API の名前を選択します。 1. API のホームページのナビゲーションペインで、**[設定]** を選択します。 1. [**ログ記録**] で以下を行います。 1. **[ログを有効にする]** をオンにします。 1. リクエストレベルの詳細なロギングを行うには、**[詳細な内容を含める]** のチェックボックスをオンにします。(オプション) 1. **[フィールドリゾルバーのログレベル]** で、希望するフィールドレベルのロギングレベル (**[なし]**、**[エラー]**、**[情報]**、**[デバッグ]** または **[すべて]**) を選択します。(オプション) 1. **既存のロールを作成または使用する**で、**新しいロール**を選択して、 AWS AppSync が CloudWatch にログを書き込むことを許可する新しい AWS Identity and Access Management (IAM) を作成します。または、**[既存のロール]** を選択して、 AWS アカウント内の既存の IAM ロールの Amazon リソースネーム (ARN) を選択します。 1. **[保存]** を選択します。 ### 手動での IAM ロールの設定 既存の IAM ロールを使用する場合、ロールは CloudWatch にログを書き込むために必要なアクセス許可を AWS AppSync に付与する必要があります。これを手動で設定するには、 AWS AppSync がログを書き込むときにロールを引き受けることができるように、サービスロール ARN を指定する必要があります。 [IAM コンソール](https://console.aws.amazon.com/iam)で、`AWSAppSyncPushToCloudWatchLogsPolicy` という名前の新しいポリシーを、以下の定義で作成します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": "*" } ] } ``` ------ 次に、**AWSAppSyncPushToCloudWatchLogsRole** という名前で新しいロールを作成し、新しく作成したポリシーをこのロールにアタッチします。このロールの信頼関係を次のように編集します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "appsync.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ ロール ARN をコピーし、 AWS AppSync GraphQL API のログ記録を設定するときに使用します。 ## CloudWatch メトリクス CloudWatch メトリクスを使用して、HTTP ステータスコードやレイテンシーの原因となる特定のイベントを監視し、アラートを出すことができます。以下のメトリクスが出力されます。 ### メトリクスのリスト `4XXError` クライアントの設定が正しくないためにリクエストが無効になったために発生するエラー。通常、GraphQL を実行する外部の任意の場所で、これらのエラーが発生します。たとえば、このエラーは、リクエストに誤った JSON ペイロードまたは誤ったクエリが含まれている場合、サービスがスロットリングされている場合、または Auth 設定が誤って構成されている場合に発生する可能性があります。 **単位**: **カウント これらのエラーの出現総数を取得するために、Sum 統計を使用します。 `5XXError` GraphQL クエリの 実行中に発生したエラー。例えば、空のスキーマや不正確なスキーマに対してクエリを実行した場合に発生する可能性があります。また、Amazon Cognito ユーザープール ID または AWS リージョンが有効でない場合にも発生する可能性があります。また、リクエストの処理中に AWS AppSync で問題が発生した場合にもこれが発生することがあります。 **単位**: **カウント これらのエラーの出現総数を取得するために、Sum 統計を使用します。 `Latency` AWS AppSync がクライアントからリクエストを受信してからクライアントにレスポンスを返すまでの時間。エンドデバイスに到達するレスポンスに発生したネットワークレイテンシーは含まれません。 **単位**: *ミリ秒* 予測されるレイテンシーを評価するために Average 統計を使用します。 `Requests` アカウント内のすべての API が処理したリクエスト (クエリ \$1 ミューテーション) の数 (リージョン別)。 **単位**: **カウント 特定のリージョンで処理されたすべてのリクエストの数。 `TokensConsumed` トークンは、`Request` が使用するリソースの量 (処理時間と使用量) に基づいて `Requests` に割り当てられます。通常、それぞれの `Request` が 1 つのトークンを消費します。ただし、`Request` が大量のリソースを消費する場合には、必要に応じて追加のトークンが割り当てられます。 **単位**: **カウント 特定のリージョンで処理されたリクエストに割り当てられるトークンの数。 `NetworkBandwidthOutAllowanceExceeded` AWS AppSync コンソールのキャッシュ設定ページで、**キャッシュヘルスメトリクス**オプションを使用すると、このキャッシュ関連のヘルスメトリクスを有効にできます。 スループットが集約された帯域幅制限を超えたためにドロップされたネットワークパケット。これは、キャッシュ設定のボトルネックを診断するのに役立ちます。データは、`appsyncCacheNetworkBandwidthOutAllowanceExceeded` メトリクスで `API_Id` を指定することで、特定の API に記録されます。 **単位**: **カウント ID で指定された API の帯域幅制限を超えた後にドロップされたパケットの数。 `EngineCPUUtilization` AWS AppSync コンソールのキャッシュ設定ページで、**キャッシュヘルスメトリクス**オプションを使用すると、このキャッシュ関連のヘルスメトリクスを有効にできます。 Redis OSS プロセスに割り当てられた CPU 使用率 (パーセンテージ)。これは、キャッシュ設定のボトルネックを診断するのに役立ちます。データは、`appsyncCacheEngineCPUUtilization` メトリクスで `API_Id` を指定することで、特定の API に記録されます。 **単位**: *パーセント*。ID で指定された API の Redis OSS プロセスで現在使用されている CPU の割合。 ### リアルタイムサブスクリプション すべてのメトリクスは、**GraphQLAPIId** という 1 つのディメンションで出力されます。これは、すべてのメトリクスが GraphQL API ID と結合されていることを意味します。次のメトリクスは、純粋な WebSocket を介した GrapQL サブスクリプションに関連しています。 #### メトリクスのリスト `ConnectRequests` 成功した試行と失敗した試行の両方を含む AWS AppSync、 に対して行われた WebSocket 接続リクエストの数。 **単位**: **カウント 接続リクエストの総数を取得するために Sum 統計を使用します。 `ConnectSuccess` AWS AppSync への成功した WebSocket 接続の数。サブスクリプションなしで接続することは可能です。 **単位**: **カウント 成功した接続の出現総数を取得するために、Sum 統計を使用します。 `ConnectClientError` クライアント側のエラーが原因で AWS AppSync によって拒否された WebSocket 接続の数。これは、サービスがスロットリングされているか、承認設定が正しく構成されていないことを意味する可能性があります。 **単位**: **カウント クライアント側の接続エラーの出現総数を取得するために、Sum 統計を使用します。 `ConnectServerError` 接続の処理中に AWS AppSync から発生したエラーの数。これは通常、予期しないサーバー側の問題が発生した場合に発生します。 **単位**: **カウント サーバー側の接続エラーの出現総数を取得するために、Sum 統計を使用します。 `DisconnectSuccess` AWS AppSync から正常に切断された WebSocket の数。 **単位**: **カウント 成功した切断の出現総数を取得するために、Sum 統計を使用します。 `DisconnectClientError` WebSocket 接続の切断中に AWS AppSync から発生したクライアントエラーの数。 **単位**: **カウント 切断エラーの出現総数を取得するために、Sum 統計を使用します。 `DisconnectServerError` WebSocket 接続の切断中に AWS AppSync から発生したサーバーエラーの数。 **単位**: **カウント 切断エラーの出現総数を取得するために、Sum 統計を使用します。 `SubscribeSuccess` WebSocket を介して AWS AppSync に正常に登録されたサブスクリプションの数。サブスクリプションがなくても接続することはできますが、接続せずにサブスクリプションを持つことはできません。 **単位**: **カウント 成功したサブスクリプションの出現総数を取得するために、Sum 統計を使用します。 `SubscribeClientError` クライアント側のエラーが原因で AWS AppSync によって拒否されたサブスクリプションの数。これは、JSON ペイロードが正しくない、サービスがスロットリングされている、または承認設定が正しく構成されていない場合に発生する可能性があります。 **単位**: **カウント クライアント側のサブスクリプションエラーの出現総数を取得するために、Sum 統計を使用します。 `SubscribeServerError` サブスクリプションの処理中に AWS AppSync から発生したエラーの数。これは通常、予期しないサーバー側の問題が発生した場合に発生します。 **単位**: **カウント サーバー側のサブスクリプションエラーの出現総数を取得するために、Sum 統計を使用します。 `UnsubscribeSuccess` 正常に処理されたサブスクリプション解除リクエストの数。 **単位**: **カウント 成功したサブスクリプション解除リクエストの出現総数を取得するために、Sum 統計を使用します。 `UnsubscribeClientError` クライアント側のエラーのために AWS AppSync によって拒否されたサブスクリプション解除リクエストの数。 **単位**: **カウント クライアント側のサブスクリプション解除リクエストのエラーの出現総数を取得するために、Sum 統計を使用します。 `UnsubscribeServerError` サブスクリプション解除リクエストの処理中に AWS AppSync から発生したエラーの数。これは通常、予期しないサーバー側の問題が発生した場合に発生します。 **単位**: **カウント サーバー側のサブスクリプション解除リクエストのエラーの出現総数を取得するために、Sum 統計を使用します。 `PublishDataMessageSuccess` 正常に発行されたサブスクリプションイベントメッセージの数。 **単位**: **カウント 正常に発行されたサブスクリプションイベントメッセージの合計を取得するために、Sum 統計を使用します。 `PublishDataMessageClientError` クライアント側のエラーのために発行に失敗したサブスクリプションイベントメッセージの数。 `Unit`: *カウント* クライアント側のサブスクリプションイベント発行エラーの出現総数を取得するために、Sum 統計を使用します。 `PublishDataMessageServerError` サブスクリプションイベントメッセージの発行中に AWS AppSync から発生したエラーの数。これは通常、予期しないサーバー側の問題が発生した場合に発生します。 **単位**: **カウント サーバー側のサブスクリプションイベント発行エラーの出現総数を取得するために、Sum 統計を使用します。 `PublishDataMessageSize` 発行されたサブスクリプションイベントメッセージのサイズ。 **単位**: *バイト* `ActiveConnections` サブスクリプションイベントメッセージの発行中に発生した AWS AppSync からのエラーの数。 **単位**: **カウント 開かれている接続の合計数を取得するために、Sum 統計を使用します。 `ActiveSubscriptions` クライアントからの同時サブスクリプション数 (1 分間)。 **単位**: **カウント アクティブなサブスクリプションの合計数を取得するために、Sum 統計を使用します。 `ConnectionDuration` 接続が開いたままになる時間。 **単位**: *ミリ秒* 接続期間を評価するために Average 統計を使用します。 `OutboundMessages` 正常に公開された従量制メッセージの数。1 つの従量制メッセージは 5 kB の配信済みデータに相当します。 **単位**: **カウント 正常に公開された従量制メッセージの総数を取得するために、Sum 統計を使用します。 `InboundMessageSuccess` 正常に処理されたインバウンドメッセージの数。ミューテーションによって呼び出されるサブスクリプションタイプごとに 1 つのインバウンドメッセージが生成されます。 **単位**: **カウント 正常に処理されたインバウンドメッセージの総数を取得するために、Sum 統計を使用します。 `InboundMessageError` サブスクリプションのペイロードサイズの制限である 240 kB を超えるなど、無効な API リクエストが原因で処理に失敗したインバウンドメッセージの数。 **単位**: **カウント API 関連で処理に失敗したインバウンドメッセージの総数を取得するために、Sum 統計を使用します。 `InboundMessageFailure` エラーが原因で処理に失敗したインバウンドメッセージの数 AWS AppSync。 **単位**: **カウント Sum 統計を使用して、 AWS AppSync関連する処理エラーが発生したインバウンドメッセージの総数を取得します。 `InboundMessageDelayed` 遅延インバウンドメッセージの数。インバウンドメッセージレートのクォータまたはアウトバウンドメッセージレートのクォータのいずれかが超過すると、インバウンドメッセージが遅延する可能性があります。 **単位**: **カウント 合計の統計を使用して、遅延したインバウンドメッセージの総数を取得します。 `InboundMessageDropped` ドロップされたインバウンドメッセージの数。インバウンドメッセージは、インバウンドメッセージレートのクォータまたはアウトバウンドメッセージレートのクォータのいずれかを超えた場合にドロップする可能性があります。 **単位**: **カウント 合計の統計を使用して、ドロップされたインバウンドメッセージの総数を取得します。 `InvalidationSuccess` `$extensions.invalidateSubscriptions()` とのミューテーションによって正常に無効 (購読解除) されたサブスクリプションの数。 **単位**: **カウント サブスクライブが正常に解除されたサブスクリプションの総数を取得するには Sum 統計を使用します。 `InvalidationRequestSuccess` 正常に処理された無効化リクエストの数。 **単位**: **カウント 正常に処理された無効化リクエストの総数を取得するために、Sum 統計を使用します。 `InvalidationRequestError` 無効な API リクエストにより処理に失敗した無効化リクエストの数。 **単位**: **カウント API 関連で処理に失敗した無効化リクエストの総数を取得するために、Sum 統計を使用します。 `InvalidationRequestFailure` エラーが原因で処理に失敗した無効化リクエストの数 AWS AppSync。 **単位**: **カウント Sum 統計を使用して、 AWS AppSync関連する処理に失敗した無効化リクエストの総数を取得します。 `InvalidationRequestDropped` 無効化リクエストのクォータを超えたときにドロップされた無効化リクエストの数。 **単位**: **カウント ドロップされた無効化リクエストの総数を取得するために、Sum 統計を使用します。 #### インバウンドメッセージとアウトバウンドメッセージの比較 ミューテーションを実行すると、そのミューテーションの *@aws\$1subscribe* ディレクティブを含むサブスクリプションフィールドが呼び出されます。サブスクリプションを呼び出すたびに、1 つのインバウンドメッセージが生成されます。例えば、2 つのサブスクリプションフィールドが *@aws\$1subscribe* で同じミューテーションを指定している場合、そのミューテーションが呼び出されると 2 つのインバウンドメッセージが生成されます。 1 つのアウトバウンドメッセージは、WebSocket クライアントに配信される 5 kB のデータに相当します。例えば、15 kB のデータを 10 個のクライアントに送信すると、アウトバウンドメッセージは 30 件になります (15 kB × 10 クライアント ÷ 1 メッセージあたり 5 kB = 30 メッセージ)。 インバウンドメッセージまたはアウトバウンドメッセージのクォータ引き上げをリクエストできます。詳細については、「*AWS 参考文献*」の「[AWS AppSync エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/appsync.html#limits_appsync)」、「*Service Quotas クォータユーザーガイド*」の「[クォータ増加のリクエスト](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)」の手順を参照してください。 ### 拡張メトリクス 拡張メトリクスは、 AWS AppSync リクエスト数やエラー数、レイテンシー、キャッシュヒット/ミスなど、API の使用状況とパフォーマンスに関する詳細なデータを生成します。拡張メトリクスデータはすべて CloudWatch アカウントに送信され、送信されるデータのタイプを設定できます。 **注記** 拡張メトリクスを使用する場合、追加料金が適用されます。詳細については、「[Amazon CloudWatch の料金](https://aws.amazon.com/cloudwatch/pricing/)」の「**詳細モニタリング**」の料金レベルを参照してください。 これらのメトリクスは、 AWS AppSync コンソールのさまざまな設定ページで確認できます。API 設定ページで、**拡張メトリクス**セクションを使用すると、次の項目を有効または無効にできます。 **リゾルバーメトリクスの動作**: これらのオプションは、リゾルバーの追加メトリクスの収集方法を制御します。フルリクエストリゾルバーメトリクス (リクエスト内のすべてのリゾルバーに対して有効になっているメトリクス) またはリゾルバーごとのメトリクス (設定が有効になっているリゾルバーに対してのみ有効になっているメトリクス) を有効にすることができます。以下のオプションが利用できます。 #### リゾルバーメトリクスの動作リスト `GraphQL errors per resolver (GraphQLError)` リゾルバーごとに発生した GraphQL エラーの数。 **メトリクスディメンション**: `API_Id`、`Resolver` **単位**: **カウント `Requests per resolver (Request)` リクエスト中に発生した呼び出しの数。これはリゾルバーごとに記録されます。 **メトリクスディメンション**: `API_Id`、`Resolver` **単位**: **カウント `Latency per resolver (Latency)` リゾルバーの呼び出しを完了する時間。レイテンシーはミリ秒単位で測定され、リゾルバーごとに記録されます。 **メトリクスディメンション**: `API_Id`、`Resolver` **単位**: *ミリ秒* `Cache hits per resolver (CacheHit)` リクエスト中のキャッシュヒットの数。これは、キャッシュが使用されている場合にのみ出力されます。キャッシュヒットはリゾルバーごとに記録されます。 **メトリクスディメンション**: `API_Id`、`Resolver` **単位**: **カウント `Cache misses per resolver (CacheMiss)` リクエスト中のキャッシュミスの数。これは、キャッシュが使用されている場合にのみ出力されます。キャッシュミスはリゾルバーごとに記録されます。 **メトリクスディメンション**: `API_Id`、`Resolver` **単位**: **カウント **データソースメトリクスの動作**: これらのオプションは、データソースの追加メトリクスの収集方法を制御します。フルリクエストデータソースメトリクス (リクエスト内のすべてのデータソースで有効になっているメトリクス) またはデータソースごとのメトリクス (設定が有効になっているデータソースでのみ有効になっているメトリクス) を有効にすることができます。以下のオプションが利用できます。 #### データソースメトリクスの動作リスト `Requests per data source (Request)` リクエスト中に発生した呼び出しの数。リクエストはデータソースごとに記録されます。完全なリクエストが有効になっている場合、各データソースは CloudWatch に独自のエントリを持ちます。 **メトリクスディメンション**: `API_Id`、`Datasource` **単位**: **カウント `Latency per data source (Latency)` データソースの呼び出しを完了する時間。レイテンシーはデータソースごとに記録されます。 **メトリクスディメンション**: `API_Id`、`Datasource` **単位**: *ミリ秒* `Errors per data source (GraphQLError)` データソースの呼び出し中に発生したエラーの数。 **メトリクスディメンション**: `API_Id`、`Datasource` **単位**: **カウント **オペレーションメトリクス**: GraphQL オペレーションレベルのメトリクスを有効にします。 #### オペレーションメトリクスの動作リスト `Requests per operation (Request)` 指定された GraphQL オペレーションが呼び出された回数。 **メトリクスディメンション**: `API_Id`、`Operation` **単位**: **カウント `GraphQL errors per operation (GraphQLError)` 指定された GraphQL オペレーション中に発生した GraphQL エラーの数。 **メトリクスディメンション**: `API_Id`、`Operation` **単位**: **カウント ## CloudWatch ログ 任意の新規または既存の GraphQL API でリクエストレベルおよびフィールドレベルの 2 つのタイプでログ記録するように設定できます。 ### リクエストレベルログ リクエストレベルのロギング (**詳細な内容を含む**) を設定すると、次の情報がログに記録されます。 + 消費されたトークンの数。 + リクエストとレスポンスの HTTP ヘッダー + リクエストで実行中の GraphQL クエリ + オペレーション全体の要約 + 登録された、新規および既存の GraphQL サブスクリプション ### フィールドレベルログ フィールドレベルのロギングを設定すると、以下の情報がログに記録されます。 + 各フィールドに対してソースと引数で生成されたリクエストマッピング + 各フィールドの、変換されたレスポンスマッピングで、対象フィールドを解決した結果のデータが含まれます。 + 各フィールドのトレース情報 ログ記録を有効にすると、 AWS AppSync は CloudWatch Logs を管理します。このプロセスには、ロググループとログストリームの作成、およびログとログストリームへのレポートが含まれます。 GraphQL API でログ記録を有効にしてリクエストを行うと、 AWS AppSync はロググループの下にロググループとログストリームを作成します。ロググループの名前は `/aws/appsync/apis/{graphql_api_id}` 形式に従います。各ロググループ内で、ログはログストリームにさらに分割されます。これらは、ログデータがレポートされるときに **Last Event Time** によって順序付けされます。 すべてのログイベントは、対象リクエストに **x-amzn-RequestId** でタグ付けされています。これにより、リクエストに関してログに記録されたすべての情報を取得するために CloudWatch のログイベントをフィルター処理できます。すべての GraphQL AWS AppSync リクエストの応答ヘッダから RequestId を取得することができます。 フィールドレベルのログ記録は次のログレベルで設定されます。 + **NONE** - フィールドレベルのログはキャプチャされません。 + ** **ERROR** - エラーカテゴリにあるフィールドについて**のみ**、次の情報がログに記録されます。** + サーバーレスポンスのエラーセクション + フィールドレベルエラー + エラーフィールドに対して解決された、生成リクエスト / レスポンス関数 + ** **情報** - 情報カテゴリとエラーカテゴリにあるフィールド**についてのみ**、次の情報がログに記録されます。** + 情報レベルのメッセージ + `$util.log.info` および `console.log` を介して送信されるユーザーメッセージ + フィールドレベルのトレースログとマッピングログは表示されません。 + 詳細コンテンツを含むフィールドレベルのログ記録が `INFO`以上に設定されている場合、 は変換されたマッピングテンプレートのログ記録メッセージ AWS AppSync を追加します。これには、変換されたマッピングテンプレートに追加された情報、またはリゾルバーまたは関数が実行した JavaScript コードの出力が含まれます。パスワードや承認ヘッダーなどの機密情報をダウンストリームデータソースに送信する予定の場合は、その情報をログに含めないでください。 + ** **デバッグ** - デバッグ、情報、エラーカテゴリにあるフィールドについて**のみ**、次の情報をログに記録します。** + デバッグレベルのメッセージ + `$util.log.info`、`$util.log.debug`、`console.log`、`console.debug` を介して送信されるユーザーメッセージ + フィールドレベルのトレースログとマッピングログは表示されません。 + ** **ALL** - 次の情報が、クエリの**すべての**フィールドに記録されます。** + フィールドレベルのトレース情報 + 各フィールドに対して解決された、生成リクエスト/レスポンス関数 ### モニタリングのメリット ログおよびメトリクスを使用して、GraphQL クエリを特定、トラブルシューティング、最適化できます。たとえば、クエリの各フィールドに記録されたトレース情報を使用して、レイテンシーの問題をデバッグできます。これを示すため、GraphQL クエリで 1 つまたは複数のリゾルバーをネストして使用しているとします。CloudWatch Logs のフィールドオペレーションのサンプルは次のようになります。 ``` { "path": [ "singlePost", "authors", 0, "name" ], "parentType": "Post", "returnType": "String!", "fieldName": "name", "startOffset": 416563350, "duration": 11247 } ``` これは GraphQL スキーマに対応します。次のようになります。 ``` type Post { id: ID! name: String! authors: [Author] } type Author { id: ID! name: String! } type Query { singlePost(id:ID!): Post } ``` 上記のログの結果で、**path** は、`singlePost()` という名前のクエリを実行して返されたデータの単一項目を示します。この例では、最初のインデックス (0) の **name** フィールドを表します。**startOffset** は、GraphQL クエリオペレーションの開始からのオフセットです。**duration** は、フィールドを解決するのにかかる合計時間です。これらの値は、特定のデータソースからデータの実行が予測より遅い理由、または特定のフィールドがクエリ全体の処理速度を低下することのトラブルシューティングに役立つ可能性があります。例えば、Amazon DynamoDB テーブルのプロビジョニングスループットを向上させたり、オペレーション全体のパフォーマンスが低下する原因となっている特定のフィールドをクエリから削除したりすることができます。 2019 年 5 月 8 日現在、 AWS AppSync は完全に構造化された JSON としてログイベントを生成します。これにより、CloudWatch Logs Insights や Amazon OpenSearch Service などのログ分析サービスを使用して、GraphQL リクエストのパフォーマンスとスキーマフィールドの使用傾向を把握できるようになります。たとえば、パフォーマンスの問題の根本原因となっている可能性のある高いレイテンシーが発生しているリゾルバーの特定を簡単に行えます。また、スキーマ内で最も使用頻度の低いフィールドを特定し、GraphQL フィールドを廃止する場合の影響を評価することもできます。 ### 競合の検出と同期ロギング AWS AppSync API に、**フィールドリゾルバーのログレベル**が **All** に設定されている CloudWatch Logs へのログ記録がある場合、 AWS AppSync は競合検出と解決情報をロググループに出力します。これにより、 AWS AppSync API が競合にどのように応答したかを詳細に把握できます。応答を解釈しやすくするため、ログには以下の情報が記録されます。 #### メトリクスのリスト `conflictType` バージョンの不一致またはお客様が指定した条件が原因で競合が発生したかどうかを詳細に示します。 `conflictHandlerConfigured` リクエスト時にリゾルバーで設定された競合ハンドラーを示します。 `message` 競合をどのように検出し、解決したかに関する情報を提供します。 `syncAttempt` リクエストを最終的に拒否する前に、サーバーがデータを同期するために試行した回数。 `data` 競合ハンドラーが `Automerge` に設定されていた場合、このフィールドは `Automerge`e が各フィールドに対してどのような決定を行ったかを示すために入力されます。提供されるアクションは、次のとおりです。 + **REJECTED** - `Automerge` がサーバーの値を優先して受信フィールド値を拒否した場合。 + **ADDED** - サーバーに既存の値がないために、`Automerge` が着信フィールドに追加した場合。 + **APPENDED** - `Automerge` がサーバーに存在するリストの値に着信値を追加した場合。 + **MERGED** - `Automerge` が受信した値をサーバーに存在するセットの値にマージした場合。 ### トークン数を使用してリクエストを最適化する 1,500 KB 秒以下のメモリと vCPU 時間を消費するリクエストには、1 つのトークンが割り当てられます。リソース消費量が 1,500 KB 秒を超えるリクエストには、追加のトークンが渡されます。たとえば、リクエストが 3,350 KB 秒を消費する場合、 AWS AppSync はリクエストに 3 つのトークン (次の整数値に切り上げ) を割り当てます。デフォルトでは、 AWS AppSync はデプロイ先の AWS リージョンに応じて、1 秒あたり最大 5,000 または 10,000 個のリクエストトークンをアカウントの APIs に割り当てます。各 API が 1 秒あたり平均 2 つのトークンを使用する場合、1 秒あたりのリクエスト数は 2,500 または 5,000 に制限されます。1 秒あたりに割り当てられた量よりも多くのトークンが必要な場合は、リクエストを送信してリクエストトークンのレートのデフォルトクォータを増やすことができます。詳細については、**「AWS 全般のリファレンス ガイド」の「[AWS AppSync エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/appsync.html#limits_appsync)」、「**Service Quotas クォータユーザーガイド」の「[クォータ増加のリクエスト](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)」を参照してください。 リクエストあたりのトークン数が多いということは、リクエストを最適化して API のパフォーマンスを向上させるチャンスがあることを示している可能性があります。リクエスト 1 回あたりのトークン数を増やす要因には次のようなものがあります。 + GraphQL スキーマのサイズと複雑さ。 + リクエストとレスポンスのマッピングテンプレートの複雑さ。 + 1 回のリゾルバー呼び出し回数。 + リゾルバーから返されたデータ転送量。 + ダウンストリームデータソースのレイテンシー。 + (parallel 呼び出しやバッチ呼び出しとは対照的に) 連続したデータソース呼び出しを必要とするスキーマとクエリの設計。 + ロギング設定、特にフィールドレベルおよび詳細なログコンテンツ。 **注記** AWS AppSync メトリクスとログに加えて、クライアントはレスポンスヘッダー を介してリクエストで消費されたトークンの数にアクセスできます`x-amzn-appsync-TokensConsumed`。 ### ログのサイズ制限 デフォルトでは、ログ記録が有効になっている場合、 AWS AppSync はリクエストごとに最大 1 MB のログを送信します。このサイズを超えるログは切り捨てられます。ログサイズを減らすには、フィールドレベルのログの `ERROR` ログレベルを選択し、`VERBOSE` ログを無効にするか、不要な場合はフィールドレベルのログを完全に無効にします。`ALL` ログレベルの代替として、拡張メトリクスを使用して特定のリゾルバー、データソース、または GraphQL オペレーションに関するメトリクスを取得したり、AppSync が提供するログユーティリティを使用して必要な情報のみをログに記録したりできます。 ## ログタイプリファレンス ### RequestSummary + **requestId:** リクエストの一意の識別子。 + **graphQLAPIId:** リクエスト元の GraphQL API の ID。 + **statusCode:** HTTP ステータスコードのレスポンス。 + **latency:** リクエストのエンドツーエンドのレイテンシー (ナノ秒単位、整数)。 ``` { "logType": "RequestSummary", "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1", "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4", "statusCode": 200, "latency": 242000000 } ``` ### ExecutionSummary + **requestId:** リクエストの一意の識別子。 + **graphQLAPIId:** リクエスト元の GraphQL API の ID。 + **startTime:** リクエストの GraphQL 処理の開始タイムスタンプ (RFC 3339 形式)。 + **endTime:** リクエストの GraphQL 処理の終了タイムスタンプ (RFC 3339 形式)。 + **duration:** GraphQL 処理の合計経過時間 (ナノ秒単位、整数)。 + **version:** ExecutionSummary のスキーマバージョン。 + ** **parsing:** ** + **startOffset:** 解析の開始オフセット (呼び出しを基準としたナノ秒単位、整数)。 + **duration:** 解析にかかった時間 (ナノ秒単位、整数)。 + ** **validation:** ** + **startOffset:** 検証の開始オフセット (呼び出しを基準としたナノ秒単位、整数)。 + **duration:** 検証の実行にかかった時間 (ナノ秒単位、整数)。 ``` { "duration": 217406145, "logType": "ExecutionSummary", "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1", "startTime": "2019-01-01T06:06:18.956Z", "endTime": "2019-01-01T06:06:19.174Z", "parsing": { "startOffset": 49033, "duration": 34784 }, "version": 1, "validation": { "startOffset": 129048, "duration": 69126 }, "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4" } ``` ### トレース + **requestId:** リクエストの一意の識別子。 + **graphQLAPIId:** リクエスト元の GraphQL API の ID。 + **startOffset:** フィールドの解決の開始オフセット (呼び出しを基準としたナノ秒単位、整数)。 + **duration:** フィールドの解決にかかった時間 (ナノ秒単位、整数)。 + **fieldName:** 解決されるフィールドの名前。 + **parentType:** 解決されるフィールドの親タイプ。 + **returnType:** 解決されるフィールドの戻り値の型。 + **path:** レスポンスのルートから解決されるフィールドまでのパスセグメントのリスト。 + **resolverArn:** フィールドの解決に使用されるリゾルバーの ARN。ネストされたフィールドには存在しない場合があります。 ``` { "duration": 216820346, "logType": "Tracing", "path": [ "putItem" ], "fieldName": "putItem", "startOffset": 178156, "resolverArn": "arn:aws:appsync:us-east-1:111111111111:apis/pmo28inf75eepg63qxq4ekoeg4/types/Mutation/fields/putItem", "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1", "parentType": "Mutation", "returnType": "Item", "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4" } ``` ## CloudWatch Logs Insights を使用したログの分析 以下は、GraphQL オペレーションのパフォーマンスとヘルスに関する実用的な洞察を得るために実行できるクエリの例です。これらの例は、CloudWatch Logs Insights コンソールでサンプルクエリとして利用できます。[CloudWatch コンソール](https://console.aws.amazon.com/cloudwatch)で、**Logs Insights** を選択し、GraphQL API の AWS AppSync ロググループを選択し、サンプル**AWS AppSync クエリ**で**クエリ**を選択します。 以下のクエリは、レイテンシーが最大の上位 10 個の GraphQL リクエストを返します。 ``` filter @message like "Tokens Consumed" | parse @message "* Tokens Consumed: *" as requestId, tokens | sort tokens desc | display requestId, tokens | limit 10 ``` 以下のクエリは、レイテンシーが最大の上位 10 個のリゾルバーを返します。 ``` fields resolverArn, duration | filter logType = "Tracing" | limit 10 | sort duration desc ``` 以下のクエリは、呼び出し頻度が最も高いリゾルバーを返します。 ``` fields ispresent(resolverArn) as isRes | stats count() as invocationCount by resolverArn | filter isRes and logType = "Tracing" | limit 10 | sort invocationCount desc ``` 以下のクエリは、マッピングテンプレートのエラーが最も多いリゾルバーを返します。 ``` fields ispresent(resolverArn) as isRes | stats count() as errorCount by resolverArn, logType | filter isRes and (logType = "RequestMapping" or logType = "ResponseMapping") and fieldInError | limit 10 | sort errorCount desc ``` 以下のクエリは、リゾルバーのレイテンシー統計を返します。 ``` fields ispresent(resolverArn) as isRes | stats min(duration), max(duration), avg(duration) as avg_dur by resolverArn | filter isRes and logType = "Tracing" | limit 10 | sort avg_dur desc ``` 以下のクエリは、フィールドのレイテンシー統計を返します。 ``` stats min(duration), max(duration), avg(duration) as avg_dur by concat(parentType, '/', fieldName) as fieldKey | filter logType = "Tracing" | limit 10 | sort avg_dur desc ``` CloudWatch Logs Insights クエリの結果は CloudWatch ダッシュボードにエクスポートできます。 ## OpenSearch Service を使用してログを分析する Amazon OpenSearch Service を使用して AWS AppSync ログを検索、分析、視覚化し、パフォーマンスのボトルネックと運用上の問題の根本原因を特定できます。レイテンシーが最大でエラーのあるリゾルバーを特定できます。さらに、OpenSearch を使用して、可視化に優れたダッシュボードを作成できます。OpenSearch Dashboards は、OpenSearch Service で利用可能なオープンソースのデータ可視化および探索ツールです。OpenSearch ダッシュボードを使用すると、GraphQL オペレーションのパフォーマンスとヘルスを継続的にモニタリングできます。例えば、GraphQL リクエストの P90 レイテンシーを可視化し、各リゾルバーの P90 レイテンシーにドリルダウンできるダッシュボードを作成できます。 OpenSearch Service を使用するときは、OpenSearch インデックスを検索するためのフィルターパターンとして「**「cwl\$1**」を使用してください。OpenSearch Service は、CloudWatch Logs からストリーミングされるログに「**cwl-**」というプレフィックスを付けてインデックスを作成します。 AWS AppSync API ログを OpenSearch Service に送信された他の CloudWatch ログと区別するには、検索`graphQLAPIID.keyword=YourGraphQLAPIID`に のフィルター式を追加することをお勧めします。 ## ログ形式の移行 AWS AppSync が生成するログイベントは、主に完全に構造化された JSON としてフォーマットされます。ただし、特定の診断および中間処理メッセージが非構造化形式で出力される場合があります。非構造化ログを完全構造化 JSON に移行する必要がある場合は、[GitHub サンプル](https://github.com/aws-samples/aws-appsync-cwl-migrator)で利用可能なスクリプトを使用できます。 次にこれらの[メトリクスフィルター](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogsConcepts.html)を使用して、ログデータをグラフの作成やアラームの設定に利用できる数値の CloudWatch メトリクスに変換します。