Adds DevTools docs (#16264)

* DevTools docs up

* Apply suggestions from code review

Fixes typos

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

* Code block tweaks

* Proofreading tweaks

* Adding links from limits page

* Wording changes

* fixing missed rebase

* Slight cleanup

---------

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
Co-authored-by: kodster28 <[email protected]>

Author: 3 people

public/_redirects

@@ -1234,6 +1234,7 @@
 /workers/about/routes/ /workers/configuration/routing/routes/ 301
 /workers/platform/routes/ /workers/configuration/routing/ 301
 /workers/about/tips/debugging/ /workers/observability/ 301
+/workers/testing/debugging-tools/ /workers/observability/dev-tools/ 301
 /workers/about/tips/signing-requests/ /workers/examples/signing-requests/ 301
 /workers/about/using-cache/ /workers/reference/how-the-cache-works/ 301
 /workers/learning/how-the-cache-works/ /workers/reference/how-the-cache-works/ 301

src/assets/images/workers/observability/heavy.png

@@ -1,21 +1,12 @@
 ---
-title: Debugging tools
 pcx_content_type: concept
+title: Breakpoints
+description: Debug your local and deployed Workers using breakpoints.
 sidebar:
   order: 4
 head: []
-description: Debug your local and deployed Workers using a variety of tools.
-
 ---
 
-Being able to assess how your Workers are functioning at various points in the development cycle is vital to identifying the root causes of bugs or issues.
-
-Cloudflare provides a variety of tools to help you debug your Workers.
-
-## Chrome DevTools
-
-Wrangler supports using [Chrome DevTools](https://developer.chrome.com/docs/devtools/) to view logs/sources, set breakpoints, and profile CPU/memory usage. To open a DevTools session connected to your Worker from any Chromium-based browser, run [`wrangler dev`](/workers/wrangler/commands/#dev) and press the <kbd>d</kbd> key in your terminal.
-
 ## Debug via breakpoints
 
 As of Wrangler 3.9.0, you can debug via breakpoints in your Worker. Breakpoints provide the ability to review what is happening at a given point in the execution of your Worker. Breakpoint functionality exists in both DevTools and VS Code.
@@ -32,17 +23,17 @@ To setup VS Code for breakpoint debugging in your Worker project:
 ```json
 {
   "configurations": [
-      {
-          "name": "Wrangler",
-          "type": "node",
-          "request": "attach",
-          "port": 9229,
-          "cwd": "/",
-          "resolveSourceMapLocations": null,
-          "attachExistingChildren": false,
-          "autoAttachChildProcesses": false,
-          "sourceMaps": true // works with or without this line
-      }
+    {
+      "name": "Wrangler",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "cwd": "/",
+      "resolveSourceMapLocations": null,
+      "attachExistingChildren": false,
+      "autoAttachChildProcesses": false,
+      "sourceMaps": true // works with or without this line
+    }
   ]
 }
 ```
@@ -57,20 +48,16 @@ To setup VS Code for breakpoint debugging in your Worker project:
 
 :::caution
 
-
 Breakpoint debugging in `wrangler dev` using `--remote` could extend Worker CPU time and incur additional costs since you are testing against actual resources that count against usage limits. It is recommended to use `wrangler dev` without the `--remote` option. This ensures you are developing locally.
 
-
 :::
 
 :::note
 
-
 The `.vscode/launch.json` file only applies to a single workspace. If you prefer, you can add the above launch configuration to your User Settings (per the [official VS Code documentation](https://code.visualstudio.com/docs/editor/debugging#_global-launch-configuration)) to have it available for all your workspaces.
 
-
 :::
 
 ## Related resources
 
-* [Local Development](/workers/testing/local-development/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop.
+- [Local Development](/workers/testing/local-development/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop.

src/assets/images/workers/observability/memory-stats.png

@@ -0,0 +1,91 @@
+---
+pcx_content_type: concept
+title: Profiling CPU usage
+weight: 4
+description: Learn how to profile CPU usage and ensure CPU-time per request stays under Workers limits
+---
+
+If a Worker spends too much time performing CPU-intensive tasks, responses may be slow or the Worker might
+fail to startup due to [time limits](/workers/platform/limits/#worker-startup-time).
+
+Profiling in DevTools can help you identify and fix code that uses too much CPU.
+
+Measuring execution time of specific functions in production can be difficult because Workers
+[only increment timers on I/O](/workers/reference/security-model/#step-1-disallow-timers-and-multi-threading)
+for security purposes. However, measuring CPU execution times is possible in local development with DevTools.
+
+## Taking a profile
+
+To generate a CPU profile:
+
+- Run `wrangler dev` to start your Worker
+- Hit <kbd>d</kbd> from your terminal to open DevTools
+- Click on the "Profiler" tab
+- Click `Start` to begin recording CPU usage
+- Send requests to your Worker from a new tab
+- Click `Stop`
+
+You now have a CPU profile.
+
+## An Example Profile
+
+Let's look at an example to learn how to read a CPU profile. Imagine you have the following Worker:
+
+```js title="index.js"
+const addNumbers = (body) => {
+	for (let i = 0; i < 5000; ++i) {
+		body = body + " " + i;
+	}
+	return body;
+};
+
+const moreAddition = (body) => {
+	for (let i = 5001; i < 15000; ++i) {
+		body = body + " " + i;
+	}
+	return body;
+};
+
+export default {
+	async fetch(request, env, ctx) {
+		let body = "Hello Profiler! - ";
+		body = addNumbers(body);
+		body = moreAddition(body);
+		return new Response(body);
+	},
+};
+```
+
+You want to find which part of the code causes slow response times. How do you use DevTool profiling to identify the
+CPU-heavy code and fix the issue?
+
+First, as mentioned above, you open DevTools by hitting <kbd>d</kbd> after running `wrangler dev`. Then, you
+navigate to the "Profiler" tab and take a profile by pressing `Start` and sending a request.
+
+![CPU Profile](~/assets/images/workers/observability/profile.png)
+
+The top chart in this image shows a timeline of the profile, and you can use it to zoom in on a specific request.
+
+The chart below shows the CPU time used for operations run during the request. In this screenshot, you can see
+"fetch" time at the top and the subscomponents of fetch beneath, including the two functions `addNumbers` and
+`moreAdditions`. By hovering over each box, you get more information, and by clicking the box, you navigate
+to the function's source code.
+
+Using this graph, you can answer the question of "what is taking CPU time?". The `addNumbers` function has
+a very small box, representing 0.3ms of CPU time. The `moreAdditions` box is larger, representing 2.2ms of CPU time.
+
+Therefore, if you want to make response times faster, you need to optimize `moreAdditions`.
+
+You can also change the visualization from ‘Chart’ to ‘Heavy (Bottom Up)’ for an alternative view.
+
+![CPU Profile](~/assets/images/workers/observability/heavy.png)
+
+This shows the relative times allocated to each function. At the top of the list, `moreAdditions` is clearly the
+slowest portion of your Worker. You can see that garbage collection also represents a large percentage of time, so
+memory optimization could be useful.
+
+## Additional Resources
+
+To learn more about how to use the CPU profiler, see [Google's documentation on Profiling the CPU in DevTools](https://developer.chrome.com/docs/devtools/performance/nodejs#profile).
+
+To learn how to use DevTools to gain insight into memory, see the [Memory Usage Documentation](/workers/observability/dev-tools/memory-usage/).

src/assets/images/workers/observability/memory-summary.png

@@ -0,0 +1,34 @@
+---
+title: DevTools
+weight: 1
+pcx_content_type: concept
+meta:
+  description: Overview of interactive DevTools used to debug a variety of situations
+---
+
+## Using DevTools
+
+When running your Worker locally using `wrangler dev`, you automatically have access to [Cloudflare's implementation](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler-devtools?cf_target_id=115890352C73E75FD7D837D0B8720E96) of [Chrome's DevTools](https://developer.chrome.com/docs/devtools/overview).
+DevTools help you debug and optimize your Workers.
+
+:::note
+You may have experience using Chrome's DevTools for frontend development. Notably, Worker DevTools are used for backend code and _not_ client-side JavaScript.
+:::
+
+## Opening DevTools
+
+To get started, run your Worker in development mode with `wrangler dev`, then open the DevTools in the browser by hitting <kbd>d</kbd> from your terminal. Now when you access this worker locally, it can be debugged and profiled with this DevTools instance.
+
+Alternatively, both the [Cloudflare Dashboard](https://dash.cloudflare.com/) and the [Worker's Playground](https://workers.cloudflare.com/playground) include DevTools in their UI.
+
+## DevTool use cases
+
+DevTools can be used in a variety of situations. For more information, see the documentation:
+
+- [Debugging code via breakpoints and logging](/workers/observability/dev-tools/breakpoints/)
+- [Profiling CPU usage](/workers/observability/dev-tools/cpu-usage/)
+- [Addressing out of memory (OOM) errors](/workers/observability/dev-tools/memory-usage/)
+
+## Related resources
+
+- [Local development](/workers/testing/local-development/) - Develop your Workers and connected resources locally via Wrangler and workerd, for a fast, accurate feedback loop.

src/assets/images/workers/observability/profile.png

@@ -0,0 +1,82 @@
+---
+title: Profiling Memory
+weight: 4
+pcx_content_type: concept
+meta:
+  description: Learn how to profile Memory usage to avoid out-of-memory errors and optimize your Worker
+---
+
+Understanding Worker memory usage can help you optimize performance, avoid Out of Memory (OOM) errors
+when hitting [Worker memory limits](/workers/platform/limits/#memory), and fix memory leaks.
+
+You can profile memory usage with snapshots in DevTools. Memory snapshots let you view a summary of
+memory usage, see how much memory is allocated to different data types, and get details on specific
+objects in memory.
+
+## Taking a snapshot
+
+To generate a memory snapshot:
+
+- Run `wrangler dev` to start your Worker
+- Hit <kbd>d</kbd> from your terminal to open DevTools
+- Click on the "Memory" tab
+- Send requests to your Worker to start allocating memory
+  - Optionally include a debugger to make sure you can pause execution at the proper time
+- Click `Take snapshot`
+
+You can now inspect Worker memory.
+
+## An Example Snapshot
+
+Let's look at an example to learn how to read a memory snapshot. Imagine you have the following Worker:
+
+```js title="index.js"
+let responseText = "Hello world!";
+
+export default {
+	async fetch(request, env, ctx) {
+		let now = new Date().toISOString();
+		responseText = responseText + ` (Requested at: ${now})`;
+		return new Response(responseText.slice(0, 53));
+	},
+};
+```
+
+While this code worked well initially, over time you notice slower responses and
+Out of Memory errors. Using DevTools, you can find out if this is a memory leak.
+
+First, as mentioned above, you open DevTools by hitting <kbd>d</kbd> after running `wrangler dev`.
+Then, you navigate to the "Memory" tab.
+
+Next, generate a large volume of traffic to the Worker by sending requests. You can do this with `curl` or by
+repeatedly reloading the browser. Note that other Workers may require more specific requests to reproduce
+a memory leak.
+
+Then, click the "Take Snapshot" button and view the results.
+
+First, navigate to "Statistics" in the dropdown to get a general sense of what takes up memory.
+
+![Memory Statistics](~/assets/images/workers/observability/memory-stats.png)
+
+Looking at these statistics, you can see that a lot of memory is dedicated to strings at 67 kB. This is
+likely the source of the memory leak. If you make more requests and take another snapshot, you would see
+this number grow.
+
+![Memory Summary](~/assets/images/workers/observability/memory-summary.png)
+
+The memory summary lists data types by the amount of memory they take up. When you click into "(string)", you can see
+a string that is far larger than the rest. The text shows that you are appending "Requested at" and a date repeatedly,
+inadvertently overwriting the global variable with an increasingly large string:
+
+```js
+responseText = responseText + ` (Requested at: ${now})`;
+```
+
+Using Memory Snapshotting in DevTools, you've identified the object and line of code causing the memory leak.
+You can now fix it with a small code change.
+
+## Additional Resources
+
+To learn more about how to use Memory Snapshotting, see [Google's documentation on Memory Heap Snapshots](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots).
+
+To learn how to use DevTools to gain insight into CPU usage, see the [CPU Profiling Documentation](/workers/observability/dev-tools/cpu-usage/).

src/content/docs/workers/testing/debugging-tools.mdx renamed to src/content/docs/workers/observability/dev-tools/breakpoints.mdx

@@ -76,7 +76,9 @@ Cloudflare updates the Workers runtime a few times per week. When this happens,
 
 CPU time is the amount of time the CPU actually spends doing work, during a given request. Most Workers requests consume less than a millisecond of CPU time. It is rare to find normally operating Workers that exceed the CPU time limit.
 
-<Render file="isolate-cpu-flexibility" /> <br />
+<Render file="isolate-cpu-flexibility" />
+
+Using DevTools locally can help identify CPU intensive portions of your code. See the [CPU profiling with DevTools documentation](/workers/observability/dev-tools/cpu-usage/) to learn more.
 
 You can also set a custom limit on the amount of CPU time that can be used during each invocation of your Worker. To do so, navigate to the Workers section in the Cloudflare dashboard. Select the specific Worker you wish to modify, then click on the "Settings" tab where you can adjust the CPU time limit.
 
@@ -156,6 +158,8 @@ If a Worker processes a request that pushes the Worker over the 128 MB limit, th
 
 Use the [TransformStream API](/workers/runtime-apis/streams/transformstream/) to stream responses if you are concerned about memory usage. This avoids loading an entire response into memory.
 
+Using DevTools locally can help identify memory leaks in your code. See the [memory profiling with DevTools documentation](/workers/observability/dev-tools/memory-usage/) to learn more.
+
 ---
 
 ## Subrequests
@@ -264,6 +268,10 @@ A Worker must be able to be parsed and execute its global scope (top-level code
 
 You can measure your Worker's startup time by deploying it to Cloudflare using [Wrangler](/workers/wrangler/). When you run `npx wrangler@latest deploy` or `npx wrangler@latest versions upload --experimental-versions`, Wrangler will output the startup time of your Worker in the command-line output, using the `startup_time_ms` field in the [Workers Script API](/api/operations/worker-script-upload-worker-module) or [Workers Versions API](/api/operations/worker-versions-upload-version#request-body).
 
+If you are having trouble staying under this limit, consider [profiling using DevTools](/workers/observability/dev-tools/) locally to learn how to optimize your code.
+
+<Render file="limits_increase" />
+
 ---
 
 ## Number of Workers