1.. zephyr:code-sample:: logging-dictionary
2   :name: Dictionary-based logging
3   :relevant-api: log_api
4
5   Output binary log data using the dictionary-based logging API.
6
7Overview
8********
9
10This is a sample app which utilizes :ref:`dictionary-based logging <logging_guide_dictionary>` and
11the UART backend. This is configured to output binary log data
12in hexadecimal so it could be run in terminal.
13
14There is also a configuration which shows how shell commands can be used to configure runtime
15filtering of the logging messages for the frontend (in the same way as it is done for backends).
16See ``log frontend`` set of commands and use ``log_rt_demo`` command to test the filtering.
17
18Configuration with shell requires that board has two UART devices (one for the shell and one for
19the UART dictionary based frontend).
20
21
22Building and Running
23********************
24
25This application can be built and executed on QEMU as follows:
26
27.. zephyr-app-commands::
28   :zephyr-app: samples/subsys/logging/dictionary
29   :host-os: unix
30   :board: qemu_x86
31   :goals: run
32   :compact:
33
34To build for another board, change "qemu_x86" above to that board's name.
35
36
37Sample Output
38=============
39
40   .. code-block:: none
41
42      SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
43      Booting from ROM..##ZLOGV1##000004000000000000ecd7000004000000f76a10001e6b10001d6b1000000003000000000000b3e30000030000004d6410004464100000080200000000000093e70000020000005e64100000200300000000000076eb0000030000006b641000dc60100000180200000000000043ef0000020000007c64100000200500000000000066f300000500000088641000dc60100001000000020000000020050000000000008cf7000005000000a2641000dc6010001000000011000000002005000000000000b3fb000005000000be641000dc60100020000000210000000020070000000000000600010007000000da641000dc60100040000000000000004100000000000000002004000000000000491f0100040000000e651000dc60100021000000002004000000000000e02801000400000025651000dc6010001a651000006007000000000000993501000401000032651000dc601000000000000364796e616d6963207374720000201b0000000000000c5701000a04000043651000dc601000000000003f651000000000003f651000000000003f651000000000000364796e616d696320737472000564796e616d6963207374720007616e6f746865722064796e616d6963207374720009616e6f746865722064796e616d6963207374720000600b000000000000736a01000801000066651000dc601000210000001a651000000000001a651000210000000564796e616d696320737472000020040000000000008c6e01000400000083651000dc601000da0310000020041a0000000000967a010004000000ba651000dc601000ad65100048455844554d50212048455844554d50402048455844554d5023
44
45
46Running the Log Parser
47======================
48
491. Pipe the run output or copy the hexadecimal string into a temporary file ``/tmp/serial.log``:
50
51   .. code-block:: none
52
53      ##ZLOGV1##000004000000000000ecd7000004000000f76a10001e6b10001d6b1000000003000000000000b3e30000030000004d6410004464100000080200000000000093e70000020000005e64100000200300000000000076eb0000030000006b641000dc60100000180200000000000043ef0000020000007c64100000200500000000000066f300000500000088641000dc60100001000000020000000020050000000000008cf7000005000000a2641000dc6010001000000011000000002005000000000000b3fb000005000000be641000dc60100020000000210000000020070000000000000600010007000000da641000dc60100040000000000000004100000000000000002004000000000000491f0100040000000e651000dc60100021000000002004000000000000e02801000400000025651000dc6010001a651000006007000000000000993501000401000032651000dc601000000000000364796e616d6963207374720000201b0000000000000c5701000a04000043651000dc601000000000003f651000000000003f651000000000003f651000000000000364796e616d696320737472000564796e616d6963207374720007616e6f746865722064796e616d6963207374720009616e6f746865722064796e616d6963207374720000600b000000000000736a01000801000066651000dc601000210000001a651000000000001a651000210000000564796e616d696320737472000020040000000000008c6e01000400000083651000dc601000da0310000020041a0000000000967a010004000000ba651000dc601000ad65100048455844554d50212048455844554d50402048455844554d5023
54
552. Run the log parser to get the text output:
56
57   .. code-block:: console
58
59      ./scripts/logging/dictionary/log_parser.py build/zephyr/log_dictionary.json /tmp/serial.log --hex
60
61   And here is the output:
62
63   .. code-block:: none
64
65      *** Booting Zephyr OS build zephyr-v2.5.0-2471-g09b9eaf333e6  ***
66      Hello World! qemu_x86
67      [     77820] <err> hello_world: error string
68      [     86332] <dbg> hello_world: main: debug string
69      [     96275] <inf> hello_world: info string
70      [    104784] <dbg> hello_world: main: int8_t 1, uint8_t 2
71      [    117609] <dbg> hello_world: main: int16_t 16, uint16_t 17
72      [    130454] <dbg> hello_world: main: int32_t 32, uint32_t 33
73      [    143299] <dbg> hello_world: main: int64_t 64, uint64_t 65
74      [    166374] <dbg> hello_world: main: char !
75      [    179452] <dbg> hello_world: main: s str static str
76      [    193395] <dbg> hello_world: main: d str dynamic str
77      [    217283] <dbg> hello_world: main: mixed str dynamic str --- dynamic str --- another dynamic str --- another dynamic str
78      [    266022] <dbg> hello_world: main: mixed c/s ! static str dynamic str static str !
79      [    287888] <dbg> hello_world: main: pointer 0x10651a
80      [    301600] <dbg> hello_world: main: For HeXdUmP!
81                                    48 45 58 44 55 4d 50 21  20 48 45 58 44 55 4d 50 |HEXDUMP!  HEXDUMP
82                                    40 20 48 45 58 44 55 4d  50 23                   |@ HEXDUM P#
83