# Overview

PolyScale provides a complete window into database activity and cache performance. These visualizations and metrics can be found under the Observability tab within the user interface for any cache.

PolyScale's Observability is structured using two interchangeable views; Summary and Details.

The Summary view provides quick answers to questions such as how busy in the platform, what should be cached and how beneficial is the cache. The Details view provides access to deep insight to answer specifics such as hit and miss ratios, payload sizes as well as detailed execution times to name but a few.

Detailed below is a description of each metric and its application.

# Summary View

## Topics​

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​

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.

### Cache performance​

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.

### Execution time​

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​

Cache configuration is principally measured by the current TTL setting. The TTL is the setting that specifies how long a specific query is cached for. Read more about Cache Configuration. 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

## Query Traffic​

### Counts​

This is the total number of queries. All queries are counted, subject to the filters set at the top row. This metric is used to verify that query traffic is indeed flowing through Polyscale, as well as to reveal changes in query traffic. This is the same query count statistic shown on the Summary view.

### Hits​

This is the total number of queries resulting in cache hits. The number of cache hits is used to demonstrate that the cache is functioning where it is active, and also validate changes in cache settings.

### Misses​

This is the total number of queries resulting in cache misses. The number of misses plus the number of hits will always be equal to the total number of queries. Similar to the hits metric, misses count is used to verify that the cache is doing what it is configured to do.

### Distinct​

This is the number of unique queries that match the specific query template. The actual query result that is cached corresponds to a particular query within the space of the template. All else being equal, queries with low distinct counts benefit more from caching.

### Results​

This is the number of unique query-result pairs within a specific query template. For example, there may be two queries that match a query template, and each of these may have resulted in four different results, that would yield a results count of eight. This count allows one to measure data change rates as well as query counts.

### Size​

This is the average size of a query result. Queries that yield large results are often (but not always!) place a burden on the database server. Caching queries with large size is beneficial.

## Cache Performance​

### Cacheability​

This is the composite metric that scores the benefit to be had from caching this query. A high cacheability score indicates a query that should be cached. Values are normalized so that the highest score is one, and the lowest score is zero. This is the same metric that is seen on the Summary view.

### Hit Rate​

This is the ratio of the number of queries that are cache hits to the total number of queries. A hit ratio of 100% would mean every query was a hit (this is technically not possible since it takes one miss per TTL period to establish the cached value). A hit ratio of 0% would mean no hits. For queries with high cacheability, hit rates of 90% or better should be targeted.

## Execution Time​

The execution time metrics are separated into two categories, Total and Average. The total times help one to consider the overall effect a query has. The average times measure the execution time independent of how often that particular query occurs.

### Total Saved​

This is the total time saved due to the presence of the cache. It is calculated as the difference between the nominal time and the actual time. It is the same metric presented on the Summary view.

### Total Actual​

This is the total time taken by the queries. The time is measured from the moment the query arrives at PolyScale, until the time the response is sent. For an uncached query, this is the sum of the times it takes to send the query to the database, evaluate the query, and return the result. For a cached query it is just the time it takes to recognize the result is cached and recover the query result from the cache.

### Total Nominal​

This is the total amount of time queries would have taken if there were no cache. For queries that do use the cache it is estimated by taking the total number of queries times the average execution time of an uncached query. For uncached queries the total actual time and the total nominal time are the same.

### Average All​

This is the average time taken for all queries (both hits and misses). It is the total actual time divided by the number of queries. Queries with the largest average-all time are taking the most time even with the effects of the cache.

### Average Hit​

This is the average time taken for queries that hit the cache. These times should be very short (at or near zero) when things are working as they should be. A long average hit time may occur for very large queries or during times of exceptional load.

### Average Miss​

This is the average time taken for queries that miss the cache. This is the time it takes for a query to make the round trip to the database server plus the time it takes for the server to evaluate it. Because the cache overhead of a miss is negligible, this is the time a query would take without the cache at all.

## Cache Configuration​

### Current​

This is the current TTL setting for this query. This value may originate from a TTL setting for the query template itself or for the table this query refers to (see Cache Configuration). The value presented in the table is the most recent value available from the configuration. The value presented in the heatmap or other graphics is the value that was being used at the time that the underlying query occurred.

This is the recommended TTL value. It is computed based on the arrival rate and distinct number of queries within the query template. Using the recommended value should yield a hit rate of 95% or better.