1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
|
# 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](https://developer.apple.com/wwdc20/10168?time=604) 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.
|
