doc: integrate dict logging into main logging section
This belong alongside other logging related documentation. No for this to exist on its own. Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif
parent
b3c107a432
commit
52398df7b6
4 changed files with 69 additions and 79 deletions
|
|
@ -35,4 +35,3 @@ User and Developer Guides
|
|||
optimizations/index
|
||||
zephyr_cmake_package.rst
|
||||
thread_local_storage.rst
|
||||
logging/index
|
||||
|
|
|
|||
|
|
@ -1,69 +0,0 @@
|
|||
.. _logging_guide_dictionary:
|
||||
|
||||
Dictionary-based Logging
|
||||
########################
|
||||
|
||||
Dictionary-based logging, instead of human readable texts, outputs the log
|
||||
messages in binary format. This binary format encodes arguments to formatted
|
||||
strings in their native storage formats which can be more compact than their
|
||||
text equivalents. For statically defined strings (including the format
|
||||
strings and any string arguments), references to the ELF file are encoded
|
||||
instead of the whole strings. A dictionary created at build time contains
|
||||
the mappings between these references and the actual strings. This allows
|
||||
the offline parser to obtain the strings from the dictionary to parse
|
||||
the log messages. This binary format allows a more compact representation
|
||||
of log messages in certain scenarios. However, this requires the use of
|
||||
an offline parser and is not as intuitive to use as text-based log messages.
|
||||
|
||||
Note that ``long double`` is not supported by Python's ``struct`` module.
|
||||
Therefore, log messages with ``long double`` will not display the correct
|
||||
values.
|
||||
|
||||
|
||||
Configuration
|
||||
*************
|
||||
|
||||
Here are kconfig options related to dictionary-based logging:
|
||||
|
||||
- :option:`CONFIG_LOG_DICTIONARY_SUPPORT` enables dictionary-based logging
|
||||
support. This should be selected by the backends which require it.
|
||||
|
||||
- The UART backend can be used for dictionary-based logging. These are
|
||||
additional config for the UART backend:
|
||||
|
||||
- :option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX` tells
|
||||
the UART backend to output hexadecimal characters for dictionary based
|
||||
logging. This is useful when the log data needs to be captured manually
|
||||
via terminals and consoles.
|
||||
|
||||
- :option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_BIN` tells
|
||||
the UART backend to output binary data.
|
||||
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
When dictionary-based logging is enabled via enabling related logging backends,
|
||||
a JSON database file, named :file:`log_dictionary.json`, will be created
|
||||
in the build directory. This database file contains information for the parser
|
||||
to correctly parse the log data. Note that this database file only works
|
||||
with the same build, and cannot be used for any other builds.
|
||||
|
||||
To use the log parser:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
./scripts/logging/dictionary/log_parser.py <build dir>/log_dictionary.json <log data file>
|
||||
|
||||
The parser takes two required arguments, where the first one is the full path
|
||||
to the JSON database file, and the second part is the file containing log data.
|
||||
Add an optional argument ``--hex`` to the end if the log data file contains
|
||||
hexadecimal characters
|
||||
(e.g. when ``CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX=y``). This tells
|
||||
the parser to convert the hexadecimal characters to binary before parsing.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Please refer to :ref:`logging_dictionary_sample` on how to use the log parser.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
.. _logging_guide:
|
||||
|
||||
Logging
|
||||
#######
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
dictionary.rst
|
||||
|
|
@ -636,6 +636,75 @@ Example message formatted using :c:func:`log_output_msg_process` or
|
|||
|
||||
[00:00:00.000,274] <info> sample_instance.inst1: logging message
|
||||
|
||||
|
||||
.. _logging_guide_dictionary:
|
||||
|
||||
Dictionary-based Logging
|
||||
========================
|
||||
|
||||
Dictionary-based logging, instead of human readable texts, outputs the log
|
||||
messages in binary format. This binary format encodes arguments to formatted
|
||||
strings in their native storage formats which can be more compact than their
|
||||
text equivalents. For statically defined strings (including the format
|
||||
strings and any string arguments), references to the ELF file are encoded
|
||||
instead of the whole strings. A dictionary created at build time contains
|
||||
the mappings between these references and the actual strings. This allows
|
||||
the offline parser to obtain the strings from the dictionary to parse
|
||||
the log messages. This binary format allows a more compact representation
|
||||
of log messages in certain scenarios. However, this requires the use of
|
||||
an offline parser and is not as intuitive to use as text-based log messages.
|
||||
|
||||
Note that ``long double`` is not supported by Python's ``struct`` module.
|
||||
Therefore, log messages with ``long double`` will not display the correct
|
||||
values.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Here are kconfig options related to dictionary-based logging:
|
||||
|
||||
- :option:`CONFIG_LOG_DICTIONARY_SUPPORT` enables dictionary-based logging
|
||||
support. This should be selected by the backends which require it.
|
||||
|
||||
- The UART backend can be used for dictionary-based logging. These are
|
||||
additional config for the UART backend:
|
||||
|
||||
- :option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX` tells
|
||||
the UART backend to output hexadecimal characters for dictionary based
|
||||
logging. This is useful when the log data needs to be captured manually
|
||||
via terminals and consoles.
|
||||
|
||||
- :option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_BIN` tells
|
||||
the UART backend to output binary data.
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
When dictionary-based logging is enabled via enabling related logging backends,
|
||||
a JSON database file, named :file:`log_dictionary.json`, will be created
|
||||
in the build directory. This database file contains information for the parser
|
||||
to correctly parse the log data. Note that this database file only works
|
||||
with the same build, and cannot be used for any other builds.
|
||||
|
||||
To use the log parser:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
./scripts/logging/dictionary/log_parser.py <build dir>/log_dictionary.json <log data file>
|
||||
|
||||
The parser takes two required arguments, where the first one is the full path
|
||||
to the JSON database file, and the second part is the file containing log data.
|
||||
Add an optional argument ``--hex`` to the end if the log data file contains
|
||||
hexadecimal characters
|
||||
(e.g. when ``CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX=y``). This tells
|
||||
the parser to convert the hexadecimal characters to binary before parsing.
|
||||
|
||||
Please refer to :ref:`logging_dictionary_sample` on how to use the log parser.
|
||||
|
||||
|
||||
|
||||
Limitations and recommendations
|
||||
*******************************
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue