Add a Debugging User Guide

[joeduffy]

We have a work item to make debugging easier with Pulumi. It has a fair number of upvotes and we see folks asking about this quite often. The thing is, even today, without any new work, this is possible in all languages as far as I know. If you read through the comments in that thread, there are various ways to get this working (e.g., in Node.js, Python, .NET, and Go).

It's not as pretty as we'd like, but debugging seldom is, and a simple Debugging User Guide that documents the known approaches would be relatively low cost and very valuable. Furthermore, I suspect the eventual work item to add a CLI flag will need to basically add built-in support to the various languages to hook the debugger in much the same way these approaches do, so having that documented in one place will presumably help when it comes to implementing the new CLI flag.

[aureq]

Instructions for Python and VSCode

1. Install debugpy as part of your environment.
2. In your VSCode project add a new launch configuration and select Python and then Remote Attach. Keep the default (localhost and 5678)
3. Add the code below to your code

import debugpy
debugpy.listen(("localhost", 5678))
max_wait_s = 30
while max_wait_s >= 0:
    if debugpy.is_client_connected():
        break

    time.sleep(1)
    max_wait_s -= 1

To start debugging, simply run pulumi up or pulumi preview from the command line and after a few seconds, hit F5 in VSCode. VSCode should pause the execution at the first encountered breakpoint.

If no debugger is attached after 30 seconds, execution will continue.

[lukehoban]

This was done in https://github.com/pulumi/docs/pull/12308.

Then we also shipped great new debugging support in the Pulumi CLI and a new Pulumi VS Code extension, and the docs were updated to use those in https://github.com/pulumi/docs/pull/12840.

🎉