sourcekit-lsp/Documentation/Logging.md

Logging

The following is a guide of how to write log messages and which level they should be logged at. There may be reasons to deviate from these guides but they should be a good starting point.

Log Levels

The following log levels should be used by log messages in default. The Explore logging in Swift session from WWDC20 has some explanation of how these levels are persisted by OS log and we follow those guidelines.

Fault

From Explore Logging in Swift: Bug in program

A bug in SourceKit-LSP, sourcekitd or any other project included in the Swift toolchain that should never happen and is not due to malformed user input. The fix for faults should always be in a project controlled by the Swift toolchain (most likely in SourceKit-LSP itself) and we should never close them as a third party to resolve. Think of these as light assertions that don’t crash sourcekit-lsp because it is able to recover in some way.

Examples:

• Some global state invariant is broken like a file to startProgress not being followed by endProgress
• sourcekitd crashes
• Two targets in SwiftPM have the same name

Error

From Explore Logging in Swift: Error seen during execution

An error that is due to user input or eg. stale state of files on disk. It indicates that something is going wrong which might explain unexpected behavior. Errors could be due to malformed user input such as invalid requests from the editor or due to stale state that will eventually converge again.

Examples:

• The client sends an invalid request
• Preparation of a file failed due to a syntax error in the user’s code
• The index contains a reference to a source file but the source fail has been modified since the index was last updated and is thus no longer valid

Log/Notice/Default

logger.default logs at the default aka notice level.

From Explore Logging in Swift: Essential for troubleshooting

Essential state transitions during SourceKit-LSP’s execution that allow use to determine what interactions the user performed. These logs will most likely be included in diagnose bundles from sourcekit-lsp diagnose and should help us solve most problems.

Examples:

• The user sends an LSP request
• Indexing of a file starts or finishes
• New build settings for a file have been computed
• Responses from sourcekitd

Info

From Explore Logging in Swift: Helpful but not essential for troubleshooting (not persisted, logged to memory)

Internal state transitions that are helpful. If eg. a request fails and it’s not immediately obvious at which it failed, these should help us narrow down the code that it failed in. These messages might be missing from the logs generated by sourcekit-lsp diagnose and should not generally be needed to fix issues

Examples:

• Requests sent to sourcekitd or clangd
• Logging the main file for a header file

Debug

From Explore Logging in Swift: Useful only during debugging (only logged during debugging)

Log messages that are useful eg. when debugging a test failure but that is not needed for diagnosing most real-world issues, like detailed information about when a function starts executing to diagnose race conditions.

Examples:

• Tasks start and finish executing in TaskScheduler

Log messages

Log messages should resemble English sentences and start with an uppercase letter. If the log is a single sentence it should not have a period at its end.