coder · stirby · Nov 1, 2024 · Oct 31, 2024 · Oct 31, 2024 · Oct 31, 2024
diff --git 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.
+
+![Workspace build timings UI](../../images/admin/templates/troubleshooting/workspace-build-timings-ui.png)
diff --git a/docs/images/admin/templates/troubleshooting/workspace-build-timings-ui.png b/docs/images/admin/templates/troubleshooting/workspace-build-timings-ui.png
diff --git 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.
+
+![Workspace build timings UI](../images/admin/templates/troubleshooting/workspace-build-timings-ui.png)
+
 ### Next steps
 
 - [Connecting to your workspace](./index.md)