saltstack / saltstack/salt

[DOCS] Update incorrect details for log_granular_levels section of doc/ref/configuration/logging/index.rst

Open
#66,884 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description
The instructions for log_granular_levels show how to set a custom module to the log level all but in practice this does not work. Not sure if this is due to all not being a native log level within Pythons logging module.

Additionally, the following sentence needs updating.

You can determine what log call name to use here by adding %(module)s to the log format.

In practice Ive found that %(module)s only prints the short name of the module (i.e. custom_module).
However, %(name)s prints the fully qualified name of the module (i.e. salt.loaded.ext.module.custom_module).

Suggested Fix

Updated doc example:

log_granular_levels

Default: {}

This can be used to control logging levels more specifically, based on log call name. The example sets
the main salt library at the warning level, sets salt.modules to log
at the info level, and sets custom modules to the debug level:

  log_granular_levels:
    'salt': 'warning'
    'salt.modules': 'info'
    'salt.loader.saltmaster.ext.module.custom_module': 'debug'
    'salt.loaded.ext.module.custom_module': 'debug'
    'salt.loaded.ext.states.custom_module': 'debug'

You can determine what log call name to use here by adding %(name)s to the
log format. Typically, it is the path of the file which generates the log
without the trailing .py and with path separators replaced with .

Note: For these granular log levels to be reflected in the logs, the log_level_logfile and/or log_level
configurations must be set to at least the lowest level specified in the granular settings. For example, if
you set a module to log at the debug level in log_granular_levels, the log_level_logfile or log_level
must be set to debug for those debug logs to be written. Otherwise, the more restrictive general log level
will take precedence.

Type of documentation

  • Salt documentation

Location or format of documentation
doc/ref/configuration/logging/index.rst

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open doc/ref/configuration/logging/index.rst and locate the log_granular_levels section. Review the existing example and its explanation of log call names, then update the documented level and logger-name details using the issue’s suggested wording. Done means the section accurately describes the supported configuration and how to identify fully qualified logger names.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.