zephyr/samples/subsys/logging/dictionary

.. zephyr:code-sample:: logging-dictionary
   :name: Dictionary-based logging
   :relevant-api: log_api

   Output binary log data using the dictionary-based logging API.

Overview
********

This is a sample app which utilizes :ref:`dictionary-based logging <logging_guide_dictionary>` and
the UART backend. This is configured to output binary log data
in hexadecimal so it could be run in terminal.

There is also a configuration which shows how shell commands can be used to configure runtime
filtering of the logging messages for the frontend (in the same way as it is done for backends).
See ``log frontend`` set of commands and use ``log_rt_demo`` command to test the filtering.

Configuration with shell requires that board has two UART devices (one for the shell and one for
the UART dictionary based frontend).


Building and Running
********************

This application can be built and executed on QEMU as follows:

.. zephyr-app-commands::
   :zephyr-app: samples/subsys/logging/dictionary
   :host-os: unix
   :board: qemu_x86
   :goals: run
   :compact:

To build for another board, change "qemu_x86" above to that board's name.


Sample Output
=============

   .. code-block:: none

      SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
      Booting from ROM..##ZLOGV1##000004000000000000ecd7000004000000f76a10001e6b10001d6b1000000003000000000000b3e30000030000004d6410004464100000080200000000000093e70000020000005e64100000200300000000000076eb0000030000006b641000dc60100000180200000000000043ef0000020000007c64100000200500000000000066f300000500000088641000dc60100001000000020000000020050000000000008cf7000005000000a2641000dc6010001000000011000000002005000000000000b3fb000005000000be641000dc60100020000000210000000020070000000000000600010007000000da641000dc60100040000000000000004100000000000000002004000000000000491f0100040000000e651000dc60100021000000002004000000000000e02801000400000025651000dc6010001a651000006007000000000000993501000401000032651000dc601000000000000364796e616d6963207374720000201b0000000000000c5701000a04000043651000dc601000000000003f651000000000003f651000000000003f651000000000000364796e616d696320737472000564796e616d6963207374720007616e6f746865722064796e616d6963207374720009616e6f746865722064796e616d6963207374720000600b000000000000736a01000801000066651000dc601000210000001a651000000000001a651000210000000564796e616d696320737472000020040000000000008c6e01000400000083651000dc601000da0310000020041a0000000000967a010004000000ba651000dc601000ad65100048455844554d50212048455844554d50402048455844554d5023


Running the Log Parser
======================

1. Pipe the run output or copy the hexadecimal string into a temporary file ``/tmp/serial.log``:

   .. code-block:: none

      ##ZLOGV1##000004000000000000ecd7000004000000f76a10001e6b10001d6b1000000003000000000000b3e30000030000004d6410004464100000080200000000000093e70000020000005e64100000200300000000000076eb0000030000006b641000dc60100000180200000000000043ef0000020000007c64100000200500000000000066f300000500000088641000dc60100001000000020000000020050000000000008cf7000005000000a2641000dc6010001000000011000000002005000000000000b3fb000005000000be641000dc60100020000000210000000020070000000000000600010007000000da641000dc60100040000000000000004100000000000000002004000000000000491f0100040000000e651000dc60100021000000002004000000000000e02801000400000025651000dc6010001a651000006007000000000000993501000401000032651000dc601000000000000364796e616d6963207374720000201b0000000000000c5701000a04000043651000dc601000000000003f651000000000003f651000000000003f651000000000000364796e616d696320737472000564796e616d6963207374720007616e6f746865722064796e616d6963207374720009616e6f746865722064796e616d6963207374720000600b000000000000736a01000801000066651000dc601000210000001a651000000000001a651000210000000564796e616d696320737472000020040000000000008c6e01000400000083651000dc601000da0310000020041a0000000000967a010004000000ba651000dc601000ad65100048455844554d50212048455844554d50402048455844554d5023

2. Run the log parser to get the text output:

   .. code-block:: console

      ./scripts/logging/dictionary/log_parser.py build/zephyr/log_dictionary.json /tmp/serial.log --hex

   And here is the output:

   .. code-block:: none

      *** Booting Zephyr OS build zephyr-v2.5.0-2471-g09b9eaf333e6  ***
      Hello World! qemu_x86
      [     77820] <err> hello_world: error string
      [     86332] <dbg> hello_world: main: debug string
      [     96275] <inf> hello_world: info string
      [    104784] <dbg> hello_world: main: int8_t 1, uint8_t 2
      [    117609] <dbg> hello_world: main: int16_t 16, uint16_t 17
      [    130454] <dbg> hello_world: main: int32_t 32, uint32_t 33
      [    143299] <dbg> hello_world: main: int64_t 64, uint64_t 65
      [    166374] <dbg> hello_world: main: char !
      [    179452] <dbg> hello_world: main: s str static str
      [    193395] <dbg> hello_world: main: d str dynamic str
      [    217283] <dbg> hello_world: main: mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
      [    266022] <dbg> hello_world: main: mixed c/s ! static str dynamic str static str !
      [    287888] <dbg> hello_world: main: pointer 0x10651a
      [    301600] <dbg> hello_world: main: For HeXdUmP!
                                    48 45 58 44 55 4d 50 21  20 48 45 58 44 55 4d 50 |HEXDUMP!  HEXDUMP
                                    40 20 48 45 58 44 55 4d  50 23                   |@ HEXDUM P#