This page shows examples of patterns that you might see in a Key Visualizerheat map. These patterns can help you to troubleshoot specific performanceissues.

Some issues that are exposed in Key Visualizer relate to your primary keydefinition. Because a primary key is immutable, these issues are best discoveredduring the design, or proof of concept, stage.

Other issues may relate to your instance's node allocation. You may need toprovision additional capacity, either overall or possibly at certain times ofday. To change the number of nodes associated with your instance, seeChanging the number of nodes.

• To learn how to open a Key Visualizer scan, seeViewing the scan for a timeperiod.
• To find out how to explore a Key Visualizer scan in detail, seeExploringHeatmaps.

Before you read this page, you should be familiar with theoverview of Key Visualizer.

Evenly distributed reads and writes

If a heatmap shows a fine-grained mix of dark and bright colors, then reads andwrites are evenly distributed throughout the database. This heatmap representsan effective usage pattern for Spanner, so you do not need to takeany action.

Your own heatmap may not be as evenly distributed as this but still illustratea healthy schema and workload. Some number of hotspots can be expected in aproperly resourced configuration.

Monotonically increasing keys

A heatmap with a single bright diagonal line, or a triangle with a flat top,can indicate a database that uses sequential keys. Sequential keys are ananti-pattern in Spanner; see theSchema design best practices page for whysequential keys cause hotspots.

Persistently hot key ranges

If a heatmap shows horizontal bands of bright color, separated by dark colors,it indicates that specific row ranges are consistently being more heavilyaccessed over time.

To address this issue, consider changing your schema design or your applicationso that the data in a heavily used row, or in an excessively large row, isspread across multiple rows.

Single hot table

If a heatmap shows a band of bright color in a single table, itindicates heavy access of that table over time.

This pattern by itself is not necessarily problematic. If you're seeing thispattern in combination with performance issues, you'relikely running out of compute capacity. Some things to consider:

• Your application may be requesting a full table scan, which will show inKey Visualizer as a bright band of the whole table. Instead, considera more restrictive query, or query against the index to reduce the number ofrows being scanned.

• Increase the number of nodes for this instance.

Roving reads and writes over times

A heatmap showing multiple diagonal bright lines (rising or falling)usually indicates sequential reads or writes to rows in a short period of time.

If the lines correspond with read activity, such as a table export, no action isrequired. If you're experiencing performance issues during these reads, considerincreasing the number of nodes for your instance during thesetime periods. You can decrease the node number between periods.

If the lines correspond with write activity, and you're experiencing performanceissues, you should consider changing your workload to a random write instead ofa sequential write.

Sudden traffic increase

A heatmap showing bright horizontal bands that appear partway across the heatmapindicate a sudden change in the usage pattern of a database. This can be a roguequery or an unexpected surge in activity for certain rows.

Caveats

There are some scenarios where Key Visualizer may not present a complete pictureof performance and resource usage.

What's next

• Learn how toget started with Key Visualizer.
• Find out how toexplore a heatmap in detail.
• Read about themetrics you can view in a heatmap.