diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md
index 7c61dfaa8be65..e08a422938e2f 100644
--- a/docs/admin/templates/troubleshooting.md
+++ b/docs/admin/templates/troubleshooting.md
@@ -154,3 +154,17 @@ the top of the script to exit on error.
> **Note:** If you aren't seeing any logs, check that the `dir` directive points
> to a valid directory in the file system.
+
+## Slow workspace startup times
+
+If your workspaces are taking longer to start than expected, or longer than
+desired, you can diagnose which steps have the highest impact in the workspace
+build timings UI (available in v2.17 and beyond). Admins can can
+programmatically pull startup times for individual workspace builds using our
+[build timings API endpoint](../../reference/api/builds.md#get-workspace-build-timings-by-id).
+
+See our
+[guide on optimizing workspace build times](../../tutorials/best-practices/speed-up-templates.md)
+to optimize your templates based on this data.
+
+
diff --git a/docs/images/admin/templates/troubleshooting/workspace-build-timings-ui.png b/docs/images/admin/templates/troubleshooting/workspace-build-timings-ui.png
new file mode 100644
index 0000000000000..137752ec1aa62
Binary files /dev/null and b/docs/images/admin/templates/troubleshooting/workspace-build-timings-ui.png differ
diff --git a/docs/user-guides/workspace-lifecycle.md b/docs/user-guides/workspace-lifecycle.md
index 12c2b021112dc..56d0c0b5ba7fd 100644
--- a/docs/user-guides/workspace-lifecycle.md
+++ b/docs/user-guides/workspace-lifecycle.md
@@ -109,6 +109,19 @@ your template's Terraform file and the target resources on your infrastructure.
Unhealthy workspaces are usually caused by a misconfiguration in the agent or
workspace startup scripts.
+## Workspace build times
+
+After a successful build, you can see a timing breakdown of the workspace
+startup process from the dashboard (starting in v2.17). We capture and display
+both time taken to provision the workspace's compute and agent startup steps.
+These include any
+[`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script)s
+such as [dotfiles](./workspace-dotfiles.md) or
+[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
+startups.
+
+
+
### Next steps
- [Connecting to your workspace](./index.md)
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy