ESPHome 2025.7.5
Loading...
Searching...
No Matches
esphome::logger::Logger Class Reference

Logger component for all ESPHome logging. More...

#include <logger.h>

Inheritance diagram for esphome::logger::Logger:
esphome::Component

Public Member Functions

 Logger (uint32_t baud_rate, size_t tx_buffer_size)
 
void init_log_buffer (size_t total_buffer_size)
 
void loop () override
 
void set_baud_rate (uint32_t baud_rate)
 Manually set the baud rate for serial, set to 0 to disable.
 
uint32_t get_baud_rate () const
 
Stream * get_hw_serial () const
 
uart_port_t get_uart_num () const
 
void create_pthread_key ()
 
void set_uart_selection (UARTSelection uart_selection)
 
UARTSelection get_uart () const
 Get the UART used by the logger.
 
void set_log_level (uint8_t level)
 Set the default log level for this logger.
 
void set_log_level (const std::string &tag, uint8_t log_level)
 Set the log level of the specified tag.
 
uint8_t get_log_level ()
 
void pre_setup ()
 Set up this component.
 
void dump_config () override
 
uint8_t level_for (const char *tag)
 
void add_on_log_callback (std::function< void(uint8_t, const char *, const char *, size_t)> &&callback)
 Register a callback that will be called for every log message sent.
 
void add_listener (std::function< void(uint8_t)> &&callback)
 
float get_setup_priority () const override
 
void log_vprintf_ (uint8_t level, const char *tag, int line, const char *format, va_list args)
 
void log_vprintf_ (uint8_t level, const char *tag, int line, const __FlashStringHelper *format, va_list args)
 
- Public Member Functions inherited from esphome::Component
virtual void setup ()
 Where the component's initialization should happen.
 
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
virtual float get_loop_priority () const
 priority of loop().
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
virtual bool teardown ()
 Called during teardown to allow component to gracefully finish operations.
 
virtual void on_powerdown ()
 Called after teardown is complete to power down hardware.
 
uint8_t get_component_state () const
 
void reset_to_construction_state ()
 Reset this component back to the construction state to allow setup to run again.
 
bool is_in_loop_state () const
 Check if this component has completed setup and is in the loop state.
 
virtual void mark_failed ()
 Mark this component as failed.
 
void mark_failed (const char *message)
 
void disable_loop ()
 Disable this component's loop.
 
void enable_loop ()
 Enable this component's loop.
 
void enable_loop_soon_any_context ()
 Thread and ISR-safe version of enable_loop() that can be called from any context.
 
bool is_failed () const
 
bool is_ready () const
 
virtual bool can_proceed ()
 
bool status_has_warning () const
 
bool status_has_error () const
 
void status_set_warning (const char *message="unspecified")
 
void status_set_error (const char *message="unspecified")
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const std::string &name, uint32_t length=5000)
 
void status_momentary_error (const std::string &name, uint32_t length=5000)
 
bool has_overridden_loop () const
 
void set_component_source (const char *source)
 Set where this component was loaded from for some debug messages.
 
const char * get_component_source () const
 Get the integration where this component was declared as a string.
 
bool should_warn_of_blocking (uint32_t blocking_time)
 

Protected Member Functions

void write_msg_ (const char *msg)
 
void HOT format_log_to_buffer_with_terminator_ (uint8_t level, const char *tag, int line, const char *format, va_list args, char *buffer, uint16_t *buffer_at, uint16_t buffer_size)
 
void HOT log_message_to_buffer_and_send_ (uint8_t level, const char *tag, int line, const char *format, va_list args)
 
void write_body_to_buffer_ (const char *value, size_t length, char *buffer, uint16_t *buffer_at, uint16_t buffer_size)
 
void printf_to_buffer_ (char *buffer, uint16_t *buffer_at, uint16_t buffer_size, const char *format,...)
 
const char * get_uart_selection_ ()
 
const char *HOT get_thread_name_ ()
 
bool HOT check_and_set_task_log_recursion_ (bool is_main_task)
 
void HOT reset_task_log_recursion_ (bool is_main_task)
 
void HOT write_header_to_buffer_ (uint8_t level, const char *tag, int line, const char *thread_name, char *buffer, uint16_t *buffer_at, uint16_t buffer_size)
 
