翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CloudWatch を使用して GraphQL APIデータをモニタリングおよびログに記録する

CloudWatch メトリクスと CloudWatch ログAPIを使用して、GraphQL のログ記録とデバッグを行うことができます。これらのツールにより、デベロッパーはパフォーマンスのモニタリング、問題のトラブルシューティング、GraphQL オペレーションの最適化を効果的に行うことができます。

CloudWatch メトリクスは、APIパフォーマンスと使用状況をモニタリングするための幅広いメトリクスを提供するツールです。これらのメトリクスは、主に 2 つのカテゴリに分類されます。

このガイドでは、リゾルバーのパフォーマンス、データソースインタラクション、個々の GraphQL オペレーションに関するより詳細なデータを提供する拡張メトリクスも紹介しています。これらのメトリクスは、より深いインサイトを提供しますが、追加のコストが発生します。

CloudWatch Logs は、GraphQL のログ記録機能を有効にするツールですAPIs。ログは の 2 つのレベルで設定できますAPI。

ログ記録を設定したり、ログエントリを解釈したり、ログデータを使用してトラブルシューティングや最適化を行うことができます。 は、クエリの実行、解析、検証、フィールド解決データを明らかにするさまざまなログタイプ AWS AppSync を提供します。

セットアップと設定

GraphQL で自動ログ記録を有効にするにはAPI、 AWS AppSync コンソールを使用します。

手動IAMロール設定

既存のIAMロールを使用する場合、ロールは にログ AWS AppSync を書き込むために必要なアクセス許可を付与する必要があります CloudWatch。これを手動で設定するには、 がログの作成時にロールを引き AWS AppSync 受けるARNことができるように、サービスロールを指定する必要があります。

IAM コンソール で、次の定義AWSAppSyncPushToCloudWatchLogsPolicyを持つ名前の新しいポリシーを作成します。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

次に、 という名前の新しいロールを作成しAWSAppSyncPushToCloudWatchLogsRole、新しく作成されたポリシーをロールにアタッチします。このロールの信頼関係を次のように編集します。

{
    "Version": "2012-10-17",
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "Service": "appsync.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
        }
    ]
}

ロールをコピーARNし、 AWS AppSync GraphQL のログ記録を設定するときに使用しますAPI。

CloudWatch メトリクス

CloudWatch メトリクスを使用して、HTTPステータスコードやレイテンシーにつながる可能性のある特定のイベントをモニタリングしてアラートを提供できます。次のメトリクスが出力されます。

リアルタイムサブスクリプション

すべてのメトリクスは 1 つのディメンション G raphQLAPIIdで出力されます。これは、すべてのメトリクスが GraphQL API と結合されていることを意味しますIDs。次のメトリクスは、純粋 の GraphQL サブスクリプションに関連しています WebSockets。

インバウンドメッセージとアウトバウンドメッセージの比較

ミューテーションが実行されると、そのミューテーションの @aws_subscribe ディレクティブを含むサブスクリプションフィールドが呼び出されます。サブスクリプションの呼び出しごとに 1 つのインバウンドメッセージが生成されます。例えば、@aws_subscribe で 2 つのサブスクリプションフィールドが同じミューテーションを指定すると、そのミューテーションが呼び出されると 2 つのインバウンドメッセージが生成されます。

1 つのアウトバウンドメッセージは、 WebSocket クライアントに配信される 5 kB のデータに相当します。例えば、15 kB のデータを 10 のクライアントに送信すると、30 のアウトバウンドメッセージ (15 kB * 10 のクライアント/メッセージあたり 5 kB = 30 メッセージ) になります。

インバウンドメッセージまたはアウトバウンドメッセージのクォータ引き上げをリクエストできます。詳細については、AWS 「 全般のリファレンスガイド」のAWS AppSync 「エンドポイントとクォータ」および「 サービスクォータユーザーガイド」の「クォータ引き上げをリクエストする手順」を参照してください。 Service Quotas

拡張メトリクス

拡張メトリクスは、リクエスト数やエラー数、レイテンシー、キャッシュヒット/ミスなど AWS AppSync 、API使用状況とパフォーマンスに関する詳細なデータを生成します。拡張メトリクスデータはすべて CloudWatch アカウントに送信され、送信されるデータのタイプを設定できます。

これらのメトリクスは、 AWS AppSync コンソールのさまざまな設定ページで確認できます。API 設定ページで、拡張メトリクスセクションでは、次の項目を有効または無効にできます。

リゾルバーメトリクスの動作： これらのオプションは、リゾルバーの追加メトリクスの収集方法を制御します。フルリクエストリゾルバーメトリクス (リクエスト内のすべてのリゾルバーに対して有効になっているメトリクス) またはリゾルバーごとのメトリクス (設定が有効になっているリゾルバーに対してのみ有効になっているメトリクス) を有効にすることができます。以下のオプションが利用できます。

データソースメトリクスの動作： これらのオプションは、データソースの追加メトリクスの収集方法を制御します。フルリクエストデータソースメトリクス (リクエスト内のすべてのデータソースで有効になっているメトリクス) またはデータソースごとのメトリクス (設定が有効になっているデータソースでのみ有効になっているメトリクス) を有効にすることができます。以下のオプションが利用できます。

オペレーションメトリクス : GraphQL オペレーションレベルのメトリクスを有効にします。

CloudWatch ログ

新規または既存の GraphQL には、APIリクエストレベルとフィールドレベルの 2 種類のログ記録を設定できます。

リクエストレベルログ

