ruff server: Tracing system now respects log level and trace level, with options to log to a file

[snowsignal]

Summary

Fixes #10968.
Fixes #11545.

The server's tracing system has been rewritten from the ground up. The server now has trace level and log level settings which restrict the tracing events and spans that get logged.

• A logLevel setting has been added, which lets a user set the log level. By default, it is set to "info".
• A logFile setting has also been added, which lets the user supply an optional file to send tracing output (it does not have to exist as a file yet). By default, if this is unset, tracing output will be sent to stderr.
• A $/setTrace handler has also been added, and we also set the trace level from the initialization options. For editors without direct support for tracing, the environment variable RUFF_TRACE can override the trace level.
• Small changes have been made to how we display tracing output. We no longer use tracing-tree, and instead use tracing_subscriber::fmt::Layer to format output. Thread names are now included in traces, and I've made some adjustment to thread worker names to be more useful.

Test Plan

In VS Code, with ruff.trace.server set to its default value, no logs from Ruff should appear.

After changing ruff.trace.server to either messages or verbose, you should see log messages at info level or higher appear in Ruff's output:

In Helix, by default, no logs from Ruff should appear.

To set the trace level in Helix, you'll need to modify your language configuration as follows:

[language-server.ruff]
command = "/Users/jane/astral/ruff/target/debug/ruff"
args = ["server", "--preview"]
environment = { "RUFF_TRACE" = "messages" }

After doing this, logs of info level or higher should be visible in Helix:

You can use :log-open to quickly open the Helix log file.

In Neovim, by default, no logs from Ruff should appear.

To set the trace level in Neovim, you'll need to modify your configuration as follows:

require('lspconfig').ruff.setup {
  cmd = {"/path/to/debug/executable", "server", "--preview"},
  cmd_env = { RUFF_TRACE = "messages" }
}

You should see logs appear in :LspLog that look like the following:

You can adjust logLevel and logFile in settings:

require('lspconfig').ruff.setup {
  cmd = {"/path/to/debug/executable", "server", "--preview"},
  cmd_env = { RUFF_TRACE = "messages" },
  settings = {
    logLevel = "debug",
    logFile = "your/log/file/path/log.txt"
  }
}

The logLevel and logFile can also be set in Helix like so:

[language-server.ruff.config.settings]
logLevel = "debug"
logFile = "your/log/file/path/log.txt"

Even if this log file does not exist, it should now be created and written to after running the server:

[github-actions]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

✅ ecosystem check detected no format changes.

[MichaReiser]

Looks good. I think we should address the TODO before merging this and extend the test plan with a case that shows that changing the verbosity in the extension settings changes the output.

[codspeed-hq]

CodSpeed Performance Report

Merging #11747 will improve performances by 13.17%

_{Comparing jane/server/logging-v2 (f5d35dd) with main (521a358)}

Summary

⚡ 1 improvements
✅ 29 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	jane/server/logging-v2	Change
⚡	linter/all-with-preview-rules[numpy/globals.py]	917.3 µs	810.5 µs	+13.17%

[MichaReiser]

The code changes look good to me. I left a few questions and are waiting for a test plan that shows a few traces.

I think some documentation on how the tracing setup would be helpful, especially because it now supports environment variables, tracing level, logLevel, log file etc.

[MichaReiser]

This looks good to me. Happy to approve tomorrow morning when the Test plan's filled out. Thanks for doing another iteration on this!

[MichaReiser]

Nice! Thank's for taking the time to iterate on the design

[dhruvmanila]

This isn't blocking the PR but can you provide similar examples for Neovim. I'm able to set the RUFF_TRACE environment variable via the cmd_env key but not able to figure out where the logLevel / logFile should go and how should they affect the messages displayed.

[snowsignal]

@dhruvmanila I've updated the PR description with a Neovim testing guide 😄