Add instructions on how to see redacted logs and debug

Author: rockbruno

CONTRIBUTING.md

@@ -9,3 +9,7 @@ If you're using Xcode, you can develop for `sourcekit-bazel-bsp` by directly ope
 ## VSCode / Cursor
 
 Download and install [the official Swift extension for Cursor / VSCode.](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode) After this, the IDE should properly recognize sourcekit-bazel-bsp as a SwiftPM project and automatically generate the relevant build/debug actions. After building, you can test your custom binary by changing the path to sourcekit-bazel-bsp in your test project's BSP json file as described in the [Initial Setup](https://github.com/spotify/sourcekit-bazel-bsp?tab=readme-ov-file#initial-setup-instructions) instructions.
+
+## Debugging and Troubleshooting
+
+Instructions on how to debug sourcekit-bazel-bsp and enable extended logging are currently available at the main README.

Enable Extended Logging.mobileconfig

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PayloadContent</key>
+	<array>
+		<dict>
+			<key>PayloadDisplayName</key>
+			<string>Enable Extended Logging</string>
+			<key>PayloadEnabled</key>
+			<true/>
+			<key>PayloadIdentifier</key>
+			<string>com.apple.system.logging.A8602F50-0DC2-43C5-8BBE-173B14BB0B5F</string>
+			<key>PayloadType</key>
+			<string>com.apple.system.logging</string>
+			<key>PayloadUUID</key>
+			<string>A8602F50-0DC2-43C5-8BBE-173B14BB0B5F</string>
+			<key>PayloadVersion</key>
+			<integer>1</integer>
+			<key>Subsystems</key>
+			<dict>
+				<key>com.spotify.sourcekit-bazel-bsp</key>
+				<dict>
+					<key>DEFAULT-OPTIONS</key>
+					<dict>
+						<key>Enable-Private-Data</key>
+						<true/>
+					</dict>
+				</dict>
+			</dict>
+		</dict>
+	</array>
+	<key>PayloadDescription</key>
+	<string>Enables extended logging for sourcekit-bazel-bsp, exposing potentially sensitive information.</string>
+	<key>PayloadDisplayName</key>
+	<string>Extended sourcekit-bazel-bsp Logging</string>
+	<key>PayloadIdentifier</key>
+	<string>com.spotify.sourcekit-bazel-bsp.enable-extended-logging</string>
+	<key>PayloadRemovalDisallowed</key>
+	<false/>
+	<key>PayloadScope</key>
+	<string>System</string>
+	<key>PayloadType</key>
+	<string>Configuration</string>
+	<key>PayloadUUID</key>
+	<string>98EC5C60-67D6-4F3F-9EB7-50293291D03F</string>
+	<key>PayloadVersion</key>
+	<integer>1</integer>
+</dict>
+</plist>

Example/.vscode/tasks.json

@@ -5,7 +5,10 @@
       "label": "Build HelloWorld",
       "type": "shell",
       "command": "bazelisk",
-      "args": ["build", "//HelloWorld"],
+      "args": [
+        "build",
+        "//HelloWorld"
+      ],
       "group": {
         "kind": "build",
         "isDefault": true
@@ -19,7 +22,10 @@
       "label": "Test HelloWorldTests",
       "type": "shell",
       "command": "bazelisk",
-      "args": ["test", "//HelloWorld:HelloWorldTests"],
+      "args": [
+        "test",
+        "//HelloWorld:HelloWorldTests"
+      ],
       "group": {
         "kind": "test",
         "isDefault": true
@@ -63,9 +69,9 @@
       }
     },
     {
-      "label": "Stream SourceKit Logs",
+      "label": "Stream SourceKitBazelBSP Logs",
       "type": "shell",
-      "command": "log stream --process sourcekit-bazel-bsp --info",
+      "command": "log stream --process sourcekit-bazel-bsp --debug",
       "problemMatcher": [],
       "isBackground": false,
       "presentation": {
@@ -74,4 +80,4 @@
       }
     }
   ]
-}
+}

Example/README.md

@@ -28,4 +28,4 @@ See the main README for a description of what is and isn't supported at the mome
 
 ## Troubleshooting
 
-If something weird (or nothing) happens, check the `SourceKit-LSP: Indexing` logs for details of what may have happened. If you don't see that option at all, first run `Cmd+S`  on a Swift file to see if that does the trick, and if it's still not there, you can instead log sourcekit-bazel-bsp by running `log stream --process sourcekit-bazel-bsp --info` on a terminal session. If you see no logs there when interacting with the IDE, that means one or more of the above steps were not followed correctly (most likely the build step).
+If something weird (or nothing) happens, check the `SourceKit-LSP: Indexing` logs for details of what may have happened. If you don't see that option at all, first run `Cmd+S` on a Swift file to see if that does the trick, and if it's still not there, try logging sourcekit-bazel-bsp directly by following the troubleshooting instructions in the main README.

README.md

@@ -40,8 +40,24 @@
 
 After following these steps, the `SourceKit Language Server` output tab (_Cmd+Shift+U_) should show up when opening Swift or Obj-C files, and indexing-related actions will start popping up at the bottom of the IDE after a while alongside a new `SourceKit-LSP: Indexing` output tab when working with those files.
 
-If you experience any trouble trying to get it to work, check out the [Example/ folder](./Example) for a test project with a pre-configured Bazel and `.bsp` setup. The example project also contains instructions on how to debug sourcekit-bazel-bsp that can help you find and fix the problem.
+If you experience any trouble trying to get it to work, check out the [Example/ folder](./Example) for a test project with a pre-configured Bazel and `.bsp` setup. The _Troubleshooting_ section below also contains instructions on how to debug sourcekit-bazel-bsp.
 
 ### Other IDEs
 
 The setup instructions depend on how the IDE integrates with LSPs. You should then search for instructions on how to install sourcekit-lsp on your IDE of choice and enable background indexing. After that, follow the `.bsp/` related steps from the above instructions. Keep in mind that this since project is developed specifically with Cursor / VSCode in mind, we cannot say how well sourcekit-bazel-bsp would work with other IDEs.
+
+## Troubleshooting
+
+### Seeing sourcekit-bazel-bsp's logs
+
+sourcekit-bazel-bsp uses Apple's OSLog infrastructure under the hood. To see the tool's logs, run `log stream --process sourcekit-bazel-bsp --debug` on a terminal session.
+
+By default, most logs will be redacted for privacy reasons, but you may want to see them for debug and development reasons. To enable extended logging and expose those logs, install the configuration profile at https://github.com/swiftlang/sourcekit-lsp/blob/main/Documentation/Enable%20Extended%20Logging.mobileconfig [as described here](https://support.apple.com/guide/mac-help/configuration-profiles-standardize-settings-mh35561/mac#mchlp41bd550) You will then able to see the redacted logs.
+
+If you wish for the logs to become redacted again, you can remove the configuration profile [as described here.](https://support.apple.com/guide/mac-help/configuration-profiles-standardize-settings-mh35561/mac#mchlpa04df41.)
+
+### Debugging
+
+Since sourcekit-bazel-bsp is initialized from within sourcekit-lsp, debugging it requires you to start a lldb session in advance. You can do it with the following command: `lldb --attach-name sourcekit-bazel-bsp --wait-for`
+
+Once the lldb session is initialized, triggering the initialization of the Swift extension on your IDE of choice (e.g. opening a Swift file in VSCode) should eventually cause lldb to start a debugging session.

Sources/SourceKitBazelBSP/SharedUtils/Logger.swift

@@ -20,7 +20,7 @@
 import Foundation
 import OSLog
 
-/// Simple helper to create loggers under the `sourcekit-bazel-bsp` subsystem.
+/// Simple helper to create loggers under the `com.spotify.sourcekit-bazel-bsp` subsystem.
 package func makeFileLevelBSPLogger(withCategory category: String = #fileID) -> Logger {
-    Logger(subsystem: "sourcekit-bazel-bsp", category: category)
+    Logger(subsystem: "com.spotify.sourcekit-bazel-bsp", category: category)
 }