Add docs for health and insights (#32498)

GitOrigin-RevId: 07920401056f71efd690622d13bb0bc09c59e929
get-convex · Dec 20, 2024 · d380527 · d380527
1 parent 66468e0
commit d380527
Show file tree

Hide file tree

Showing 12 changed files with 104 additions and 8 deletions.
diff --git a/docs/dashboard/deployments/data.md b/docs/dashboard/deployments/data.md
@@ -1,7 +1,7 @@
 ---
 title: "Data"
 slug: "data"
-sidebar_position: 0
+sidebar_position: 5
 ---
 
 ![Data Dashboard Page](/screenshots/data.png)

diff --git a/docs/dashboard/deployments/health.md b/docs/dashboard/deployments/health.md
@@ -0,0 +1,95 @@
+---
+title: "Health"
+slug: "health"
+sidebar_position: 0
+---
+
+The [health page](https://dashboard.convex.dev/deployment/) is the landing page
+for your deployment. On this page, you can see some important information about
+the health of your deployment.
+
+## Failure Rate
+
+![Failure Rate Card](/screenshots/health_failure_rate.png)
+
+The failure rate card shows the percentage of failed request by minute ove the
+last hour. The failure rate is calculated as the number of failed requests
+divided by the total number of requests.
+
+## Cache Hit Rate
+
+![Cache Hit Rate Card](/screenshots/health_cache_hit_rate.png)
+
+The cache hit rate card shows the percentage of cache hits by minute over the
+last hour. The cache hit rate is calculated as the number of cache hits divided
+by the total number of requests.
+
+Cache hit rate only applies to query functions.
+
+## Scheduler Status
+
+![Scheduler Status Card](/screenshots/scheduler_overdue.png)
+
+The scheduler status card shows the status of the
+[scheduler](/scheduling/scheduled-functions). If the scheduler falls behind due
+to too many scheduled tasks, the status will show as "Overdue", displaying the
+lag time in minutes.
+
+You may click the button in the top right corner of the card to view a chart
+showing the scheduler status over the last hour.
+
+![Scheduler Status Chart](/screenshots/scheduler_status.png)
+
+## Last Deployed
+
+![Last Deployed Card](/screenshots/health_last_deployed.png)
+
+The last deployed card shows the time of the last time your functions were
+deployed.
+
+## Integrations
+
+<Admonition type="info">
+
+Integrations are only available for paid teams..
+
+</Admonition>
+
+![Last Deployed Card](/screenshots/health_integrations.png)
+
+The integrations card shows the status of your
+[Exception Reporting](/production/integrations/exception-reporting) and
+[Log Streams](/production/integrations/log-streams) integrations, with quick
+links to view and configure your integrations.
+
+## Insights
+
+<Admonition type="info">
+
+Insights are only available for paid teams.
+
+</Admonition>
+
+![Insights Card](/screenshots/insights.png)
+
+The Health page also surfaces insights about your deployment, with suggestions
+on how to improve performance and reliability.
+
+Each Insight contains a description of the issue, the impact on your deployment
+(via a chart and event log), and a link to learn more about the issue and how to
+resolve it.
+
+Clicking on an Insight will open a breakdown of the issue, including a larger
+chart and a list of events that triggered the Insight.
+
+![Insight Breakdown](/screenshots/insights_breakdown.png)
+
+Available insights include:
+
+- Functions that are
+  [reading too many bytes](/production/state/limits#transactions) in a single
+  transaction.
+- Functions that are
+  [reading too many documents](/production/state/limits#transactions) in a
+  single transaction.
+- Functions that are experiencing [write conflicts](/error#1).
diff --git a/docs/error.mdx b/docs/error.mdx
@@ -5,7 +5,7 @@ This page explains specific errors thrown by Convex.
 See [Error Handling](/docs/functions/error-handling/error-handling.mdx) to learn
 about handling errors in general.
 
-## Optimistic concurrency control (OCC) conflict \{#1}
+## Write conflict: Optimistic concurrency control \{#1}
 
 This system error is thrown when a mutation repeatedly fails due to conflicting
 changes from parallel mutation executions.

diff --git a/docs/production/state/limits.mdx b/docs/production/state/limits.mdx
@@ -65,8 +65,6 @@ Applied per document and to any nested `Object` unless stated otherwise.
 | Function argument size                                                            | 8 MiB                               | 8 MiB                                                     |                                                                                                               |
 | Function return value size                                                        | 8 MiB                               | 8 MiB                                                     |                                                                                                               |
 | HTTP action response size                                                         | 20 MiB                              | 20 MiB                                                    | There is no specific limit on request size                                                                    |
-| Number of documents scanned in a query                                            | 16384                               | 16384                                                     | Documents not returned due to a `filter` count as scanned                                                     |
-| Number of documents written in a mutation                                         | 8192                                | 8192                                                      |
 | Length of a console.log line                                                      | 4 KiB                               | 4 KiB                                                     |                                                                                                               |
 | [Log streaming](/docs/production/integrations/log-streams/log-streams.mdx) limits | 4096 logs, flushed every 10 seconds | 4096 logs, flushed every 10 seconds                       | How many logs can be buffered when streaming                                                                  |
 
@@ -85,10 +83,13 @@ Applied per document and to any nested `Object` unless stated otherwise.
 
 These limits apply to each `query` or `mutation` function.
 
-|              |       |
-| ------------ | ----- |
-| Data read    | 8 MiB |
-| Data written | 8 MiB |
+|                            |        | Notes                                                     |
+| -------------------------- | ------ | --------------------------------------------------------- |
+| Data read                  | 8 MiB  | Data not returned due to a `filter` counts as scanned     |
+| Data written               | 8 MiB  |
+| Documents scanned          | 16,384 | Documents not returned due to a `filter` count as scanned |
+| Documents written          | 8,192  |
+| Function return value size | 8 MiB  |
 
 ## Environment Variables
 

diff --git a/static/screenshots/health_cache_hit_rate.png b/static/screenshots/health_cache_hit_rate.png
diff --git a/static/screenshots/health_failure_rate.png b/static/screenshots/health_failure_rate.png
diff --git a/static/screenshots/health_integrations.png b/static/screenshots/health_integrations.png
diff --git a/static/screenshots/health_last_deployed.png b/static/screenshots/health_last_deployed.png
diff --git a/static/screenshots/insights.png b/static/screenshots/insights.png
diff --git a/static/screenshots/insights_breakdown.png b/static/screenshots/insights_breakdown.png
diff --git a/static/screenshots/scheduler_overdue.png b/static/screenshots/scheduler_overdue.png
diff --git a/static/screenshots/scheduler_status.png b/static/screenshots/scheduler_status.png