PolyScale Database Observability Walkthrough

Matt Calder
Oct 25, 2021

PolyScale is a plug-and-play global database cache that reduces global query latency for databases. Using PolyScale, database reads can be distributed and cached, seamlessly scaling your current database without writing code or altering query or transactional semantics.

PolyScale caching improves user experiences by reducing latency and improves data throughput by reducing database server loads. In addition, through its Observability interface, PolyScale improves developer’s situational awareness. Awareness of the structure of the database load, and how the cache is performing.

Observability at a Glance

Query traffic into the database and its interaction with the cache is a complex, time varying, multidimensional process. PolyScale tames that complexity by organizing metrics across high level topics:

  • Query traffic How much traffic is going to the database server?
  • Cache performance How effective is the PolyScale cache operating?
  • Execution time How much time is being spent across the queries?
  • Cache configuration How is and how ought the PolyScale cache be configured?

Within each of these topics information is presented hierarchically from top level summary to fine grained details. That presentation is projected onto two principal dimensions,

  • Query Template Query templates group queries that differ only parametrically. In what follows, a query refers to a query template unless otherwise qualified.
  • Time Series The trend and variation of a metric over time.

Using the Observability interface developers can look at topic metrics individually or compare across topics, examine variation over time or across queries or both, and focus the level of detail to achieve a complete picture. In addition, the interface is a stepping off point to cache configuration.

Summary View

The entrypoint into the Observability interface is the Summary view, which defaults to the Query Counts metric, viewed over the previous 15 minutes.


The central graphic of the Summary view presents a heatmap of query counts. The heatmap has a row for each query and columns over time. Dark areas represent high counts, and light areas represent fewer counts.

The table beneath the heatmap shows the principal metric for each of the four primary topics with a row for each query. The table allows comparisons to be made between queries and across metrics simultaneously.

Both the graphic and the table support interactivity to navigate the information being presented. In the heatmap, tooltips reveal the underlying values, for both the query count metric, as well as the other topic metrics. The columns of the table can be sorted by clicking the column header which also induces the same order in the heatmap rows. Finally, individual queries can be highlighted by clicking either a heatmap cell or the row.

The other controls to be aware of are in the upper right corner. These control the time range being viewed as well control the data refresh. The default timescale is the last 15 minutes. In order to look back farther simply choose a larger window from the drop down. It is important to realize that some measurements can have a natural frequency, and that viewing them at either too short or too long of a time scale can lead to different conclusions.

Time Scales

Clicking on refresh will toggle the automatic update of the data. If the data appears to update too quickly, or not at all, check the state of this toggle.


The metrics are categorized by four topics and each topic has a principal metric. Clicking on the menu item changes the metric displayed by the heatmap. The four topics are:

Query traffic is principally measured by the query count, the number of times a query matching a specific query template has been made. This number includes all queries, whether or not the query was served from the database or the cache. The query count reveals how much traffic is flowing through the PolyScale connection and so is the first step in establishing that things are functioning. queryCount1200

Cache performance is principally measured by cacheability, a composite number between zero and one that represents the benefit of caching each query. Queries with the highest cacheability occur with high frequency and consistently return the same result. Sorting the queries by their cacheability score is a quick way to hone in on the most important queries from a cache perspective. cacheability1200

Execution time is principally measured by time saved, the total time saved for each query due to caching. This is simply the difference between the total time that would be spent serving a query without the cache minus the total time actually spent executing the query with the cache. For cached queries this directly represents the savings client side in user experience and server side in reduced database load. For uncached queries the time saved is necessarily zero.


Cache configuration is principally measured by the current TTL setting. The TTL setting specifies how long a specific query is cached for. Sorting the queries by their TTL will immediately lift all the queries currently being cached to the top. The heatmap can show when a TTL value was changed.


Details View


The Summary view is intended to give the developer a high level view of all the aspects important to the operation of the database cache. However, sometimes, one needs to dig a little deeper. Toggling the Details button reveals additional features of the Observability interface.


These additional buttons at the top of the interface control the graphic type and filter which queries to view.

On the Details view there are three different graphic types. Query-Template by Time is the same heatmap graphic that was present on the Summary view. The other two graphics give an edge-on view of the heatmap.

By Query-Template gives a bar chart with one bar per query. The bar’s value represents the value of the metric over the entire time period (either average, total, or final, as appropriate).

By Query-Template

By Time gives a time series chart with one line for each query. The bar chart allows one to focus on differences between queries, the time series chart allows one to focus on changes over time, and the heatmap gives a high level view of both.

By Time

The other buttons control which queries are being viewed. The Cached, Uncached, All button allows one to focus on just cached queries (that is, queries that currently have a TTL set), or just uncached queries (those that do not currently have a TTL set), or all queries respectively.

The DQL, All Statements button allows one to filter out non-DQL queries (not SELECT or SHOW queries) or to include them. Depending on the question of interest, these filters can help exclude queries that are not relevant.

The other major change that the Details button exposes is additional metrics. The metrics remain organized by the same four topics of: Query Traffic, Cache Performance, Execution Time, and Cache Configuration, but now the topics reveal drop down menus.


The complete list of metrics is

available here.

The PolyScale Observability interface allows developers to examine query traffic and cache performance at varying levels of detail. It allows them to answer important questions about the nature of that traffic, the benefits that caching is providing, and how to optimize those benefits further.

Next Steps

Ready to try PolyScale.ai? Sign up for a free account here (no credit card required). Or try out PolyScale without bringing your own database with our live interactive demo playground.

Read the Quick Start Guide to understand how easily PolyScale can be integrated without code and without deploying servers.

Written by

Matt Calder