void HOT format_body_to_buffer_ (char *buffer, uint16_t *buffer_at, uint16_t buffer_size, const char *format, va_list args)
 
void HOT write_footer_to_buffer_ (char *buffer, uint16_t *buffer_at, uint16_t buffer_size)
 
void disable_loop_when_buffer_empty_ ()
 
- Protected Member Functions inherited from esphome::Component
virtual void call_loop ()
 
virtual void call_setup ()
 
virtual void call_dump_config ()
 
void set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a unique name.
 
void set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a const char* name.
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const std::string &name)
 Cancel an interval function.
 
bool cancel_interval (const char *name)
 
void set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
 Set an retry function with a unique name.
 
void set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
 
bool cancel_retry (const std::string &name)
 Cancel a retry function.
 
void set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a unique name.
 
void set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a const char* name.
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (const std::string &name)
 Cancel a timeout function.
 
bool cancel_timeout (const char *name)
 
void defer (const std::string &name, std::function< void()> &&f)
 Defer a callback to the next loop() call.
 
void defer (const char *name, std::function< void()> &&f)
 Defer a callback to the next loop() call with a const char* name.
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call.
 
bool cancel_defer (const std::string &name)
 Cancel a defer callback using the specified name, name must not be empty.
 

Protected Attributes

uint32_t baud_rate_
 
char * tx_buffer_ {nullptr}
 
Stream * hw_serial_ {nullptr}
 
void * main_task_ = nullptr
 
pthread_key_t log_recursion_key_
 
uart_port_t uart_num_
 
std::map< std::string, uint8_t > log_levels_ {}
 
CallbackManager< void(uint8_t, const char *, const char *, size_t)> log_callback_ {}
 
CallbackManager< void(uint8_t)> level_callback_ {}
 
std::unique_ptr< logger::TaskLogBufferlog_buffer_
 
uint16_t tx_buffer_at_ {0}
 
uint16_t tx_buffer_size_ {0}
 
uint8_t current_level_ {ESPHOME_LOG_LEVEL_VERY_VERBOSE}
 
UARTSelection uart_ {UART_SELECTION_UART0}
 
bool main_task_recursion_guard_ {false}
 
bool global_recursion_guard_ {false}
 
- Protected Attributes inherited from esphome::Component
const char * component_source_ {nullptr}
 
uint16_t warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_MS}
 Warn if blocked for this many ms (max 65.5s)
 
uint8_t component_state_ {0x00}
 State of this component - each bit has a purpose: Bits 0-1: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED) Bit 2: STATUS_LED_WARNING Bit 3: STATUS_LED_ERROR Bits 4-7: Unused - reserved for future expansion (50% of the bits are free)
 
volatile bool pending_enable_loop_ {false}
 ISR-safe flag for enable_loop_soon_any_context.
 

Detailed Description

Logger component for all ESPHome logging.

This class implements a multi-platform logging system with protection against recursion.

Recursion Protection Strategy:

  • On ESP32: Uses task-specific recursion guards
    • Main task: Uses a dedicated boolean member variable for efficiency
    • Other tasks: Uses pthread TLS with a dynamically allocated key for task-specific state
  • On other platforms: Uses a simple global recursion guard

We use pthread TLS via pthread_key_create to create a unique key for storing task-specific recursion state, which:

  1. Efficiently handles multiple tasks without locks or mutexes
  2. Works with ESP-IDF's pthread implementation that uses a linked list for TLS variables
  3. Avoids the limitations of the fixed FreeRTOS task local storage slots

Definition at line 104 of file logger.h.

Constructor & Destructor Documentation

◆ Logger()

esphome::logger::Logger::Logger ( uint32_t baud_rate,
size_t tx_buffer_size )
explicit

Definition at line 158 of file logger.cpp.

Member Function Documentation

◆ add_listener()

void esphome::logger::Logger::add_listener ( std::function< void(uint8_t)> && callback)
inline

Definition at line 149 of file logger.h.

◆ add_on_log_callback()

void esphome::logger::Logger::add_on_log_callback ( std::function< void(uint8_t, const char *, const char *, size_t)> && callback)

Register a callback that will be called for every log message sent.

Definition at line 239 of file logger.cpp.

◆ check_and_set_task_log_recursion_()

