esphome-docs/components/logger.rst

210 lines
7.5 KiB
ReStructuredText
Raw Normal View History

.. _logger:
2018-05-13 11:37:02 +02:00
Logger Component
================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up the central logging component in ESPHome.
:image: file-document-box.svg
2018-11-14 22:12:27 +01:00
2018-05-13 11:37:02 +02:00
The logger component automatically logs all log messages through the
serial port and through MQTT topics (if there is an MQTT client in the
configuration). By default, all logs with a severity ``DEBUG`` or higher will be shown.
Increasing the log level severity (to e.g ``INFO`` or ``WARNING``) can help with the performance of the application and memory size.
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
# Example configuration entry
logger:
level: DEBUG
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-05-13 11:37:02 +02:00
- **baud_rate** (*Optional*, int): The baud rate to use for the serial
2018-08-27 13:21:30 +02:00
UART port. Defaults to ``115200``. Set to ``0`` to disable logging via UART.
2018-05-13 11:37:02 +02:00
- **level** (*Optional*, string): The global log level. Any log message
with a lower severity will not be shown. Defaults to ``DEBUG``.
2018-05-13 11:37:02 +02:00
- **logs** (*Optional*, mapping): Manually set the log level for a
2018-06-01 18:10:00 +02:00
specific component or tag. See :ref:`Manual Log Levels for more
information <logger-manual_tag_specific_levels>`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2019-05-12 22:44:59 +02:00
Advanced settings:
- **tx_buffer_size** (*Optional*, int): The size of the buffer used
for log messages. Decrease this if youre having memory problems.
Defaults to ``512``.
- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging.
Defaults to ``UART0``.
- **esp8266_store_log_strings_in_flash** (*Optional*, boolean): If set to false, disables storing
log strings in the flash section of the device (uses more memory). Defaults to true.
- **on_message** (*Optional*, :ref:`Automation <automation>`): An action to be
2021-07-23 01:05:32 +02:00
performed when a message is to be logged. The variables ``int level``, ``const char* tag`` and
``const char* message`` are available for lambda processing.
- **deassert_rts_dtr** (*Optional*, boolean): Deasserts RTS/DTR when opening
log over UART. This is useful if RTS/DTR signals are directly connected to
the reset pin or strapping pins. Note: Deassert typically means high on TTL
level since RTS/DTR are usually low active signals. Defaults to ``false``.
2019-05-12 22:44:59 +02:00
.. _logger-hardware_uarts:
Hardware UARTs
--------------
The logger component makes use of platform-specific hardware UARTs for serial logging.
By default, the logger will occupy ``UART0``. The ESP32 has three hardware UARTs, all of
which can be used for both transmit and receive. The ESP8266 only has two hardware UARTs,
one of which is transmit-only. The ESP8266 ``UART0`` can also be 'swapped' to TX/RX on the
CTS/RTS pins, if you need to use GPIO1 and GPIO3 for something else. Note that the common
NodeMCU boards have their USB-UART Adapters fixed to the default GPIOs used by ``UART0``,
so if you use anything else you will not get log messages over the on-board USB.
Possible Hardware UART configurations:
- ``UART0`` - TX: GPIO1, RX: GPIO3
- ``UART0_SWAP`` - TX: GPIO15, RX: GPIO13 (Only on ESP8266)
- ``UART1`` - TX: GPIO2, RX: None (Only on ESP8266)
- ``UART1`` - TX: GPIO9, RX: GPIO10 (Only on ESP32)
- ``UART2`` - TX: GPIO16, RX: GPIO17 (Only on ESP32 but not ESP32S2, ESP32S3 or ESP32C3)
- ``USB_CDC`` - uses the USB CDC driver (Only on ESP32S2 and ESP32S3)
- ``USB_SERIAL_JTAG`` - uses the USB Serial/JTAG driver (Only on ESP32S3 and ESP32C3)
2018-06-01 18:10:00 +02:00
.. _logger-log_levels:
2018-05-13 11:37:02 +02:00
Log Levels
2018-08-24 22:44:01 +02:00
----------
2018-05-13 11:37:02 +02:00
Possible log levels are (sorted by severity):
- ``NONE``
2018-11-23 12:33:49 +01:00
- No messages are logged.
2018-05-13 11:37:02 +02:00
- ``ERROR``
2018-11-23 12:33:49 +01:00
- With this log level, only errors are logged. Errors are issues that prevent the ESP from working
correctly. Color: red
2018-05-13 11:37:02 +02:00
- ``WARN``
2018-11-23 12:33:49 +01:00
- With this log level, warnings and errors are logged. Warnings are issues like invalid readings from
2019-02-16 23:25:23 +01:00
sensors that ESPHome can recover from. Color: yellow
2018-11-23 12:33:49 +01:00
2018-05-13 11:37:02 +02:00
- ``INFO``
2018-11-23 12:33:49 +01:00
- With this log level, everything up to info messages are logged; so errors, warnings and info. Color: green
- ``DEBUG`` (**Default**)
- Everything up to this log level is logged. Debug messages include the current readings from a sensor
and status messages. Color: cyan
2018-05-13 11:37:02 +02:00
- ``VERBOSE``
2018-11-23 12:33:49 +01:00
- Like debug, but a few more messages that are usually deemed to be spam are also included. Color: grey
2018-05-14 21:15:49 +02:00
- ``VERY_VERBOSE``
2018-05-13 11:37:02 +02:00
2018-11-23 12:33:49 +01:00
- All internal messages are logged. Including all the data flowing through data buses like
I²C, SPI or UART. Warning: May cause the device to slow down and have trouble staying
2019-05-12 22:44:59 +02:00
connecting due to amount of generated messages. Color: white
2018-11-23 12:33:49 +01:00
2018-06-01 18:10:00 +02:00
.. _logger-manual_tag_specific_levels:
2018-05-13 11:37:02 +02:00
Manual Tag-Specific Log Levels
2018-08-24 22:44:01 +02:00
------------------------------
2018-05-13 11:37:02 +02:00
If some component is spamming the logs and you want to manually set the
log level for it, first identify the tag of the log messages in question
and then disable them in your configuration.
Suppose we want to have verbose log messages globally, but the MQTT
client spams too much. In the following example, wed first see that the
tag of the MQTT client is ``mqtt.client`` (before the first colon) and
the tag for MQTT components is ``mqtt.component``.
2018-06-01 18:10:00 +02:00
.. figure:: images/logger-manual_log_level.png
2018-05-13 11:37:02 +02:00
Next, we can manually set the log levels in the configuration like this:
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
logger:
level: VERBOSE
logs:
mqtt.component: DEBUG
mqtt.client: ERROR
Please note that the global log level determines what log messages are
2021-01-11 17:46:37 +01:00
saved in the binary. So for example an ``INFO`` global log message will
2018-05-13 11:37:02 +02:00
purge all ``DEBUG`` log statements from the binary in order to conserve
space. This however means that you cannot set tag-specific log levels
that have a lower severity than the global log level.
2018-10-20 15:19:31 +02:00
.. _logger-log_action:
``logger.log`` Action
---------------------
Print a formatted message to the logs.
In the ``format`` option, you can use ``printf``-style formatting (see :ref:`display-printf`).
.. code-block:: yaml
2018-10-20 15:19:31 +02:00
on_...:
then:
- logger.log: "Hello World"
# Formatted:
- logger.log:
format: "The temperature sensor reports value %.1f and humidity %.1f"
2019-01-13 15:49:06 +01:00
args: [ 'id(temperature_sensor).state', 'id(humidity_sensor).state' ]
2018-10-20 15:19:31 +02:00
Configuration options:
- **format** (**Required**, string): The format for the message in :ref:`printf-style <display-printf>`.
- **args** (*Optional*, list of :ref:`lambda <config-lambda>`): The optional arguments for the
format message.
- **level** (*Optional*, string): The :ref:`log level <logger-log_levels>` to print the message
with. Defaults to ``DEBUG``.
- **tag** (*Optional*, string): The tag (seen in front of the message in the logs) to print the message
with. Defaults to ``main``.
Logger Automation
-----------------
.. _logger-on_message:
``on_message``
**************
This automation will be triggered when a new message is added to the log.
In :ref:`lambdas <config-lambda>` you can get the message, log level and tag from the trigger
using ``message`` (``const char *``), ``level`` (``int``) and ``tag`` (``const char *``).
.. code-block:: yaml
logger:
# ...
on_message:
level: ERROR
then:
- mqtt.publish:
topic: some/topic
payload: !lambda |-
return "Triggered on_message with level " + to_string(level) + ", tag " + tag + " and message " + message;
.. note::
Logging will not work in the ``on_message`` trigger. You can't use the :ref:`logger.log <logger-log_action>` action
and the ``ESP_LOGx`` logging macros in this automation.
2018-06-01 18:10:00 +02:00
See Also
--------
2018-05-13 11:37:02 +02:00
- :doc:`/components/uart`
2019-05-12 22:44:59 +02:00
- :apiref:`logger/logger.h`
- :ghedit:`Edit`