How to Monitor AWS AppSync GraphQL API Performance

AWS AppSync is a fully managed GraphQL service that connects applications to multiple data sources, including DynamoDB, Lambda, Aurora Serverless, and HTTP endpoints, with a single API layer. As you scale, you need clear visibility into how your API is behaving: where latency is coming from, which resolvers are throwing errors, and how your real-time subscriptions are holding up under load.

This guide covers everything you need to set up robust AWS AppSync monitoring using native AWS tools and third-party observability platforms, so you can catch issues fast and keep your GraphQL API performing reliably.

1. How AWS AppSync Monitoring Works

AWS AppSync integrates natively with two core AWS observability services:

• Amazon CloudWatch: Collects metrics and logs from your GraphQL API automatically.
• AWS X-Ray: Provides distributed tracing across your AppSync API and downstream services.

Together these tools cover metrics (how much), logs (what happened), and traces (where the time went). No third-party agent is required for basic monitoring.

2. Built-in CloudWatch Metrics for AWS AppSync

Out of the box, AppSync reports a set of standard metrics to CloudWatch without any configuration. You can view them in the Monitoring section of the AppSync console or directly in the CloudWatch console under the AWS/AppSync namespace. 

Setting Alarms on Core Metrics

A practical starting point for any production API is to create CloudWatch alarms on these four signals:

1. 5XXError sum > 10 over 5 minutes: Rising server errors demand immediate investigation.
2. Latency p99 > 2000ms over 5 minutes: Indicates a slow resolver or downstream bottleneck impacting your worst-performing users.
3. 4XXError rate > 5% over 10 minutes: Possible auth misconfiguration or malformed requests from clients.
4. TokensConsumed spike > 2x baseline: Signals unexpectedly expensive queries that could inflate costs.

3. Real-time Subscription Metrics

In November 2023, AWS added dedicated CloudWatch metrics for GraphQL subscriptions over pure WebSockets. All subscription metrics are emitted in the GraphQLAPIId dimension.

4. Enhanced Metrics for Resolver-Level Visibility

In February 2024, AWS launched 12 new optional CloudWatch metrics for AWS AppSync. Standard metrics aggregate everything at the API level. Enhanced Metrics break data down at three granular levels:

Resolver-level Metrics

Tracks GraphQL errors, request count, latency, and cache hits per resolver. Recorded by API ID and resolver name. You can enable metrics for all resolvers or only for specific ones using the metricsConfig field.

Data Source-level Metrics

Tracks request counts and errors per data source (DynamoDB table, Lambda function, HTTP endpoint, and so on). Recorded by API ID and data source name. You can choose between FULL_REQUEST_DATA_SOURCE_METRICS (all data sources) or PER_DATA_SOURCE_METRICS (only those with metricsConfig: ENABLED).

Operation-level Metrics

Tracks request counts and GraphQL errors per named operation (query, mutation, or subscription by operation name). Recorded by API ID and operation name. Set operationLevelMetricsConfig to ENABLED or DISABLED.

Important: Enhanced Metrics incur additional CloudWatch costs. Enable them selectively on critical resolvers or data sources first and expand coverage as needed. 

5. Enabling CloudWatch Logs for AppSync

CloudWatch Logs gives you the actual request content and resolver execution details your metrics cannot capture alone. 

How to Enable Logging

• Open the AppSync console and select your GraphQL API.
• Navigate to Settings in the left-hand panel.
• Under Logging, toggle Enable Logs to on.
• Optionally enable Include verbose content for full request detail.
• Choose a Field resolver log level: None, Error, Info, Debug, or All.
• Assign an IAM role that allows AppSync to write to CloudWatch Logs, or let the console create one automatically.
• Save your changes.

Request-level vs Field-level Logs

Request-level logs capture HTTP headers, the full GraphQL query, operation summaries, and subscription registration events. They are useful for auditing and request replay.

Field-level logs capture per-resolver detail: request and response mapping template outputs, resolver latency, and tracing IDs. They are powerful for debugging but produce significantly more data. Use the Error level in production and raise it to Debug only during active troubleshooting to manage ingestion costs.

Required IAM Policy

If you create the IAM role manually, the role needs the following policy:

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

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

6. AWS X-Ray Tracing for AppSync

AWS X-Ray lets you trace the full journey of a GraphQL request: from AppSync through Lambda resolvers, to DynamoDB and back. It highlights slow segments and failed calls with a visual service map.

Enabling X-Ray for AppSync

