Clarify logging documentation #21665
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
extend documentation of logger outputs with short description (what do they do), and fix mistake in the brief listing
…nfig values. The new order of the settings moves those to earlier places that have a higher impact over the functionality of the logger
lunny
approved these changes
Nov 3, 2022
GiteaBot
added
the
lgtm/need 1
yardenshoham
approved these changes
Nov 4, 2022
GiteaBot
added
lgtm/done
yardenshoham
reviewed
Nov 4, 2022
|
Oh, we have a Markdown linter, thanks for reminding me about it! Pushed the fix. Also, I'll go ahead with the other changes. |
mpeter50
changed the title
mpeter50
changed the title
Details the usage of the main [log] section, and the default values it uses.
Outlines how the logging configuration is built up
|
For now if everything is ok then this is the final form of the file. There is still one TODO in it, though: I want to clarify what
I'm not familiar with the codebase, and searching for |
mpeter50
requested review from
yardenshoham and
lunny
and removed request for
yardenshoham
Codecov Report
@@ Coverage Diff @@
## main #21665 +/- ##
=======================================
Coverage ? 48.21%
=======================================
Files ? 1031
Lines ? 140846
Branches ? 0
=======================================
Hits ? 67912
Misses ? 64817
Partials ? 8117 Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. |
|
I've just noticed that in the same event where I requested reviews, Github says this:
Does that mean that I misclicked something, or that @yardenshoham has approved the changes (as the reviewers section on the right says)? |
|
Generally, if you want your PR reviewed change it from draft PR |
Oh, ok, thanks. I've set it this way so it's not merged accidentally, but I'll remove the draft marking. |
fsologureng
pushed a commit
to fsologureng/gitea
that referenced
this pull request
Nov 22, 2022
My pull request changes the logging documentation that is visible here: https://docs.gitea.io/en-us/logging-configuration/ The reason behind the changes is that for some time I've found the logging documentation confusing, and wanted to give a try at making it more clear. --- If you find the existing changes to be ok, please don't merge yet, as I have further ideas which I want to discuss with you before making the changes. ### Swap the "Log Groups" and "Log outputs" sections. I want to move the "Log outputs" section before the "Log Groups" section. The reason is that the "Log Groups" section refers to ini sections that are only later explained, and to concepts that are general and should be documented in "Log outputs" or a different section. This change is essentially a swap of the "Log Groups" and "Log outputs" sections. That way the doumentation would follow the structure in which the ini file is built: first explaining the outer sections, and then the inner ones ([log], [log.name], [log.name.default], ...) ### Explain the workings of ambigous settings below the settings listing Right now the basics of a setting is shown later than the explanation of its special workings, for example with `FILE_NAME` at [the file output mode](https://docs.gitea.io/en-us/logging-configuration/#file-mode) (well, if the first changes are taken into account). Currently I have `TODO` witten at 2 settings, which I have to figure out how do they exactly work before I can document them. ### New section about [log] New section after "Collecting Logs for Help" about how the top level [log] itself works and what can go there. Currently, variables that directly go into [log] are noted throughout the whole document. --- Please let me know what you think about the changes. A counterargument that I myself see is that some of this is already present in the cheatsheet, but I think it would be better to have [this document](https://docs.gitea.io/en-us/logging-configuration/) as a throrough explanation of how logging is configured, and the cheatsheet would only have a short outline of the possible sections and variables. Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
zjjhot
added a commit
to zjjhot/gitea
that referenced
this pull request
Nov 23, 2022
* giteaofficial/main: Handle empty author names (go-gitea#21902) Move all remaining colors into CSS variables (go-gitea#21903) Add option to enable CAPTCHA validation for login (go-gitea#21638) Prepend refs/heads/ to issue template refs (go-gitea#20461) Fixes go-gitea#21895: standardize UTC tz for util tests (go-gitea#21897) Clarify logging documentation (go-gitea#21665) Update JS dependencies (go-gitea#21881) Webhook list enhancements (go-gitea#21893) Embed Matrix icon as SVG (go-gitea#21890) fix(web): add `alt` for logo in home page (go-gitea#21887) Improvements for Content Copy (go-gitea#21842) Replace yaml.v2 with yaml.v3 (go-gitea#21832) Allow disable RSS/Atom feed (go-gitea#21622) Consolidate security-check into checks-backend (go-gitea#21882)
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
My pull request changes the logging documentation that is visible here: https://docs.gitea.io/en-us/logging-configuration/
The reason behind the changes is that for some time I've found the logging documentation confusing, and wanted to give a try at making it more clear.
If you find the existing changes to be ok, please don't merge yet, as I have further ideas which I want to discuss with you before making the changes.
Swap the "Log Groups" and "Log outputs" sections.
I want to move the "Log outputs" section before the "Log Groups" section. The reason is that the "Log Groups" section refers to ini sections that are only later explained, and to concepts that are general and should be documented in "Log outputs" or a different section.
This change is essentially a swap of the "Log Groups" and "Log outputs" sections. That way the doumentation would follow the structure in which the ini file is built: first explaining the outer sections, and then the inner ones ([log], [log.name], [log.name.default], ...)
Explain the workings of ambigous settings below the settings listing
Right now the basics of a setting is shown later than the explanation of its special workings, for example with
FILE_NAMEat the file output mode (well, if the first changes are taken into account).Currently I have
TODOwitten at 2 settings, which I have to figure out how do they exactly work before I can document them.New section about [log]
New section after "Collecting Logs for Help" about how the top level [log] itself works and what can go there.
Currently, variables that directly go into [log] are noted throughout the whole document.
Please let me know what you think about the changes.
A counterargument that I myself see is that some of this is already present in the cheatsheet, but I think it would be better to have this document as a throrough explanation of how logging is configured, and the cheatsheet would only have a short outline of the possible sections and variables.