リクエストレベルのロギング (詳細な内容を含む) を設定すると、次の情報がログに記録されます。

フィールドレベルログ

フィールドレベルのロギングを設定すると、以下の情報がログに記録されます。

ログ記録を有効にすると、 は CloudWatch ログ AWS AppSync を管理します。このプロセスには、ロググループとログストリームの作成、およびログとログストリームへのレポートが含まれます。

GraphQL のログ記録を有効にしてリクエストを行うAPIと、 はロググループの下にロググループとログストリーム AWS AppSync を作成します。ロググループの名前は /aws/appsync/apis/{graphql_api_id} 形式に従います。各ロググループ内で、ログはログストリームにさらに分割されます。これらは、ログデータがレポートされるときに Last Event Time によって順序付けされます。

すべてのログイベントには、そのリクエストの x-amzn-RequestId がタグ付けされます。これにより、 のログイベントをフィルタリング CloudWatch して、そのリクエストに関するすべてのログ情報を取得できます。は、すべての GraphQL AWS AppSync リクエストのレスポンスヘッダー RequestId から取得できます。

フィールドレベルのログ記録は次のログレベルで設定されます。

モニタリングのメリット

ログおよびメトリクスを使用して、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に設定されている CloudWatch ログへのログがある場合、 は競合検出と解決情報をロググループに AWS AppSync 出力します。これにより、 が AWS AppSync API競合にどのように対応したかを詳細に把握できます。応答を解釈しやすくするため、ログには以下の情報が記録されます。

トークン数を使用してリクエストを最適化する

1,500 KB 秒以下のメモリと vCPU 時間しか消費しないリクエストには、1 つのトークンが割り当てられます。リソース消費量が 1,500 KB 秒を超えるリクエストには、追加のトークンが渡されます。例えば、リクエストが 3,350 KB 秒を消費する場合、 はリクエストに 3 つのトークン (次の整数値に切り上げ) を AWS AppSync 割り当てます。デフォルトでは、 は、デプロイ先の AWS リージョンに応じて、アカウントAPIs内の に 1 秒あたり最大 5,000 または 10,000 個のリクエストトークンを AWS AppSync 割り当てます。APIs 各 が 1 秒あたり平均 2 つのトークンを使用する場合、それぞれ 1 秒あたり 2,500 または 5,000 リクエストに制限されます。1 秒あたりに割り当てられた量よりも多くのトークンが必要な場合は、リクエストを送信してリクエストトークンのレートのデフォルトクォータを増やすことができます。詳細については、「 AWS 全般のリファレンス ガイド」のAWS AppSync 「エンドポイントとクォータ」およびService Quotas」を参照してください。 https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html

リクエストごとのトークン数が多い場合は、リクエストを最適化し、 のパフォーマンスを向上させる機会があることを示している可能性がありますAPI。リクエスト 1 回あたりのトークン数を増やす要因には次のようなものがあります。

ログサイズ制限

デフォルトでは、ログ記録が有効になっている場合、 AWS AppSync はリクエストごとに最大 1 MB のログを送信します。このサイズを超えるログは切り捨てられます。ログサイズを減らすには、フィールドレベルのログのERRORログレベルを選択し、VERBOSEログ記録を無効にするか、不要な場合はフィールドレベルのログを完全に無効にします。ALL ログレベルの代替として、拡張メトリクスを使用して特定のリゾルバー、データソース、または GraphQL オペレーションに関するメトリクスを取得したり、 が提供するログ記録ユーティリティを使用して必要な情報のみをログ AppSync 記録したりできます。

ログタイプリファレンス

RequestSummary

{
     "logType": "RequestSummary",
     "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
     "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4",
     "statusCode": 200,
     "latency": 242000000
}

ExecutionSummary

{
    "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"
}

トレース

{
    "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 コンソール で、Logs Insights を選択し、GraphQL の AWS AppSync ロググループを選択しAPI、サンプル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 ダッシュボードは、 OpenSearch Service で利用できるオープンソースのデータの視覚化と探索ツールです。 OpenSearch Dashboards を使用すると、GraphQL オペレーションのパフォーマンスと状態を継続的にモニタリングできます。例えば、GraphQL リクエストの P90 レイテンシーを可視化し、各リゾルバーの P90 レイテンシーにドリルダウンできるダッシュボードを作成できます。

OpenSearch サービスを使用する場合は、フィルターパターンとして「cwl*」を使用して OpenSearch インデックスを検索します。 OpenSearch サービスは CloudWatch 、ログからストリーミングされたログに「cwl-」というプレフィックスでインデックスを作成します。Service に送信された他の CloudWatch ログとログを区別 AWS AppSync APIするには OpenSearch 、検索graphQLAPIID.keyword=YourGraphQLAPIIDに のフィルター式を追加することをお勧めします。

ログ形式の移行

2019 年 5 月 8 日以降に AWS AppSync 生成されるログイベントは、完全に構造化された としてフォーマットされますJSON。2019 年 5 月 8 日より前の GraphQL リクエストを分析するには、GitHub サンプル で利用可能なスクリプトJSONを使用して、古いログを完全構造化に移行できます。2019 年 5 月 8 日より前のログ形式を使用する必要がある場合は、[Type (タイプ)] を [Account Management (アカウント管理)] に、[Category (カテゴリ)] を [General Account Question (一般的なアカウント質問)] に設定して、サポートチケットを作成します。

また、 のメトリクスフィルターを使用して CloudWatch ログデータを数値 CloudWatch メトリクスに変換することで、ログデータをグラフ化またはアラームを設定することもできます。