github/prysm
1
1
Fork 0
mirror of https://github.com/OffchainLabs/prysm.git synced 2026-01-09 15:37:56 -05:00
Code Issues Packages Projects Releases Wiki Activity

v2

Browse Source
This commit is contained in:
Bastin
2025-11-26 13:00:09 +01:00
parent 13ea9033b8
commit 00da23ba97
1 changed files with 44 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
runtime/logging/logging.md
View File

@@ -1,58 +1,79 @@
## Advanced Log Control in Prysm
> [!WARNING]
> This is a work in progress. The design is not finalized, nor the implementation is complete.
> This warning will be removed when the design and implementation are finalized.
### Goals
The goal of this work is to give more control over the logging system to the user. Right now the user can only control the global verbose level of the logs, which has some limitations. Mainly, the user does not have control over:
The goal of this work is to give more control over the logging system to the user. Right now the user can only control
the global verbose level of the logs, which has some limitations. Mainly, the user does not have control over:
1. Which packages are logging to the terminal. (Per-Package Visibility)
2. What is the verbosity level for each package. (Per-Package Verbosity)
We try to tackle these limitations, by providing a simple, optional mechanism to the user.
### Per-Package Visibility
We will offer two new config flags:
1. `--log-include-only <comma separated list of package names>`: by providing this flag, the logs will only consist of the packages that the user has mentioned. All other logs will be ignored.
2. `--log-exclude <comma separated list of package names>`: by providing this flag, the logs will consist of all logs, except the logs from packages mentioned by the user.
1. `--log-only <comma separated path of packages>`: by providing this flag, the logs will only consist of
the packages that the user has mentioned. All other logs will be ignored.
2. `--log-exclude <comma separated list of package paths>`: by providing this flag, the logs will consist of all enabled
logs, except the logs from packages mentioned by the user.
These flags follow the inheritance model, meaning that if a package is included/excluded, all its sub-packages are also
included/excluded. Here is an example:
`--log-only beacon-chain/db,beacon-chain/p2p --log-exclude beacon-chain/db/kv,beacon-chain/p2p/peers`
In case of conflicting rules (same package mentioned in both flags), the `--log-only` flag takes precedence.
These flags are mutually exclusive.
These flags have nothing to do with verbosity.
### Per-Package Verbosity
We currently have a flag `--verbosity <trace|debug|info|warn|error>` which sets the default verbosity for all logs.
We will introduce a new config flag `--log-vmodule value` which overrides the default verbosity for the packages mentioned here.
We will introduce a new config flag `--log-vmodule value` which overrides the default verbosity for the packages
mentioned here.
An example of the flag use:
`--log-vmodule beacon-chain/db/kv=5,beacon-chain/p2p=4`
`--log-vmodule beacon-chain/db/kv=trace,beacon-chain/p2p=debug`
Any package not mentioned will take the verbosity of the provided `--verbosity` flag, or if not provided, the default `info` value.
Any package not mentioned will take the verbosity of the provided `--verbosity` flag, or if not provided, the default
`info` value.
This flag has nothing to do with visibility.
### Prerequisite
We need to define a `doc.go` file for every package that we care about<sup>1</sup>.
The file should include a declaration of the `log` variable with a field `package` set to
We need to define a `log.go` file for every package that uses logging.
The file should include a declaration of the `log` variable with a field `package` set to
the full path of the package inside prysm.
For example package `kv` will have this `doc.go` file:
For example package `kv` will have this `log.go` file:
```go
// Package kv handles the key value db of prysm
//We can add package descriptions here, which is encouraged.
//
package kv
import "github.com/sirupsen/logrus"
var log = logrus.WithField("package", "beacon-chain/db/kv")
```
This way we can filter logs based on the paths provided by the user.
**1:**
### Implementation
We can have a script that generates the `doc.go` file for every package.
We also can enforce this rule on the GitHub actions checks.
But we might not need EVERY package to have this.
For example `testing/` or `tools/` are probably not needed.
We can have a script that generates the `log.go` file for every package that uses logging.
After generating the files, we can have a CI check that ensures that every package that uses logging has this file.
If not, devs should fix it manually by adding this file, or by running the script again.
We do not need EVERY package to have this file.
For example `testing/` or `tools/` are probably not needed.
Here is the list of number of packages per top level folder in the project:
- api – 14
- async – 3
- beacon-chain – 112
@@ -76,12 +97,12 @@ Here is the list of number of packages per top level folder in the project:
- tools – 50
- validator – 37
The point is, that we can exclude some of these paths from the rule.
**Open Question:** how to handle packages that do not emit a log (yet)? should we define the log variable as `_`?
We can exclude some of these paths from the rule.
### Improvements
We can also offer additional features here:
- We can let the users know that they can skip writing `beacon-chain` or `validator` in their path. We can just try for those paths as well, since most logs come from these packages.
- We can allow pattern matchings, so users can have more freedom of expressing what packages they want to mention.
- We can let the users know that they can skip writing `beacon-chain` or `validator` in their path. We can just try for
those paths as well, since most logs come from these packages.
- We could warn the user in case of conflicting rules in the visibility flags.