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

CloudWatch を使用した GraphQL API データのモニタリングとログ

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

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

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

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

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

セットアップと設定

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

手動での IAM ロールの設定

既存の IAM ロールを使用する場合、ロールは CloudWatch にログを書き込むために必要なアクセス許可を AWS AppSync に付与する必要があります。これを手動で設定するには、 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 ステータスコードやレイテンシーの原因となる特定のイベントを監視し、アラートを出すことができます。以下のメトリクスが出力されます。

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

すべてのメトリクスは、GraphQLAPIId という 1 つのディメンションで出力されます。これは、すべてのメトリクスが GraphQL API ID と結合されていることを意味します。次のメトリクスは、純粋な WebSocket を介した GrapQL サブスクリプションに関連しています。

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

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

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

インバウンドメッセージまたはアウトバウンドメッセージのクォータ引き上げをリクエストできます。詳細については、「AWS 参考文献」の「AWS AppSync エンドポイントとクォータ」、「Service Quotas クォータユーザーガイド」の「クォータ増加のリクエスト」の手順を参照してください。

拡張メトリクス

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

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

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

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

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

CloudWatch ログ

任意の新規または既存の GraphQL API でリクエストレベルおよびフィールドレベルの 2 つのタイプでログ記録するように設定できます。

リクエストレベルログ

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

フィールドレベルログ

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

ログ記録を有効にすると、 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 を取得することができます。

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

モニタリングのメリット

ログおよびメトリクスを使用して、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 が競合にどのように応答したかをきめ細かく把握できます。応答を解釈しやすくするため、ログには以下の情報が記録されます。

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

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 エンドポイントとクォータ」、「Service Quotas クォータユーザーガイド」の「クォータ増加のリクエスト」を参照してください。

リクエストあたりのトークン数が多いということは、リクエストを最適化して 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 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*」を使用してください。OpenSearch Service は、CloudWatch Logs からストリーミングされるログに「cwl-」というプレフィックスを付けてインデックスを作成します。 AWS AppSync API ログを OpenSearch Service に送信された他の CloudWatch ログと区別するには、検索graphQLAPIID.keyword=YourGraphQLAPIIDに のフィルター式を追加することをお勧めします。

ログ形式の移行

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

次にこれらのメトリクスフィルターを使用して、ログデータをグラフの作成やアラームの設定に利用できる数値の CloudWatch メトリクスに変換します。