How do I troubleshoot issues with Performance Insights and CloudWatch Database Insights for Aurora clusters and instances?

Short description

Important: Performance Insights will reach its end of life on June 30, 2026. You can upgrade to the Advanced mode of Database Insights before June 30, 2026. If you don't upgrade, then DB clusters that use Performance Insights will default to the Standard mode of Database Insights. Only the Advanced mode of Database Insights will support execution plans and on-demand analysis. If your clusters default to the Standard mode, then you might not be able to use these features on the console. To turn on the Advanced mode, see Turning on the Advanced mode of Database Insights for Amazon RDS and Turning on the Advanced mode of Database Insights for Amazon Aurora.

When you don't correctly configure the components for Performance Insights and Database Insights, you experience issues.

The following components can cause issues:

• Aurora version and AWS Region availability
• Instance type
• AWS Identity and Access Management (IAM) policies
• The MySQL Performance Schema
• SQL text quota
• Resource utilization
• Transient network issue or system maintenance on your DB instance
• A database load (DB load) on your DB instance that's below the threshold

Resolution

Aurora version and Region availability

Depending on your parallel query configuration, your engine version and AWS Region might not be available for Performance Insights and Database Insights.

If you turned off parallel query, then all versions of Aurora MySQL-Compatible 2 and Aurora MySQL-Compatible version 3 clusters are available in all Regions.

If you turned on parallel query, then all versions of Aurora MySQL 2 are available in the Asia Pacific (Hyderabad) Region. For all other Regions, only version 2.09.0 and later are available. Aurora MySQL-Compatible version 3 isn't available.

You can view Performance Insights proactive recommendations only in specific Regions. To view a list of supported Regions, see Amazon Aurora DB engine, Region, and instance class support for Performance Insights features.

All Regions except China (Beijing) and China (Ningxia) support Database Insights. For more information, see Amazon Aurora DB engine, Region, and instance class support for Database Insights features.

Instance type

The following DB instance classes don't support Performance Insights and Database Insights:

• db.t2
• db.t3
• db.t4g.micro and db.t4g.small

You can't analyze database performance for a period of time or view Performance Insights proactive recommendations on the db.serverless instance class.

IAM policies

The following are common examples of how you can use IAM policies to access Performance Insights:

• Attach the AmazonRDSPerformanceInsightsReadOnly policy to an IAM principal.
• Attach the AmazonRDSPerformanceInsightsFullAccess policy to an IAM principal.
• Create a custom IAM policy.
• Update an AWS Key Management Service (AWS KMS) policy.
• Grant fine-grained access control.

To access Database Insights, you must use the following open access permissions:

• cloudwatch:*
• logs:*
• rds:*
• pi:*

Note: It's a best practice to follow the principle of least privilege. For more information, see Required permissions for Database Insights.

The MySQL Performance Schema

The Performance Schema is an optional MySQL feature that monitors internal events with minimal effect on performance. 

The type of metrics that the Performance Schema monitors depends on the management mode setting that you configure:

• If you set Performance Schema to ON (Automatic management mode), then you get detailed low-level metrics.
• If you set Performance Schema to ON (Manual management mode), then you get partial detailed metrics.
• If you set Performance Schema to OFF (Management mode N/A), then you don’t get wait event reports and can access only basic metrics.

If you can't view detailed low-level metrics on the Performance Insights dashboard, then reset the following parameters and set the Source column to Engine default:

• performance_schema=1
• performance-schema-consumer-events-waits-current=ON
• performance-schema-instrument: wait/%=ON
• performance_schema_consumer_global_instrumentation=ON
• performance_schema_consumer_thread_instrumentation=ON

For more information, see Overview of the Performance Schema for Performance Insights on Aurora MySQL.

SQL text quota

The Performance Insights dashboard has a quota for maximum text size. If your text exceeds the quota, then you can't view the entire query on you Performance Insights dashboard. To resolve this issue, reduce your text size.

Resource utilization

If your DB instance experiences a heavy load, then your cluster dedicates resources to the database process. As a result, the cluster deprioritizes system processes, such Performance Insights. To check if your DB instance is under a heavy load, review the CPU utilization and FreeableMemory CloudWatch metrics.

To resolve this issue, take the following actions:

• Resolve high resource utilization issues.
• Modify your DB instance to a larger DB instance class.

Transient network issue or system maintenance on your DB instance

When your DB instance is experiencing a transient networking issue or system maintenance, Performance Insights might not correctly report data. To troubleshoot affected resources, check the AWS Health Dashboard.

Can't view Performance Insights data

If you turn on Performance Insights and you can't view your data, then check the Database load chart and Counter metrics on your Performance Insights dashboard. If there's data under Counter metrics but not on the Database load chart, then your DB load might be below the DB load threshold for MySQL.

To test this issue, run a long-running transaction on your MySQL DB instance, and then check the Performance Insights dashboard again. If the data populates, then your original database load is below the threshold.

To resolve this issue, wait for your DB load to increase before you check your Performance Insights dashboard. The dashboard data populates as your database load increases over time.

Related information

Analyzing Amazon RDS database workloads with Performance Insights

Monitor query performance with Performance Insights on Amazon RDS for Microsoft SQL Server

Performance Insights FAQs

Monitoring DB load with Performance Insights on Amazon Aurora