log2src

Mapping logs to source code to augment debugging, analysis, and understanding.

Log driven debugging

Use logs generated by your application to drive a debugger and step through the source code.

Demo

Click to view a GIF that demonstrates the idea.

Use cases (Aspirational)

The current version is still an early prototype that only works with simple programs, demonstrated in the examples dir of this project. That being said, here are some of the types of use cases that this project hopes to improve over a traditional debugger:

1. Multi-threaded code: A connected debugger can impact the execution of multi-threaded code. Instead of connecting to your application and praying for the correct interleaving, capture the issue in your logs and replay as many times as you like.
2. Client server or machine-to-machine requests: Stepping across multiple processes, perhaps on separate machines, requires orchestrating multiple debuggers and racing against client time outs. Alternatively one could aggregate logs of all machines involved and debug at one's own pace. The client and server logs do not need to be implemented in the same programming language for this kind of functionality.
3. Production issues: Trying to debug on prod is risky and requires access to the infrastructure where the application is running. With log2src, as long as the logs are accessible to you, you can debug the problem offline without impacting production servers.

Features

• Maps log lines back onto the source code to aid debugging by easing cognitive burden.
• Tries to reconstruct a portion of the program state by providing values of expressions & variables.
• Infer the call stack when possible based on an analysis of the source code.
• At the moment a subset of the Java & Rust programming languages are supported, but intending to try and work with most popular languages.
• A VS Code extension using the debug adapter protocol.

Build

You must compile the command line tool using Rust. The log2src command line tool has several options and the API is still quite experimental, so expect changes. See -h for the up to date documentation.

You can also build and run the VS Code extension by building the log2src binary and copying it into editors/code/bin. The easiest way to run the extension at the moment is from VS Code using the standard run configuration.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run Extension",
            "type": "extensionHost",
            "request": "launch",
            "args": [
                "--extensionDevelopmentPath=${workspaceFolder}/editors/code"
            ],
            "outFiles": [
                "${workspaceFolder}/editors/code/out/**/*.js"
            ],
            "preLaunchTask": "${defaultBuildTask}"
        }
    ]
}

When the new window with the extension is loaded, you can load up in text editors the source code that you'd like to debug, as well as a log file generated from the source. See the demo above for an example.

You can run the log2src debugger using this example configuration that shows how to "debug" the basic.rs example. Note that the log location was stored on disk at /tmp/basic.log.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "log2src",
            "request": "launch",
            "name": "Launch: log2src: stack",
            "source": "${workspaceFolder}/examples/basic.rs",
            "log": "/tmp/basic.log"
        }
    ]
}

In order to package the VS Code extension, run

$ pnpm vsce package --no-dependencies

The vsix package can be installed within the VS Code extensions.

Contributing

This is mostly a hobby project worked on during nights and weekends, so to minimize project management I'm not looking for pull requests at the moment. Feel free to file an issue to discuss bugs, ideas, or other interest in the project.