# How to Diagnose Bigtable Hotspotting Using Key Visualizer > Diagnose Bigtable hotspotting effectively using Key Visualizer and gcloud commands. Identify high-density row keys and pinpoint tablets with high CPU usage to optimize performance. - Repository: [Google/skills](https://github.com/google/skills) - Tags: how-to-guide - Published: 2026-08-13 --- **Use the Key Visualizer heat-map in the Google Cloud Console to identify high-density row-key ranges, then corroborate with the `gcloud bigtable hot-tablets list` command to pinpoint specific tablets with elevated CPU usage.** When a Cloud Bigtable cluster experiences uneven traffic distribution, a single tablet can become overwhelmed, causing degraded performance and uneven resource utilization across your cluster. According to the diagnostic workflow documented in the `google/skills` repository, the most effective way to identify these imbalances is to analyze how row-key accesses are distributed using the **Key Visualizer** tool. ## Understanding Bigtable Hotspotting Hotspotting occurs when a disproportionate amount of read or write traffic targets a single tablet—or a small set of tablets—within a Cloud Bigtable cluster. This concentration causes specific nodes to exhibit high CPU and memory utilization while others remain underutilized, degrading overall cluster performance. The root cause typically lies in the row-key design, where sequential keys (such as timestamps) cause traffic to concentrate on the latest tablet. As implemented in `google/skills`, the diagnostic approach involves correlation between visual heat-maps and CLI-based tablet statistics to confirm the exact location of the bottleneck. ## Step 1: Analyze Access Patterns with the Key Visualizer The **Key Visualizer**—accessible directly in the Google Cloud Console—renders a heat-map of read and write activity across your table's row-key ranges. This visualization allows you to see which specific keys (and thus which underlying tablets) receive the most traffic. Navigate to the Key Visualizer using the following URL pattern: ```text https://console.cloud.google.com/bigtable/instances//key-visualizer?project= ``` In the heat-map interface, rows that appear in **red** indicate high request density. These red zones represent hotspots where traffic is concentrated. This visual representation, documented in [`skills/cloud/bigtable-basics/references/infrastructure_management.md`](https://github.com/google/skills/blob/main/skills/cloud/bigtable-basics/references/infrastructure_management.md) lines 98-102, provides immediate insight into whether your row-key distribution is causing uneven load. ## Step 2: Validate with the Hot-Tablet CLI After identifying suspicious key ranges in the Key Visualizer, corroborate your findings using the `gcloud` CLI to retrieve specific tablet-level CPU metrics. This step confirms which physical tablets are experiencing the highest load. Execute the following command, replacing the environment variables with your specific cluster and instance names: ```bash gcloud bigtable hot-tablets list ${BIGTABLE_CLUSTER} --instance=${BIGTABLE_INSTANCE} ``` The command returns tablet IDs along with their respective CPU usage percentages. According to the source analysis in [`skills/cloud/bigtable-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/bigtable-basics/SKILL.md) lines 27-31, tablets consistently showing CPU usage above approximately **70%** are likely the primary cause of performance degradation. Cross-reference these tablet IDs with the red zones observed in the Key Visualizer to confirm the diagnosis. ## Step 3: Deep Dive with Per-Tablet Statistics For advanced analysis, you can fetch detailed per-tablet statistics using the `cbt` CLI tool. This optional step provides granular visibility into request latency and throughput for specific row-key ranges. ```bash cbt read --include-stats=full ``` This output helps distinguish between read-heavy and write-heavy hotspots, informing whether you need to optimize for scan performance or write throughput in your remediation strategy. ## Interpreting the Results When analyzing Key Visualizer output and CLI data together, look for these indicators: - **Red heat-map zones** in the Console UI indicate row-key ranges receiving disproportionate traffic - **Sustained CPU above 70%** in the `hot-tablets list` output confirms the tablet is resource-constrained - **Correlation** between the visual heat-map and the CLI tablet list validates that the hotspot is caused by row-key distribution rather than node-level hardware issues If the Key Visualizer shows sequential red patterns (e.g., a diagonal line or a concentrated block at the end of the key space), this strongly suggests that monotonically increasing row keys (like timestamps) are causing the hotspot. ## Remediation Strategies Once you diagnose Bigtable hotspotting using the Key Visualizer, address the root cause by redesigning your row-key scheme to distribute traffic evenly. Effective strategies include: - **Salting**: Prepend a random or hash-based prefix to row keys to scatter writes across multiple tablets - **Field promotion**: Swap the order of key components so that high-cardinality fields appear first - **Time sharding**: Replace raw timestamps with reversed timestamps or bucketing to prevent the "latest tablet" problem These architectural changes ensure that the load spreads evenly across the cluster, eliminating the red zones visible in the Key Visualizer heat-map. ## Summary - **Hotspotting** in Cloud Bigtable occurs when traffic concentrates on single tablets, causing performance degradation - The **Key Visualizer** in the Google Cloud Console displays a heat-map where red indicates high-traffic row-key ranges - Use `gcloud bigtable hot-tablets list` to confirm specific tablets with CPU usage exceeding ~70% - Reference [`skills/cloud/bigtable-basics/references/infrastructure_management.md`](https://github.com/google/skills/blob/main/skills/cloud/bigtable-basics/references/infrastructure_management.md) and [`skills/cloud/bigtable-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/bigtable-basics/SKILL.md) in the `google/skills` repository for the authoritative diagnostic workflow - Remediation requires redesigning row keys through salting, field promotion, or time sharding to distribute load evenly ## Frequently Asked Questions ### What is Bigtable hotspotting? Bigtable hotspotting is a performance issue where a disproportionate amount of read or write traffic targets a single tablet or small subset of tablets within a cluster. This creates uneven CPU and memory utilization, causing some nodes to become overloaded while others remain underutilized, which degrades overall application performance. ### How do I access the Key Visualizer? Navigate to the Key Visualizer through the Google Cloud Console using the URL pattern `https://console.cloud.google.com/bigtable/instances//key-visualizer?project=`, or select "Key Visualizer" from the instance details page in the Bigtable section of the Console. No additional authentication is required beyond standard Cloud IAM permissions for Bigtable viewer roles. ### What CPU threshold indicates a hot tablet? Tablets consistently showing CPU usage above approximately **70%** in the output of `gcloud bigtable hot-tablets list` are considered hot and likely contributing to performance degradation. This threshold, derived from the `google/skills` source analysis, indicates that the tablet is receiving more traffic than it can efficiently process. ### How can I fix hotspotting after diagnosing it with Key Visualizer? After confirming hotspots using the Key Visualizer red zones and CLI correlation, redesign your row-key scheme to distribute traffic more evenly. Implement **salting** by adding hash prefixes to keys, use **field promotion** to place high-cardinality fields first, or apply **time sharding** techniques like reverse timestamps to prevent sequential write patterns.