bool HOT esphome::logger::Logger::check_and_set_task_log_recursion_ ( bool is_main_task)
inlineprotected

Definition at line 287 of file logger.h.

◆ create_pthread_key()

void esphome::logger::Logger::create_pthread_key ( )
inline

Definition at line 123 of file logger.h.

◆ disable_loop_when_buffer_empty_()

void esphome::logger::Logger::disable_loop_when_buffer_empty_ ( )
inlineprotected

Definition at line 364 of file logger.h.

◆ dump_config()

void esphome::logger::Logger::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 245 of file logger.cpp.

◆ format_body_to_buffer_()

void HOT esphome::logger::Logger::format_body_to_buffer_ ( char * buffer,
uint16_t * buffer_at,
uint16_t buffer_size,
const char * format,
va_list args )
inlineprotected

Definition at line 334 of file logger.h.

◆ format_log_to_buffer_with_terminator_()

void HOT esphome::logger::Logger::format_log_to_buffer_with_terminator_ ( uint8_t level,
const char * tag,
int line,
const char * format,
va_list args,
char * buffer,
uint16_t * buffer_at,
uint16_t buffer_size )
inlineprotected

Definition at line 164 of file logger.h.

◆ get_baud_rate()

uint32_t esphome::logger::Logger::get_baud_rate ( ) const
inline

Definition at line 115 of file logger.h.

◆ get_hw_serial()

Stream * esphome::logger::Logger::get_hw_serial ( ) const
inline

Definition at line 117 of file logger.h.

◆ get_log_level()

uint8_t esphome::logger::Logger::get_log_level ( )
inline

Definition at line 135 of file logger.h.

◆ get_setup_priority()

float esphome::logger::Logger::get_setup_priority ( ) const
overridevirtual

Reimplemented from esphome::Component.

Definition at line 242 of file logger.cpp.

◆ get_thread_name_()

const char *HOT esphome::logger::Logger::get_thread_name_ ( )
inlineprotected

Definition at line 272 of file logger.h.

◆ get_uart()

UARTSelection esphome::logger::Logger::get_uart ( ) const

Get the UART used by the logger.

Definition at line 236 of file logger.cpp.

◆ get_uart_num()

uart_port_t esphome::logger::Logger::get_uart_num ( ) const
inline

Definition at line 120 of file logger.h.

◆ get_uart_selection_()

const char * esphome::logger::Logger::get_uart_selection_ ( )
protected

Definition at line 210 of file logger_esp32.cpp.

◆ init_log_buffer()

void esphome::logger::Logger::init_log_buffer ( size_t total_buffer_size)

Definition at line 166 of file logger.cpp.

◆ level_for()

uint8_t esphome::logger::Logger::level_for ( const char * tag)
inline

Definition at line 151 of file logger.cpp.

◆ log_message_to_buffer_and_send_()

void HOT esphome::logger::Logger::log_message_to_buffer_and_send_ ( uint8_t level,
const char * tag,
int line,
const char * format,
va_list args )
inlineprotected

Definition at line 185 of file logger.h.

◆ log_vprintf_() [1/2]

void esphome::logger::Logger::log_vprintf_ ( uint8_t level,
const char * tag,
int line,
const __FlashStringHelper * format,
va_list args )

Definition at line 112 of file logger.cpp.

◆ log_vprintf_() [2/2]

void HOT esphome::logger::Logger::log_vprintf_ ( uint8_t level,
const char * tag,
int line,
const char * format,
va_list args )

Definition at line 27 of file logger.cpp.

◆ loop()

void esphome::logger::Logger::loop ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 176 of file logger.cpp.

◆ pre_setup()

void esphome::logger::Logger::pre_setup ( )

Set up this component.

Definition at line 95 of file logger_esp32.cpp.

◆ printf_to_buffer_()

void esphome::logger::Logger::printf_to_buffer_ ( char * buffer,
uint16_t * buffer_at,
uint16_t buffer_size,
const char * format,
... )
inlineprotected

Definition at line 217 of file logger.h.

◆ reset_task_log_recursion_()

void HOT esphome::logger::Logger::reset_task_log_recursion_ ( bool is_main_task)
inlineprotected

Definition at line 302 of file logger.h.

◆ set_baud_rate()

