1.. _module-pw_log_tokenized: 2 3---------------- 4pw_log_tokenized 5---------------- 6The ``pw_log_tokenized`` module contains utilities for tokenized logging. It 7connects ``pw_log`` to ``pw_tokenizer``. 8 9C++ backend 10=========== 11``pw_log_tokenized`` provides a backend for ``pw_log`` that tokenizes log 12messages with the ``pw_tokenizer`` module. By default, log messages are 13tokenized with the ``PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD`` macro. 14The log level, 16-bit tokenized module name, and flags bits are passed through 15the payload argument. The macro eventually passes logs to the 16``pw_tokenizer_HandleEncodedMessageWithPayload`` function, which must be 17implemented by the application. 18 19Example implementation: 20 21.. code-block:: cpp 22 23 extern "C" void pw_tokenizer_HandleEncodedMessageWithPayload( 24 pw_tokenizer_Payload payload, const uint8_t message[], size_t size) { 25 // The metadata object provides the log level, module token, and flags. 26 // These values can be recorded and used for runtime filtering. 27 pw::log_tokenized::Metadata metadata(payload); 28 29 if (metadata.level() < current_log_level) { 30 return; 31 } 32 33 if (metadata.flags() & HIGH_PRIORITY_LOG != 0) { 34 EmitHighPriorityLog(metadata.module(), message, size); 35 } else { 36 EmitLowPriorityLog(metadata.module(), message, size); 37 } 38 } 39 40See the documentation for :ref:`module-pw_tokenizer` for further details. 41 42Using a custom macro 43-------------------- 44Applications may use their own macro instead of 45``PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD`` by setting the 46``PW_LOG_TOKENIZED_ENCODE_MESSAGE`` config macro. This macro should take 47arguments equivalent to ``PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD``: 48 49 .. c:function:: PW_LOG_TOKENIZED_ENCODE_MESSAGE(pw_tokenizer_Payload log_metadata, const char* message, ...) 50 51For instructions on how to implement a custom tokenization macro, see 52:ref:`module-pw_tokenizer-custom-macro`. 53 54Build targets 55------------- 56The GN build for ``pw_log_tokenized`` has two targets: ``pw_log_tokenized`` and 57``log_backend``. The ``pw_log_tokenized`` target provides the 58``pw_log_tokenized/log_tokenized.h`` header. The ``log_backend`` target 59implements the backend for the ``pw_log`` facade. ``pw_log_tokenized`` invokes 60the ``pw_tokenizer:global_handler_with_payload`` facade, which must be 61implemented by the user of ``pw_log_tokenized``. 62 63Python package 64============== 65``pw_log_tokenized`` includes a Python package for decoding tokenized logs. 66 67pw_log_tokenized 68---------------- 69.. automodule:: pw_log_tokenized 70 :members: 71 :undoc-members: 72