[PATCH 18/18] doc: Update logging documentation

[Heinrich Schuchardt]

On 10/6/20 9:16 PM, Sean Anderson wrote:
> This updates logging documentation with some examples of the new commands
> added in the previous commits. It also removes some items from the to-do
> list which have been implemented.
>
> Signed-off-by: Sean Anderson <seanga2 at gmail.com>
> ---
>
>  doc/develop/logging.rst | 42 +++++++++++++++++++++++++++++------------
>  1 file changed, 30 insertions(+), 12 deletions(-)
>
> diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst
> index 6a22062073..8b6237f829 100644
> --- a/doc/develop/logging.rst
> +++ b/doc/develop/logging.rst
> @@ -174,18 +174,45 @@ fields are present, but not the field order.
>  Filters
>  -------
>
> -Filters are attached to log drivers to control what those drivers emit. Only
> -records that pass through the filter make it to the driver.
> +Filters are attached to log drivers to control what those drivers emit. FIlters
> +can either allow or deny a log message when they match it. Only records which
> +are allowed by a filter make it to the driver.
>
>  Filters can be based on several criteria:
>
> -* maximum log level
> +* minimum or maximum log level
>  * in a set of categories
>  * in a set of files
>
>  If no filters are attached to a driver then a default filter is used, which
>  limits output to records with a level less than CONFIG_MAX_LOG_LEVEL.
>
> +Adding Filters
> +~~~~~~~~~~~~~~
> +
> +To add new filters at runtime, use the 'log filter-add' command. For example, to
> +filter messages from the SPI subsystem, run::

Does "filter" mean I see only messages from SPI or does this mean I see
no messages from SPI? If you mean suppress, please, use that word or
something similar.

> +
> +    log filter-add -D -c spi
> +
> +You will also need to allow everything else to emit messages (because the
> +default filter no longer applies)::
> +
> +    log filter-add -A -l debug

Thank you for starting the documenation.

Unfortunately after reading the lines above I have no clue what the
meaning of -D -A -c -l are.

Users will need a complete description of the log command with all
parameters.

Best regards

Heinrich

> +
> +To view active filters, use the 'log filter-list' command. Some example output
> +is::
> +
> +    => log filter-list
> +    num policy level           categories files
> +      0   deny <=IO                   spi
> +      1  allow <=DEBUG
> +
> +Note that filters are processed in-order from top to bottom, not in the order of
> +their filter number. Filters are added to the top of the list if they deny when
> +they match, and to the bottom if they allow when they match. For more
> +information, consult the usage of the 'log' command, by running 'help log'.
> +
>
>  Logging statements
>  ------------------
> @@ -259,8 +286,6 @@ Add a way to browse log records
>
>  Add a way to record log records for browsing using an external tool
>
> -Add commands to add and remove filters
> -
>  Add commands to add and remove log devices
>
>  Allow sharing of printf format strings in log records to reduce storage size
> @@ -268,10 +293,6 @@ for large numbers of log records
>
>  Add a command-line option to sandbox to set the default logging level
>
> -Convert core driver model code to use logging
> -
> -Convert uclasses to use logging with the correct category
> -
>  Consider making log() calls emit an automatic newline, perhaps with a logn()
>  function to avoid that
>
> @@ -282,9 +303,6 @@ number dropped due to them being generated before the log system was ready.
>
>  Add a printf() format string pragma so that log statements are checked properly
>
> -Enhance the log console driver to show level / category / file / line
> -information
> -
>  Add a command to add new log records and delete existing records.
>
>  Provide additional log() functions - e.g. logc() to specify the category
>