Overview of introspection tools

Introspection tools for Cloud Spanner enable you to investigate issues with your database. They consist of a set of built-in tables that you can query to gain more insight about queries, transactions, reads and more. Not sure which tool to use for a particular problem? The following list summarizes each tool and the kinds of questions they can help answer.

Query statistics

To help investigate issues on your database, it is helpful to know which queries are expensive, run frequently or scan a lot of data.

Query statistics are aggregated statistics for successfully completed queries gathered in 1, 10, and 60 minute intervals. The statistics include highest CPU usage, total query execution counts, average latency, most data scanned, and additional basic query statistics. Use these statistics to help identify expensive, frequently run or data-intensive queries.

Oldest active queries

Sometimes you want to look at the current workload on the system by examining running queries. Use the Oldest active queries tool to investigate long running queries that may be having an impact on database performance. This tool tells you what the queries are, when they started running and to which session they belong.

Read statistics

Read statistics can be used to investigate the most common and most resource-consuming reads on your database using the Cloud Spanner Reads API. These statistics are collected and stored in 3 different time intervals - minute, 10 minutes and an hour. For each time interval, Cloud Spanner tracks the reads that are using the most resources.

Use read statistics to find out the combined resource usage by all reads, find the most CPU consuming reads, and find out how a specific read's frequency changes over time.

Transaction statistics

Transaction statistics can be used to investigate transaction-related issues. For example, you can check for slow-running transactions that might be causing contention or identify changes in transaction shapes that are leading to performance regressions. Each row contains statistics of all transactions executed over the database during 1, 10, and 60 minute intervals.

Operations included in each tool

In Cloud Spanner there is some overlap between transactions, reads and queries. Therefore, it might not be clear which operations are included when compiling results for each introspection tool. The following table lists the main operations and their relationship to each tool.

Operation Query statistics Oldest active queries Read statistics Transaction statistics
Strong read No No Yes No
Stale read No No Yes No
Single-use transaction1 (reads) No No Yes No
Single-use transaction1 (queries) Yes Yes No No
Read-only transaction1 (reads) No No Yes No
Read-only transaction1 (queries) Yes Yes No No
Read-write transaction (reads) No No Yes Yes
Read-write transactions (queries) Yes Yes No Yes
Read-write transactions (DML2, Mutations3) No Yes4 No Yes


1 Read-related transactions, such as read-only transactions and single-use transactions, are not included in transaction statistics. Only read- write transactions are included in the transaction statistics table.

2 Uncommitted DML operations are not included in transaction statistics.

3 Empty mutations that are effectively no-op, are not included in transaction statistics.

4 The query parts of DML operations are included in oldest active queries results.