• In the AppSync console, open your API’s Settings.
• Under X-Ray Tracing, toggle Enable X-Ray.
• Save changes. AppSync will now emit trace segments for every request.

What X-Ray Shows You

• End-to-end latency broken down by segment: the AppSync handler, each resolver, and each downstream call.
• Failed requests with the exact segment where the failure occurred.
• A service map visualizing connections between AppSync, Lambda, DynamoDB, and other data sources.
• Correlation with CloudWatch Logs via trace IDs embedded in log entries.

Important limitation: X-Ray does not trace VTL mapping templates. For resolver template debugging, you still need CloudWatch field-level logs.

CloudWatch ServiceLens

CloudWatch ServiceLens correlates CloudWatch metrics, logs, and X-Ray traces in a single view. Use it to jump from a spike in the Latency metric to the specific X-Ray trace that caused it.

7. Querying Logs with CloudWatch Logs Insights

CloudWatch Logs Insights lets you run SQL-like queries against your AppSync logs to surface patterns that individual metrics cannot reveal.

Find Slow Operations

fields @timestamp, @message| filter @message like /Resolve field/| parse @message "duration: * ms" as duration| sort duration desc| limit 20

fields @timestamp, @message| filter @message like /Resolve field/| parse @message "duration: * ms" as duration| sort duration desc| limit 20

Count 5XX Errors by Operation

filter statusCode = 500| stats count(*) as errorCount by operationName| sort errorCount desc

filter statusCode = 500| stats count(*) as errorCount by operationName| sort errorCount desc

These queries help you quickly spot which operations are responsible for the most errors or the highest latency, rather than digging through individual log streams manually.

8. CloudTrail for GraphQL Data Plane Logging

In November 2024, AWS AppSync added support for logging GraphQL data plane operations (queries, mutations, subscriptions, and connect requests) to AWS CloudTrail. 

CloudTrail captures all API activities as events, including calls from the console and programmatic API calls. This is primarily a security and compliance feature that creates an immutable audit trail of who called what operation and when.

Use CloudTrail when you need to:

• Audit which IAM principals are calling your GraphQL operations.
• Investigate security incidents involving unexpected API access.
• Satisfy compliance requirements that mandate operation-level logging.

9. Building a CloudWatch Dashboard for AppSync

A well-designed CloudWatch dashboard gives your team instant visibility into API health. Include these widgets at minimum:

• Requests over time (line chart, Sum statistic)
• Latency average and p99 (line chart)
• 4XXError and 5XXError counts (bar chart, Sum statistic)
• TokensConsumed (line chart, Sum statistic)
• ActiveConnections and ActiveSubscriptions (if you use real-time subscriptions)
• EngineCPUUtilization (if you use AppSync caching)

Pin the dashboard to your team’s main operations screen and link the alarm notification to your incident management tool.

10. AWS AppSync Logging Best Practices

• Start with Error-level field logs in production. All-level logging creates a large volume of data that quickly raises CloudWatch Logs ingestion costs.
• Set log retention policies. The default retention for CloudWatch log groups is indefinite. Set a retention period (30 or 90 days is typical) to prevent storage costs from compounding.
• Use X-Ray sampling rules. At high request volumes, tracing 100% of requests is expensive. Configure sampling rules to trace a representative subset.
• Enable Enhanced Metrics selectively. Enable resolver-level metrics only on your most critical or highest-traffic resolvers to keep costs predictable.
• Add NEW logging levels (INFO and DEBUG) selectively. AWS added INFO and DEBUG field log levels in September 2024, giving you finer control over log output.
• Tag your AppSync API resources to make cost attribution easy across environments (dev, staging, production).

Conclusion

AWS AppSync gives you a solid observability foundation through native CloudWatch integration. Start with the standard metrics (Latency, 5XXError, 4XXError, Requests) and set alarms so your team is never surprised by a spike in production. Enable CloudWatch Logs at the Error field level, activate X-Ray for distributed tracing, and reach for Enhanced Metrics when you need to pinpoint a specific resolver or data source.

As your API grows, Logs Insights queries and a well-organized CloudWatch dashboard will save your team significant time during incident response. For teams running multiple AWS services, a unified observability platform like CubeAPM can reduce the number of consoles you need to check during an incident and give you correlated context in a single place.

Disclaimer: AWS service features, pricing, and console navigation may change after the publication of this article. Always refer to the official AWS AppSync documentation for the most current information.

FAQs