[PATCH 18/18] doc: Update logging documentation

[Sean Anderson <seanga2@gmail.com>]

On 10/6/20 4:34 PM, Heinrich Schuchardt wrote:
> 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@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.

Ok.

> 
>> +
>> +    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.

These options are currently documented in the help text for log. Should
they be added here? I am concerned that duplicating documentation will
result in drift over time.

> 
> 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'.

Here is my suggestion of where to find a complete list of options.

--Sean

>>
>>  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
>>
>