LLDB-DAP extension should provide better logging to diagnose issues

[award999]

While trying to diagnose debugging issues experienced by users of the vscode-swift extension, I have been finding it hard to get sufficient information and logging to diagnose issues with the LLDB-DAP extension. I would like to propose the following setup which I have found worked well in other extensions I've worked on:

1. On activate the provided ExtensionContext has a logUri property where VSCode wants the extension to write log files. There is a timestamped folder so you can find logs for older sessions.
2. Have an LLDB-DAP LogOutputChannel where users can view some messaging provided by the extension to possibly diagnose their own problems, and vscode will write to a .log file under logUri.
3. winston is a popular MIT module for handling logging. The great thing about winston is you can add multiple transports. So you have one common logging interface but winston handles the writing to the multiple data sinks.
4. Add a transport the writes to the OutputChannel. By default the OutputChannel transport will have log level info
5. A log file transport will be added to write a log file under the logUri folder, and this log will be at the debug log level. So the log file captures everything to help with diagnosing issues, but the OutputChannel is less verbose, providing the user with info that may help them self-diagnose setup problems.
6. Add a new lldb-dap.verboseLogging lldb-dap.captureSessionLogs boolean settings, that will (1) change the OutputChannel log level from info to debug, and (2) make sure the LLDBDAP_LOG environment variable is set. If the lldb-dap.log-path setting is set by the user then will use this path, otherwise write the session log to logUri/lldb-dap-session-YYYYMMDDHHMMSS.log

[award999]

cc @JDevlieghere

[award999]

I know that is a lengthy proposal, but the change is rather small so I've got a draft PR I coded up quick that I'll put up to help gather feedback

[llvmbot]

@llvm/issue-subscribers-lldb-dap

Author: None (award999)

While trying to diagnose debugging issues experienced by users of the [vscode-swift](https://github.com/swiftlang/vscode-swift) extension, I have been finding it hard to get sufficient information and logging to diagnose issues with the LLDB-DAP extension. I would like to propose the following setup which I have found worked well in other extensions I've worked on:

1. Have an LLDB-DAP OutputChannel where users can view some messaging provided by the extension to possibly diagnose their own problems.
2. On activate the provided ExtensionContext has a logUri property where VSCode wants the extension to write log files. There is a timestamped folder so you can find logs for older sessions.
3. winston is a popular MIT module for handling logging. The great thing about winston is you can add multiple transports. So you have one common logging interface but winston handles the writing to the multiple data sinks.
4. Add a transport the writes to the OutputChannel. By default the OutputChannel transport will have log level info
5. A log file transport will be added to write a log file under the logUri folder, and this log will be at the debug log level. So the log file captures everything to help with diagnosing issues, but the OutputChannel is less verbose, providing the user with info that may help them self-diagnose setup problems.
6. Add a new lldb-dap.verboseLogging boolean settings, that will (1) change the OutputChannel log level from info to debug, and (2) make sure the LLDBDAP_LOG environment variable is set. If the lldb-dap.log-path setting is set by the user then will use this path, otherwise write the session log to logUri/lldb-dap-session-YYYYMMDDHHMMSS.log

[award999]

Also worth noting users of the vscode-swift extension have asked for this verbose debug logging back before the LLDB-DAP extension became a dependency swiftlang/vscode-swift#1104

[JDevlieghere]

Thanks for putting this together Adam!

To summarize: you're proposing to use the existing logging from lldb-dap the binary and plug that into Visual Studio Code's native logging/diagnostics infrastructure. That way, the logs are always captured and available in a standard location, as opposed to today, where we need to ask users to follow bespoke steps to enable logging and reproduce an issue. As an added benefit, if we were to introduce log levels in lldb-dap we could show certain log messages to the users and have others go to this diagnostics log (like the JSON packets).

Did I get that right?

[award999]

Yes I think mostly right but there is a separation of 2 types of log files. For the first type of what I want to call "session logs", I want to use existing logging from the lldb-dap binary that is created when LLDBDAP_LOG environment variable is set, but put them into a common spot.

The second type I'll refer to as the "extension log". This is where Winston comes in. The winston logger will be only for the extension to log information. Some of the information being logged would include the resolved debug configuration before lldb-dap is spawned or the environment passed to the lldb-dap process. So essentially the extension log captures the VSCode extension's logic, before lldb-dap is spawned.

So for the logUri given to the extension by VS Code, this log folder may look something like this:

$ ls <logUri>
    lldb-dap-extension.log
    lldb-dap-session-20250624084800.log
    lldb-dap-session-20250624092452.log

where lldb-dap-extension.log is the extension log created by winston. And then the lldb-dap-session-*.log files are the session logs from the various debug sessions that the user runs.

I am proposing these 2 separate logs, because I think that putting the extension and session log messages in the same log file would be hard to mentally parse through, not to mention there could be interleaving, for example you have one debug session for a client and one for a server running at the same time.

[JDevlieghere]

Got it, thanks for the clarification! I like this proposal as it will help us as developers better diagnose issues. A minor concern could be that this now turns on logging all the time, but the logging in lldb-dap is fairly lightweight so I don't expect that to be a real concern. Empirically, I always have logging enabled and I haven't noticed any overhead.