[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-05 (世界標準時間)。"],[[["\u003cp\u003eKey Visualizer is a diagnostic tool for Firestore in Datastore mode that generates visual reports to analyze usage patterns, including entity access and index modifications.\u003c/p\u003e\n"],["\u003cp\u003eThis tool aids in troubleshooting performance issues, understanding data access, and refining data model designs by identifying hotspots and traffic impacts.\u003c/p\u003e\n"],["\u003cp\u003eKey Visualizer scans cover two-hour periods, displaying heatmaps that represent access patterns or performance metrics across key ranges, and these scans are available for databases that reach at least 3,000 document operations per minute.\u003c/p\u003e\n"],["\u003cp\u003eThe heatmaps display metrics like Ops/s, latency, and index write operations, categorized into key buckets, with each bucket ideally capturing at least 50 Ops/s.\u003c/p\u003e\n"],["\u003cp\u003eData in Key Visualizer is retained for 14 days, impacting the availability of scan data and the validity of shared scan URLs.\u003c/p\u003e\n"]]],[],null,["# Overview of Key Visualizer\n\nThis page provides an overview of the Key Visualizer diagnostic tool for\nFirestore in Datastore mode.\n\nWhat is Key Visualizer?\n-----------------------\n\nKey Visualizer is a tool that helps you analyze your Datastore mode\nusage patterns. It generates visual reports that break down your usage based on\nthe entities that you access or index entries that are written or deleted as\nentities are modified.\n\nKey Visualizer can provide insights into usage patterns at scale.\nUses for Key Visualizer include:\n\n- Troubleshooting performance issues. Key Visualizer helps you identify performance issues in your database caused by hotspots from sequential entity or index keys or sudden traffic increases.\n- Getting a better understanding of how you access the data stored in Datastore mode.\n- Iteratively designing a data model or improving the design of an existing data model. In each iteration, you can check Key Visualizer to spot problems your data model causes.\n\nTo accomplish these goals, Key Visualizer can help you complete the\nfollowing tasks:\n\n- Check whether your reads or writes create hotspots on specific entity ranges.\n- See how a sudden increase in traffic affects latency.\n- Look at whether your access patterns are balanced across your database.\n- Check the structure of index keys to identify the index definitions that cause index load problems.\n- Use the index keys visualization to make better workload pattern predictions.\n\n\u003cbr /\u003e\n\n\n| **Key Term:** Index key\n|\n|\n| In Key Visualizer, the term **Index Key** refers to a index's unique\n| identifier. These can be built-in indexes or composite indexes. For example, the following\n| indexes are some examples of index keys as seen on the Key Visualizer tool:\n|\n| - ``NAMESPACE: '' KIND: Test PROPERTIES: (integer: ASC, description:\n| DESC)ANCESTOR:KEY(PROJECT('PROJECT_ID'),NAMESPACE(''),`Ancestor`,1685558526142092,`Test`,4848490060529664)\n| VALUES: (1,\"tIu9hjuuTpFj0OjDdBe0lX3Zfv8P6pOWKQYxE6hNaol0HrWzGoJ1MHva4T8XupUVccbe4ZCU7Fa1NUhEVBAAcBiUijZw00D0qHbZ\")\n| ENTITY: KEY(PROJECT('PROJECT_ID'),NAMESPACE(''),`Ancestor`,1685558526142092,`Test`,4848490060529664)``\n| - ``NAMESPACE: '' KIND: Test PROPERTIES: (integer: ASC, description:DESC) ANCESTOR:\n| KEY(PROJECT('PROJECT_ID'),NAMESPACE(''),`Ancestor`,1685556682238805,`Test`,5097691411464192)\n| VALUES: (1,\"7m4tJ4nMqmpWgTH9dl6GxgHlnsLbCEZTlFRxVIapvFvXgt3SPogs2bqIDLxAL3GK6Wg1oig7PJi2iin7p3PZueNM5SgqMXwwAm9j\")\n| ENTITY:KEY(PROJECT('PROJECT_ID'),NAMESPACE(''),`Ancestor`,1685556682238805,`Test`,5097691411464192)``\n\n\u003cbr /\u003e\n\nScan eligibility\n----------------\n\n\nEach Key Visualizer scan covers a two hour period. A scan for a given period\nis available for databases with traffic that exceeds 3000 document operations\nin any given minute in that period.\n\n\u003cbr /\u003e\n\nScan eligibility depends completely on database activity. It does not depend\non the amount of data or the type of data in your database.\n\nKey Visualizer scans\n--------------------\n\nThe following image shows a Key Visualizer scan. Each scan includes a\nheatmap that shows access patterns or performance metrics\nfor a group of entity keys or index keys over time.\n\n#### Sharing scan URLs\n\nYou can share or bookmark the URL of a Key Visualizer scan. The URL will open\nthe same Key Visualizer scan and select the same metric. This URL is valid\nuntil the [scan data duration](#data-duration) expires.\n\n### Heatmaps\n\nThe core of a Key Visualizer scan is the heatmap, which shows the value of a\nmetric over time, broken down into up to 1000 contiguous\n[key buckets](#key-buckets).\n\nFor a entity keys heatmap, the x-axis of the heatmap represents time, and\nthe y-axis represents entity keys, while for an index keys heatmap, the\nx-axis of the heatmap represents time, and the y-axis represents index keys.\n\nEach Key Visualizer scan for Firestore in Datastore mode covers two hours of\nactivity divided into 10-second segments.\n\nA low value for a metric is considered \"cold\" and appears as a dark color.\nA high value is \"hot,\" and it\nappears as a bright color. The highest values appear in white.\n\nDifferent types of usage result in different visual patterns within the heatmap,\nwhich can make it possible to diagnose issues at a glance. See [Heatmap patterns\nfor entity keys](./keyvis-patterns) or [Heatmap patterns for index\nkeys](./keyvis-patterns-index) for examples of some common patterns.\n\nKey Visualizer provides tools to help you understand the data in each scan.\nSee [Getting started with Key Visualizer](./keyvis-getting-started) and\n[Exploring heatmaps](./keyvis-exploring-heatmaps).\n\n### Key buckets\n\nKey Visualizer divides all of the keys in your database into up\nto 1,000 contiguous ranges, with roughly the same number of keys and\nOps/s in each range. These ranges are known as *key buckets*.\n\nKey Visualizer uses the total Ops/s of a database to divide key buckets\nso that each bucket captures roughly the same number of Ops/s with a minimum\nintended size of 50 Ops/s per key bucket. For databases\nwith higher total Ops/s, key buckets can capture more than 50 Ops/s each.\nDatabases with less that 50 Ops/s result in scans with a single key bucket.\n\nKey Visualizer reports most metrics as averages over each key bucket, or as\nmaximum values within each key bucket.\n\nMetrics\n-------\n\nThe following metrics are available for entity keys in Key Visualizer scans:\n\nThe following metric is available for index keys in Key Visualizer scans:\n\n### Performance averages\n\nAverage latency metrics take an average over the keys in the key bucket.\nSince this measurement is taken at the storage layer, the latency reported\nhere might be lower than the total latency an API call experiences.\n\nLimits\n------\n\nAlthough Key Visualizer shows a variety of metrics, it doesn't display every\nsingle metric that can affect the performance of Datastore mode. For\nexample:\n\n- Network issues between your application and Google Cloud might not be visible. They might appear as vertical bands across all keys in Key Visualizer which only gives you hints about *when* the problems occurred.\n\nData duration\n-------------\n\nData collected by Key Visualizer for Firestore in Datastore mode is deleted after 14 days.\n\nKey Visualizer data is available for the last 14 days. For example, if you\nlaunch Key Visualizer on December 19 at 12:45 PM, the earliest start time you\ncan choose for a 2-hour time span is December 5 at 1:00 PM.\n\nThis limit also means that if you bookmark or share the URL for a Key\nVisualizer scan, the URL has a maximum life of 14 days.\n\nWhat's next\n-----------\n\n- Learn how to [get started with Key Visualizer](./keyvis-getting-started).\n- Understand the [entity key patterns](./keyvis-patterns) or [index key\n patterns](./keyvis-patterns-index) you might see in Key Visualizer heatmaps.\n- Find out how to [explore a heatmap in detail](./keyvis-exploring-heatmaps)."]]