void esphome::logger::Logger::set_baud_rate ( uint32_t baud_rate)

Manually set the baud rate for serial, set to 0 to disable.

Definition at line 232 of file logger.cpp.

◆ set_log_level() [1/2]

void esphome::logger::Logger::set_log_level ( const std::string & tag,
uint8_t log_level )

Set the log level of the specified tag.

Definition at line 233 of file logger.cpp.

◆ set_log_level() [2/2]

void esphome::logger::Logger::set_log_level ( uint8_t level)

Set the default log level for this logger.

Definition at line 268 of file logger.cpp.

◆ set_uart_selection()

void esphome::logger::Logger::set_uart_selection ( UARTSelection uart_selection)
inline

Definition at line 126 of file logger.h.

◆ write_body_to_buffer_()

void esphome::logger::Logger::write_body_to_buffer_ ( const char * value,
size_t length,
char * buffer,
uint16_t * buffer_at,
uint16_t buffer_size )
inlineprotected

Definition at line 199 of file logger.h.

◆ write_footer_to_buffer_()

void HOT esphome::logger::Logger::write_footer_to_buffer_ ( char * buffer,
uint16_t * buffer_at,
uint16_t buffer_size )
inlineprotected

Definition at line 357 of file logger.h.

◆ write_header_to_buffer_()

void HOT esphome::logger::Logger::write_header_to_buffer_ ( uint8_t level,
const char * tag,
int line,
const char * thread_name,
char * buffer,
uint16_t * buffer_at,
uint16_t buffer_size )
inlineprotected

Definition at line 312 of file logger.h.

◆ write_msg_()

void HOT esphome::logger::Logger::write_msg_ ( const char * msg)
protected

Definition at line 173 of file logger_esp32.cpp.

Field Documentation

◆ baud_rate_

uint32_t esphome::logger::Logger::baud_rate_
protected

Definition at line 229 of file logger.h.

◆ current_level_

uint8_t esphome::logger::Logger::current_level_ {ESPHOME_LOG_LEVEL_VERY_VERBOSE}
protected

Definition at line 258 of file logger.h.

◆ global_recursion_guard_

bool esphome::logger::Logger::global_recursion_guard_ {false}
protected

Definition at line 268 of file logger.h.

◆ hw_serial_

Stream* esphome::logger::Logger::hw_serial_ {nullptr}
protected

Definition at line 232 of file logger.h.

◆ level_callback_

CallbackManager<void(uint8_t)> esphome::logger::Logger::level_callback_ {}
protected

Definition at line 250 of file logger.h.

◆ log_buffer_

std::unique_ptr<logger::TaskLogBuffer> esphome::logger::Logger::log_buffer_
protected

Definition at line 252 of file logger.h.

◆ log_callback_

CallbackManager<void(uint8_t, const char *, const char *, size_t)> esphome::logger::Logger::log_callback_ {}
protected

Definition at line 249 of file logger.h.

◆ log_levels_

std::map<std::string, uint8_t> esphome::logger::Logger::log_levels_ {}
protected

Definition at line 248 of file logger.h.

◆ log_recursion_key_

pthread_key_t esphome::logger::Logger::log_recursion_key_
protected

Definition at line 241 of file logger.h.

◆ main_task_

void* esphome::logger::Logger::main_task_ = nullptr
protected

Definition at line 235 of file logger.h.

◆ main_task_recursion_guard_

bool esphome::logger::Logger::main_task_recursion_guard_ {false}
protected

Definition at line 266 of file logger.h.

◆ tx_buffer_

char* esphome::logger::Logger::tx_buffer_ {nullptr}
protected

Definition at line 230 of file logger.h.

◆ tx_buffer_at_

uint16_t esphome::logger::Logger::tx_buffer_at_ {0}
protected

Definition at line 256 of file logger.h.

◆ tx_buffer_size_

uint16_t esphome::logger::Logger::tx_buffer_size_ {0}
protected

Definition at line 257 of file logger.h.

◆ uart_

UARTSelection esphome::logger::Logger::uart_ {UART_SELECTION_UART0}
protected

Definition at line 260 of file logger.h.

◆ uart_num_

uart_port_t esphome::logger::Logger::uart_num_
protected

Definition at line 244 of file logger.h.


The documentation for this class was generated from the following files: