Overview of Key Visualizer

What is Key Visualizer?

Key Visualizer helps you analyze your Cloud Spanner usage patterns. It generates visual reports for your databases broken down by ranges of rows over time.

Key Visualizer provides insights into usage patterns at scale that are difficult to understand otherwise. Uses for Key Visualizer include:

  • Iteratively designing a schema or improving the design of an existing schema. In each iteration, you check Key Visualizer to spot problems your schema may be causing, then tune your schema and check again.
  • Troubleshooting performance issues to understand how queries and operations use resources.
  • Understanding how your users and applications access the data that you store in Cloud Spanner.

To accomplish these goals, Key Visualizer can help you complete the following tasks:

  • Check whether your reads or writes are creating hotspots on specific row ranges.
  • Look at whether your access patterns are balanced across all of the rows in a table.

Although Key Visualizer shows a variety of metrics, it doesn't capture everything that can affect the performance of Cloud Spanner. For example, if there are network issues between your application and Google Cloud, those network issues might not be visible, or they might appear as vertical bands across all keys in Key Visualizer, which only gives you hints about when the problems occurred. If you can't identify the cause of a performance issue by looking at your Key Visualizer scans, you'll need to do additional troubleshooting.

Key Visualizer scans

The following image shows a Key Visualizer scan. Each scan includes a few different types of information:

  • A large heatmap, which shows access patterns for a group of row keys over time.
  • Aggregate values along each axis of the heatmap, including average values and either total or maximum values.

Example of a Key Visualizer scan

Key Visualizer also provides tools to help you understand the data in each scan. If you haven't used Key Visualizer before, see Getting Started with Key Visualizer for instructions. If you're a more experienced user, see Exploring heatmaps.


The core of a Key Visualizer scan is the heatmap, which shows the value of a metric over time, broken down into contiguous ranges of row keys. The x-axis of the heatmap represents time, and the y-axis represents row ranges. If the metric had a low value for a row range at a point in time, the metric is "cold," and it appears in a dark color. A high value is "hot," and it appears in a bright color; the highest values appear in white.

Different types of usage result in different visual patterns within the heatmap, which can make it possible to diagnose issues at a glance. See Heatmap patterns for examples of some common patterns.

Row ranges

A row range is a contiguous set of rows within a single table or index. It is defined by a start key and an end key.

A Cloud Spanner database typically uses many tables and indexes. Key Visualizer selects up to 1,000 row ranges based on the existing keys in all tables and indexes across the entire database. On the heatmap, each key is first sorted based on its table or index name alphabetically. Within each table or index, keys are sorted by their primary key values. As a result, a row range only consists of keys from a single table or index. For interleaved tables, row ranges of a parent table do not include any keys from its interleaved child tables.

Key Visualizer selects at most 1,000 row ranges. When there are more than 1,000 combined tables and indexes, some of those tables are rolled up into a single data point on the heatmap and are shown as a single line. Therefore, potential hotspots may be hard to detect due to their tables being combined and downsampled.

If there are fewer than 1,000 tables and indexes, the heatmap will have at least one row range representing every table.

What's next