.. _module-pw_log-protobuf:

-------------------
The pw_log protobuf
-------------------
``pw_log`` defines a protocol buffer for storing and transmitting log messages.
The protobuf is optimized to be maximally efficient.

Fields
======
The ``pw_log`` protobuf is defined in ``log.proto``.

.. literalinclude:: log.proto
  :language: protobuf
  :lines: 14-

Timestamps
----------
Timestamps are specified in implementation-defined ticks. Ticks could be
milliseconds, microsends, or any arbitrary duration derived from the device’s
clock.

For many applications, the timestamp field can be interpreted based on the prior
knowledge of the system. For example, ``timestamp`` might be known to be
milliseconds since boot for one core or microseconds since boot for another.

If desired, a project could collect information about clock parameters
separately from ``pw_log``, and use that to interpret log timestamps. For
example, they may call an RPC that returns a ``pw_chrono`` ``ClockParamters``
protobuf. The values from that could be used to interpret timestamp from that
device.

The ``pw_log`` proto contains two timestamp fields, only one of which may be set
at a time:

- ``timestamp`` – Absolute time when message was logged.
- ``time_since_last_entry`` – When the message was logged, relative
  to the previously encoded log message. This is used when multiple log entries
  are sent in a single ``LogEntries`` proto. The previous log entry must use the
  same time source. If logs with multiple time sources are intermingled in a
  single ``LogEntries`` proto, they must use an absolute timestamp each time the
  time source changes.

Optionally tokenized text fields
--------------------------------
Several fields in the ``pw_log`` proto store text. Examples include ``message``
and ``thread_name``. These fields may contain either plain or tokenized text,
either of which is represented as a single bytes field. These fields are marked
with a protocol buffer option so the ``pw_tokenizer.proto`` module can detect
and detokenize tokenized fields as appropriate.

See :ref:`module-pw_tokenizer-proto` for details.

Utility functions
-----------------
Conversion into the ``log.proto`` format from a tokenized log message can be
performed using the ``pw_log/proto_utils.h`` headers. Given tokenized data and
a payload, the headers provide a quick way to encode to the LogEntry protobuf.

.. code-block:: cpp

   #include "pw_log/proto_utils.h"

   extern "C" void pw_tokenizer_HandleEncodedMessageWithPayload(
       pw_tokenizer_Payload payload, const uint8_t data[], size_t size) {
     pw::log_tokenized::Metadata metadata(payload);
     std::byte log_buffer[kLogBufferSize];

     Result<ConstByteSpan> result = EncodeTokenizedLog(
         metadata,
         std::as_bytes(std::span(data, size)),
         log_buffer);
     if (result.ok()) {
       // This makes use of the encoded log proto and is custom per-product.
       // It should be implemented by the caller and is not in Pigweed.
       EmitProtoLogEntry(result.value());
     }
   }