Skip to content
This repository has been archived by the owner on Nov 12, 2024. It is now read-only.

Commit

Permalink
docs: upstream
Browse files Browse the repository at this point in the history 
planetscale/www@8e79510
  • Loading branch information
@planetscale-actions-bot
planetscale-actions-bot committed Nov 16, 2023
1 parent 1de5d91 commit 575aa0a
Showing 1 changed file with 76 additions and 50 deletions.
126 changes: 76 additions & 50 deletions docs/concepts/query-insights.md
View file
Original file line number Diff line number Diff line change
@@ -1,119 +1,145 @@
---
title: 'Query Insights'
subtitle: 'Find and optimize long-running queries in your application.'
date: '2022-12-01'
date: '2023-11-16'
---

PlanetScale Insights gives you a detailed look into the active queries running against your database. This in-dashboard tool allows you to identify queries that are running too often, too long, returning too much data, producing errors, and more. You can scroll through the performance graph to detect the time that a query was impacted and, if applicable, the [Deploy Request](/docs/concepts/deploy-requests) that affected it.

You can also see a [list of all queries](#queries-list) performed on your database in the last 24 hours. For further analysis, you can sort these by metrics like amount of rows read, time per query, and more.
You can also see a [list of all queries](#queries-overview) performed on your database in the last 24 hours. For further analysis, you can sort these by metrics like amount of rows read, time per query, and more.

## Insights page overview

To view Insights for your database, head to the [PlanetScale dashboard](https://app.planetscale.com), select your database, and click the "**Insights**" tab.

Below is an overview of what you'll find on this page. If you'd like to see a practical example of how to use Insights to debug a performance issue, check out our [Announcing Insights blog post](/blog/introducing-planetscale-insights-advanced-query-monitoring).
The dropdown on the top right lets you select which branch you want to analyze. You can also choose which servers you want to view insights for: primary or replicas.

{% vimeo aspect="other" src="https://player.vimeo.com/video/830571854" caption="This video shows an example Insights page. All explanations are covered in this doc." /%}
![PlanetScale Insights overview page](/assets/docs/concepts/query-insights/query-insights-overview.png)

You can click the dates listed above the graph to scroll through the past seven days. To further narrow down query analysis, you can select a time range by clicking on the graph and dragging the cursor across. This will zoom in on the selected timeframe.

{% callout %}
On the free Hobby plan, query insights are limited to the previous 24 hours. To unlock the full seven days of
analytics, [upgrade to a paid plan](/docs/concepts/billing).
{% /callout %}

## Branch selection
You also have the option to save a screenshot of the graph by clicking "Save".

If any deploy requests were deployed during the selected period, you will also see an overlay with a link to the deploy request. This can help you quickly assess any impact a deploy request had on your database.

### Queries overview table

The table underneath the graph shows all queries performed on your database in the selected timeframe (last 24 hours by default).

For more information about how to read and interpret this data, see the [Queries overview](#queries-overview) section.

### Insights graph tabs

Once you have selected the branch and server you want to analyze, you can begin exploring the insights for them in the following tabs:

![PlanetScale Insights branch selection](/assets/docs/concepts/query-insights/branches-2.jpg)
- [Query latency](#query-latency)
- [Queries](#queries)
- [Rows read](#rows-read)
- [Rows written](#rows-written)
- [Errors](#errors)

The dropdown on the top right lets you select which branch you want to analyze. The selection applies to the entire Insights page.
The remaining sections of this doc walk through how to interpret and act on the data in each tab. If you'd like to see a practical example of how to use Insights to debug a performance issue, check out our [Announcing Insights blog post](/blog/introducing-planetscale-insights-advanced-query-monitoring) or [this YouTube video](https://www.youtube.com/watch?v=kkjAxSViOAA) walking you through an example.

## Insights graph
## Query latency

![PlanetScale Insights graph](/assets/docs/concepts/query-insights/graph-2.jpg)
The default tab depicts your database's query latency in milliseconds over the last 24 hours.

This graph depicts your database activity over a 24-hour period. You'll also see links to any deploy requests at the time that you deployed them.
By default, the graph contains two line charts showing `p50` and `p95` latency. This means 50% and 95% of requests, respectively, completed faster than the time listed. You can also click on the `p99` and `p99.9` pills to toggle those on, or click `p50` or `p95` to toggle those off.

You can click the dates listed above the graph to scroll through the past seven days. If you're on our free Hobby plan, activity is limited to the previous 24 hours.
## Queries

## Graph metrics selection
The Queries tab displays insights about all active running queries in your database. The graph displays total queries per second against the specified time period.

![PlanetScale Insights graph metrics selection - rows written](/assets/docs/concepts/query-insights/metrics-2.jpg)
## Rows read

The dropdown on the top left lets you select what metric you want to see on the graph. You can hover over a specific time on the graph to see the metric(s) for that time period.
The Rows read tab displays the total number of rows read per second across the selected time period.

The available options are:
## Rows written

- **Rows read per second** — Total count followed by rows read per second.
- **Rows written per second** — Total count followed by rows written per second.
- **Query latency (ms)** — Two line charts showing p50 and p90 latency. This means 50% and 90% of requests, respectively, completed faster than the time listed.
- **Queries per second** — Total queries per second.
- **Query errors** — Any errors that have been captured on your database. See the **Errors** tab on the table below for a deep dive.
The Rows written tab displays the total number of rows written per second across the selected time period.

## Queries list
## Errors

![PlanetScale Insights recent queries list](/assets/docs/concepts/query-insights/queries-2.jpg)
The Errors tab surfaces any errors that have been captured on your database in a 24 hour period.

The table underneath the graph shows all queries performed on your database in the past 24 hours. To further narrow down query analysis, you can select a time range from the above graph to restrict the table to queries that happened in that time frame.
Underneath the graph, you'll find a list of database error messages that have been captured over the selected period.

You can also sort the columns for quick analysis.
You can click on any of the error messages on the Errors tab to open a more detailed view. This view shows you the individual queries that produced the error, when they ran, how long they ran, and any query tags attached to them.

## Queries overview

![Insights queries selected time range](/assets/docs/concepts/query-insights/timeframe-2.jpg)
The table underneath the graph shows all queries performed on your database in the selected timeframe (last 24 hours by default).

You may see some placeholder values in the queries, such as `:v1`. This is because we consider the actual data private and normalize it away.

{% callout %}
You have the option to [opt in to complete query collection](#complete-query-collection) to see the full SQL statements.
{% /callout %}

**Available query statistics**:
You may also see a red shards icon next to some queries. This signifies that the query requires execution across multiple shards.

This query overviews table shows the same data for all graph tabs except for [Errors](#errors). For more information about the content there, refer to the Errors section.

### Available query statistics

You can customize the metrics that show up on the Queries list by clicking the "Columns" dropdown.

- **Keyspace** — The keyspace(s) being queried or modified.
- **Table** — The table(s) being queried or modified.
- **Count** — The number of times this query has run.
- **Total time (ms)** — The total time the query has run in milliseconds.
- **Time per query (ms)** — The number of milliseconds each individual query takes to run. This is calculated from total time divided by count.
- **Table** — The table(s) being queried or modified.
- **`p50` latency** — The `p50` latency for the query in milliseconds. This means that 50% of requests completed faster than the time listed.
- **`p99` latency** — The `p99` latency for the query in milliseconds. This means that 99% of requests completed faster than the time listed.
- **Rows returned** — The total number of rows fetched by a `SELECT` statement. This includes all times the query has run in the displayed time frame.
- **Rows read** — The total number of rows read. This includes all times the query has run in the displayed time frame. This is the number that directly affects your [rows read billing calculation](/docs/concepts/billing#understanding-rows-read).
- **Rows read/rows returned** — The result of dividing total rows read by rows returned in a query. A high number can indicate that your database is reading unnecessary rows, and they query may be improved by adding an index.
- **Rows affected** — The total number of rows modified by an `INSERT`, `UPDATE`, or `DELETE` statement. This includes all times the query has run in the displayed time frame.
- **Last run** — The last time a query was run.

You can customize the metrics that show up on the Queries list by clicking the "Columns" dropdown.
You can also sort the columns for quick analysis by clicking on the title at the top of each column.

## Query deep dive
### Query filtering

Clicking on a query in the Queries list will open a new page with more information about that query, such as:
The search bar above the table allows you to filter queries as needed. You can filter for table name, tag name, tag value, user name, exact string match, query count, multisharded queries, and [Boosted](/docs/concepts/query-caching-with-planetscale-boost) queries. Click on the `?` next to the search bar for the full list of search syntax.

- **The query pattern** — The query with data normalized away. This query may run several times with different values, which Insights combines into a single query pattern.
- **Selected instances of the query** — Below the query pattern, we surface any instances of the query that took longer than one second, read more than 10,000 rows, or produced an error.
- **Error messages** — If any exist.
- **Query tags** — If any of the selected queries have [SQL comment](https://google.github.io/sqlcommenter/) tags attached, you'll see the key-value pairs in the table. Note, if you're sending queries with comments using the MySQL shell, make sure you have [enabled comments with the `-c` flag](https://dev.mysql.com/doc/refman/8.0/en/mysql-command-options.html#option_mysql_comments).
- **Query `EXPLAIN` plan** — If you toggle "Show explain plan", you can generate the [execution plan](https://dev.mysql.com/blog-archive/mysql-explain-analyze/) for the selected query. You may have to fill in some sample values designated with placeholders like `:v1`. We use placeholders in the patterns both so you can look at whole patterns at once and so the literal values remain private.
- **Query metrics** — A graph of the metrics associated with this query. The set of available metrics is the same as the database level metrics graphs.
### Query deep dive

If you'd like to further interact with the query, click "Open query in web console", and you'll be taken to your in-dashboard web console, where you can run the `EXPLAIN` plan.
Clicking on a query in the Queries list will open a new page with more information about that query.

You'll first see the full query pattern, which displays the query with data normalized away. This query may run several times with different values, which Insights combines into a single query pattern.

You can also toggle on the [query `EXPLAIN` plan](/blog/how-read-mysql-explains) by clicking "Show explain plan", which generates the [execution plan](https://dev.mysql.com/blog-archive/mysql-explain-analyze/) for the selected query. You may have to fill in some sample values designated with placeholders like `:v1`. We use placeholders in the patterns both so you can look at whole patterns at once and so the literal values remain private.

Note, if you're viewing the `EXPLAIN` plan on a production branch, this button will be disabled unless you enable production web console access in your database Settings page.

![PlanetScale Insights query pattern w/ explain plan](/assets/docs/concepts/query-insights/query.jpg)
![PlanetScale Insights explain plan](/assets/docs/concepts/query-insights/explain.jpg)
If you'd like to further interact with the query, click "Open query in web console", and you'll be taken to your in-dashboard web console, where you can run the `EXPLAIN` plan.

## Database errors
#### Additional query information

The table underneath the top graph also contains an **Errors** tab, which shows you a list of database error messages that have been captured over the last 24 hours. You can click the dates listed above the graph to scroll through the past seven days. If you're on our free Hobby plan, activity is limited to the previous 24 hours.
Beneath the query pattern is a graph with more information about the query. The set of available metrics/tabs is the same as the main database-level metrics graphs: Query latency, Queries, Rows read, Rows written, and Errors.

![PlanetScale Insights errors tab](/assets/docs/concepts/query-insights/errors.jpg)
#### Notable queries

You can click on any of the error messages on the Errors tab to open a more detailed view. This view shows you the individual queries that produced the error, when they ran, how long they ran, and any query tags attached to them.
Underneath the graph, you'll see a table with more information about notable instances of the query, which are defined as queries that took longer than 1s, read more than 10,000 rows, or produced an error.

![PlanetScale Insights errors tab deep dive showing queries](/assets/docs/concepts/query-insights/errors-detailed-view.jpg)
If any of the selected queries have [SQL comment tags](https://google.github.io/sqlcommenter/) attached, you'll see the key-value pairs in the table under `Tags`.

## Complete query collection
{% callout %}
If you're sending queries with comments using the MySQL shell, make sure you have [enabled comments with the `-c` flag](https://dev.mysql.com/doc/refman/8.0/en/mysql-command-options.html#option_mysql_comments).
{% /callout %}

If you would prefer to view the raw query data using Insights, you can enable this option in your database settings page. In the dashboard, select your database, click "**Settings**", scroll down until you see "**Complete query collection**", and click "**Enable**" to opt in.
The table also surfaces when the query started, rows returned, rows read, rows affected, the time it took the query to run (in ms), and the user associated with the query.

![PlanetScale Insights complete query collection opt in](/assets/docs/concepts/query-insights/opt-in.jpg)
### Complete query collection

With this enabled, Insights will gather the complete raw SQL statements and display them when a query deep dive is selected and in the `EXPLAIN` plan. For example, if you select a query from the table on the Insights page, the query pattern and the selected queries below it will display the full query.
If you would prefer to view the raw query data using Insights, you can enable this option in your database settings page. In the dashboard, select your database, click "**Settings**", scroll down until you see "**Complete query collection**", and click "**Enable**" to opt in.

![PlanetScale Insights unnormalized data in query deep dive](/assets/docs/concepts/query-insights/unnormalized-data.jpg)
With this enabled, Insights will gather the complete raw SQL statements and display them when a query deep dive is selected and in the `EXPLAIN` plan. For example, if you select a query from the table on the Insights page, the query pattern and the selected queries below it will display the full query.

Enabling complete query collection is beneficial when performance varies significantly within the same query pattern, and you need to see the full SQL statement, without placeholders, to identify the correct source of the performance issue.

Expand Down

0 comments on commit 575aa0a

Please sign in to comment.