mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-10-01 01:36:09 -04:00
devdocs: documentation of logging conventions (#899)
Signed-off-by: Daniel Weiße <dw@edgeless.systems>
This commit is contained in:
parent
cf91e1513f
commit
41fca129f6
@ -55,6 +55,61 @@ golangci-lint run ./...
|
||||
|
||||
It is also recommended to use golangci-lint (and [gofumpt](https://github.com/mvdan/gofumpt) as formatter) in your IDE, by adding the recommended VS Code Settings or by [configuring it yourself](https://golangci-lint.run/usage/integrations/#editor-integration)
|
||||
|
||||
## Logging
|
||||
|
||||
We use a [custom subset](/internal/logger/) of [zap](https://pkg.go.dev/go.uber.org/zap) to provide logging for Constellation's services and components.
|
||||
Usage instructions can be found in the package documentation.
|
||||
|
||||
Certain components may further specify a subset of the logger for their use. For example, the CLI has a debug-only logger, restricting the use of the logger to only `Debugf()`.
|
||||
|
||||
Further we try to adhere to the following guidelines:
|
||||
|
||||
* Do not log potentially sensitive information, e.g. variables that contain keys, secrets or otherwise protected information.
|
||||
|
||||
* Start log messages in uppercase and end without a punctuation mark. Exclamation, question marks, or ellipsis may be used where appropriate.
|
||||
|
||||
Example:
|
||||
|
||||
```Go
|
||||
log.Infof("This is a log message")
|
||||
log.Infof("Waiting to do something...")
|
||||
log.Error("A critical error occurred!")
|
||||
```
|
||||
|
||||
* Use the `With()` method to add structured context to your log messages. The context tags should be easily searchable to allow for easy log filtering. Try to keep consistent tag naming!
|
||||
|
||||
Example:
|
||||
|
||||
```Go
|
||||
log.With(zap.Error(someError), zap.String("ip", "192.0.2.1")).Errorf("Connecting to IP failed")
|
||||
```
|
||||
|
||||
* Log messages may use format strings to produce human readable messages. However, the information should also be present as structured context fields if it might be valuable for debugging purposes.
|
||||
|
||||
Example:
|
||||
|
||||
```Go
|
||||
log.Infof("Starting server on %s:%s", addr, port)
|
||||
```
|
||||
|
||||
* Usage of the `Fatalf()` method should be constrained to the main package of an application only!
|
||||
|
||||
* Use log levels to configure how detailed the logs of you application should be.
|
||||
|
||||
* `Debugf()` for log low level and detailed information. This may include variable dumps, but should not disclose sensitive information, e.g. keys or secret tokens.
|
||||
* `Infof()` for general information.
|
||||
* `Warnf()` for information that may indicate unwanted behavior, but is not an application error. Commonly used by retry loops.
|
||||
* `Errorf()` to log information about any errors that occurred.
|
||||
* `Fatalf()` to log information about any errors that occurred and then exit the program. Should only be used in the main package of an application.
|
||||
|
||||
* Loggers passed to subpackages of an application may use the `Named()` method for better understanding of where a message originated.
|
||||
|
||||
Example:
|
||||
|
||||
```Go
|
||||
grpcServer, err := server.New(log.Named("server"))
|
||||
```
|
||||
|
||||
## Nested Go modules
|
||||
|
||||
As this project contains nested Go modules, we use a Go work file to ease integration with IDEs. You can find an introduction in the [Go workspace tutorial](https://go.dev/doc/tutorial/workspaces).
|
||||
|
Loading…
Reference in New Issue
Block a user