Overview of Key Visualizer

This page provides an overview of the Key Visualizer diagnostic tool for Cloud Bigtable.

Key Visualizer provides a detailed look at how you use data in your Cloud Bigtable tables. You can also use the Google Cloud Console and Cloud Monitoring to get a high-level overview of your Cloud Bigtable usage. See Monitoring a Cloud Bigtable Instance for details.

What is Key Visualizer?

Key Visualizer is a tool that helps you analyze your Cloud Bigtable usage patterns. It generates visual reports for your tables that break down your usage based on the row keys that you access.

Key Visualizer can provide insights into usage patterns at scale that are difficult to understand otherwise. Uses for Key Visualizer include the following:

  • 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 tweak your schema and check again.
  • Troubleshooting performance issues.
  • Getting a better understanding of how you access the data that you store in Cloud Bigtable.

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

  • Check whether your reads or writes are creating hotspots on specific rows
  • Find rows that contain too much data
  • 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 display every single metric that can affect the performance of Cloud Bigtable. For example, if there are network issues between your application and Google Cloud, those network issues will not be visible in Key Visualizer. 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.

Video tour of Key Visualizer

Watch an interactive walk-through of Key Visualizer's major features.

Key Visualizer scans

Key Visualizer automatically generates hourly and daily scans for every table in your instance that meets at least one of the following criteria:

  • During the previous 24 hours, the table contained at least 30 GB of data at some point in time.
  • During the previous 24 hours, the average of all reads or all writes was at least 10,000 rows per second.

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 for details.


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 keys. If the metric had a low value for a group of row keys 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.

By default, a Key Visualizer heatmap shows the Ops metric, which represents the combined number of reads and writes. You can switch to the heatmap for a different metric at any time. See Switching metrics for details.

You can also view more than one metric at a time, which can help you find connections between different metrics.

Hierarchical row keys

Row keys are often composed of a hierarchy of values, with each value separated by a delimiter. For example, the row key memusage#1423523569918 contains an identifier for all rows that capture memory usage, followed by a timestamp that identifies a specific set of data within that group.

Key Visualizer automatically recognizes this type of row key and breaks it down into a hierarchy of tabs, as shown on the left side of the example above. This feature helps you understand how your data and access patterns are distributed across the table's rows. It also enables you to drill down into the data for specific ranges of row keys more quickly.

If your row keys are not composed of multiple values, Key Visualizer still displays tabs on the left side of the scan, but the tabs might split up your row keys in unexpected ways rather than presenting a clear hierarchy.

Key buckets

A Cloud Bigtable table can have trillions of rows, so it's not always practical to report metrics for each individual row. Instead, Key Visualizer divides all of the row keys into 1,000 contiguous ranges, with roughly the same number of row keys in each range. These ranges are known as key buckets.

Key Visualizer reports most metrics as averages over each key bucket, or as maximum values within each key bucket. For Warnings metrics and Performance metrics, Key Visualizer provides higher precision by reporting metrics for individual row keys or for specific key ranges within the key bucket.

Aggregate values

In addition to the heatmap, a Key Visualizer scan includes aggregate values in bar charts along the bottom and right sides of the heatmap. When you hover over the aggregate values, Key Visualizer highlights a narrow area in the heatmap and shows the following information:

  • For the x-axis, Key Visualizer shows the average value for the current metric, along with either the total or maximum value. These values appear for all of the visible key ranges in 15-minute intervals.
  • For the y-axis, Key Visualizer shows the average value for the current metric across the visible time range, broken down into key ranges.

What's next