Logger component for all ESPHome logging. More...

#include <logger.h>

Inheritance diagram for esphome::logger::Logger:

Data Structures
class	NonMainTaskRecursionGuard

class	RecursionGuard

Public Member Functions
	Logger (uint32_t baud_rate)

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	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 char *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_log_callback (void instance, void(fn)(void , uint8_t, const char , const char *, size_t))
	Register a log callback to receive log messages.

void	add_log_callback (void instance, void(fn)(void , uint8_t, const char , const char *, size_t))
	No-op when log listeners are disabled.

void	add_level_listener (LoggerLevelListener *listener)
	Register a listener for log level changes.

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)

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.

bool	is_idle () const
	Check if this component is idle.

void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const LogString *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 ()

void	status_set_warning (const char *message)

void	status_set_warning (const LogString *message)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

void	status_momentary_warning (const char *name, uint32_t length=5000)
	Set warning status flag and automatically clear it after a timeout.

void	status_momentary_error (const char *name, uint32_t length=5000)
	Set error status flag and automatically clear it after a timeout.

bool	has_overridden_loop () const

const LogString *	get_component_log_str () const ESPHOME_ALWAYS_INLINE
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)

Protected Member Functions
void	log_vprintf_non_main_thread_ (uint8_t level, const char tag, int line, const char format, va_list args, const char *thread_name)

void	cdc_loop_ ()

void	process_messages_ ()

void	write_msg_ (const char *msg, uint16_t len)

void	write_msg_ (const char *msg, uint16_t len)

void HOT	format_log_to_buffer_with_terminator_ (uint8_t level, const char tag, int line, const char format, va_list args, LogBuffer &buf, const char *thread_name)

void HOT	format_log_to_buffer_with_terminator_P_ (uint8_t level, const char tag, int line, const __FlashStringHelper format, va_list args, LogBuffer &buf)

void HOT	notify_listeners_ (uint8_t level, const char *tag, const LogBuffer &buf)

void HOT	write_to_console_ (LogBuffer &buf)

void HOT	write_log_buffer_to_console_ (LogBuffer &buf)

template<typename FormatType >
void HOT	log_message_to_buffer_and_send_ (bool &recursion_guard, uint8_t level, const char tag, int line, FormatType format, va_list args, const char thread_name)

void HOT	format_buffered_message_and_notify_ (uint8_t level, const char tag, uint16_t line, const char thread_name, const char *text, uint16_t text_length, LogBuffer &buf)

const LogString *	get_uart_selection_ ()

void	dump_crash_ ()

const char *	get_thread_name_ (TaskHandle_t task)

const char *HOT	get_thread_name_ ()

const char *HOT	get_thread_name_ (std::span< char > buff)

const char *HOT	get_thread_name_ (std::span< char > buff, k_tid_t current_task=nullptr)

bool HOT	is_non_main_task_recursive_ () const

NonMainTaskRecursionGuard	make_non_main_task_guard_ ()

bool HOT	is_non_main_task_recursive_ () const

RecursionGuard	make_non_main_task_guard_ ()

void	disable_loop_when_buffer_empty_ ()

Protected Member Functions inherited from esphome::Component
friend	void::setup ()

friend	void::original_setup ()

void	set_component_source_ (uint8_t index)
	Set where this component was loaded from for some debug messages.

virtual void	call_setup ()

void	call_dump_config_ ()

void	enable_loop_slow_path_ ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

bool	set_status_flag_ (uint8_t flag)
	Helper to set a status LED flag on both this component and the app.

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 id, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a numeric ID (zero heap allocation).

void	set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const char *name)
	Cancel an interval function.

bool	cancel_interval (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

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 id, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a numeric ID (zero heap allocation).

void	set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const char *name)
	Cancel a timeout function.

bool	cancel_timeout (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

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.

void	defer (uint32_t id, std::function< void()> &&f)
	Defer a callback with a numeric ID (zero heap allocation)

bool	cancel_defer (const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

bool	cancel_defer (uint32_t id)

void	status_clear_warning_slow_path_ ()

void	status_clear_error_slow_path_ ()

Protected Attributes
uint32_t	baud_rate_

Stream *	hw_serial_ {nullptr}

const device *	uart_dev_ {nullptr}

void *	main_task_ {nullptr}

pthread_t	main_thread_ {}

pthread_key_t	log_recursion_key_

uart_port_t	uart_num_

std::map< const char *, uint8_t, CStrCompare >	log_levels_ {}

StaticVector< LogCallback, ESPHOME_LOG_MAX_LISTENERS >	log_callbacks_

std::vector< LoggerLevelListener * >	level_listeners_

uint8_t	current_level_ {ESPHOME_LOG_LEVEL_VERY_VERBOSE}

UARTSelection	uart_ {UART_SELECTION_UART0}

bool	main_task_recursion_guard_ {false}

bool	non_main_task_recursion_guard_ {false}

bool	global_recursion_guard_ {false}

char	tx_buffer_ [ESPHOME_LOGGER_TX_BUFFER_SIZE+1]

logger::TaskLogBuffer	log_buffer_

Protected Attributes inherited from esphome::Component
uint8_t	component_source_index_ {0}
	Index into component source PROGMEM lookup table (0 = not set)

uint8_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
	Warn threshold in centiseconds (max 2550ms)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

ComponentRuntimeStats	runtime_stats_

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:

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

Definition at line 144 of file logger.h.

Constructor & Destructor Documentation

◆ Logger()

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

explicit

Definition at line 155 of file logger.cpp.

Member Function Documentation

◆ add_level_listener()

void esphome::logger::Logger::add_level_listener ( LoggerLevelListener * listener )

inline

Register a listener for log level changes.

Definition at line 197 of file logger.h.

◆ add_log_callback() [1/2]

void esphome::logger::Logger::add_log_callback	(	void *	instance,
		void(*	fn )(void , uint8_t, const char , const char *, size_t) )

inline

Register a log callback to receive log messages.

Definition at line 187 of file logger.h.

◆ add_log_callback() [2/2]

void esphome::logger::Logger::add_log_callback	(	void *	instance,
		void(*	fn )(void , uint8_t, const char , const char *, size_t) )

inline

No-op when log listeners are disabled.

Definition at line 192 of file logger.h.

◆ cdc_loop_()

void esphome::logger::Logger::cdc_loop_ ( )

protected

Definition at line 36 of file logger_zephyr.cpp.

◆ create_pthread_key() [1/2]

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

inline

Definition at line 158 of file logger.h.

◆ create_pthread_key() [2/2]

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

inline

Definition at line 161 of file logger.h.

◆ disable_loop_when_buffer_empty_()

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

inlineprotected

Definition at line 472 of file logger.h.

◆ dump_config()

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

overridevirtual

Reimplemented from esphome::Component.

Definition at line 222 of file logger.cpp.

◆ dump_crash_()

void esphome::logger::Logger::dump_crash_ ( )

protected

Definition at line 151 of file logger_zephyr.cpp.

◆ format_buffered_message_and_notify_()

void HOT esphome::logger::Logger::format_buffered_message_and_notify_	(	uint8_t	level,
		const char *	tag,
		uint16_t	line,
		const char *	thread_name,
		const char *	text,
		uint16_t	text_length,
		LogBuffer &	buf )

inlineprotected

Definition at line 301 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,
		LogBuffer &	buf,
		const char *	thread_name )

inlineprotected

Definition at line 241 of file logger.h.

◆ format_log_to_buffer_with_terminator_P_()

void HOT esphome::logger::Logger::format_log_to_buffer_with_terminator_P_	(	uint8_t	level,
		const char *	tag,
		int	line,
		const __FlashStringHelper *	format,
		va_list	args,
		LogBuffer &	buf )

inlineprotected

Definition at line 250 of file logger.h.

◆ get_baud_rate()

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

inline

Definition at line 152 of file logger.h.

◆ get_hw_serial()

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

inline

Definition at line 154 of file logger.h.

◆ get_log_level()

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

inline

Definition at line 175 of file logger.h.

◆ get_setup_priority()

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

overridevirtual

Reimplemented from esphome::Component.

Definition at line 213 of file logger.cpp.

◆ get_thread_name_() [1/4]

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

inlineprotected

Definition at line 392 of file logger.h.

◆ get_thread_name_() [2/4]

const char *HOT esphome::logger::Logger::get_thread_name_ ( std::span< char > buff )

inlineprotected

Definition at line 396 of file logger.h.

◆ get_thread_name_() [3/4]

const char *HOT esphome::logger::Logger::get_thread_name_	(	std::span< char >	buff,
		k_tid_t	current_task = nullptr )

inlineprotected

Definition at line 409 of file logger.h.

◆ get_thread_name_() [4/4]

const char * esphome::logger::Logger::get_thread_name_ ( TaskHandle_t task )

inlineprotected

Definition at line 380 of file logger.h.

◆ get_uart()

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

Get the UART used by the logger.

Definition at line 210 of file logger.cpp.

◆ get_uart_num()

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

inline

Definition at line 157 of file logger.h.

◆ get_uart_selection_()

const LogString * esphome::logger::Logger::get_uart_selection_ ( )

protected

Definition at line 128 of file logger_esp32.cpp.

◆ is_non_main_task_recursive_() [1/2]

bool HOT esphome::logger::Logger::is_non_main_task_recursive_ ( ) const

inlineprotected

Definition at line 446 of file logger.h.

◆ is_non_main_task_recursive_() [2/2]

bool HOT esphome::logger::Logger::is_non_main_task_recursive_ ( ) const

inlineprotected

Definition at line 463 of file logger.h.

◆ level_for()

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

inline

Definition at line 146 of file logger.cpp.

◆ log_message_to_buffer_and_send_()

template<typename FormatType >

void HOT esphome::logger::Logger::log_message_to_buffer_and_send_	(	bool &	recursion_guard,
		uint8_t	level,
		const char *	tag,
		int	line,
		FormatType	format,
		va_list	args,
		const char *	thread_name )

inlineprotected

Definition at line 282 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 137 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 26 of file logger.cpp.

◆ log_vprintf_non_main_thread_()

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

protected

Definition at line 72 of file logger.cpp.

◆ loop()

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

overridevirtual

Reimplemented from esphome::Component.

Definition at line 166 of file logger.cpp.

◆ make_non_main_task_guard_() [1/2]

NonMainTaskRecursionGuard esphome::logger::Logger::make_non_main_task_guard_ ( )

inlineprotected

Definition at line 449 of file logger.h.

◆ make_non_main_task_guard_() [2/2]

RecursionGuard esphome::logger::Logger::make_non_main_task_guard_ ( )

inlineprotected

Definition at line 466 of file logger.h.

◆ notify_listeners_()

void HOT esphome::logger::Logger::notify_listeners_	(	uint8_t	level,
		const char *	tag,
		const LogBuffer &	buf )

inlineprotected

Definition at line 259 of file logger.h.

◆ pre_setup()

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

Set up this component.

Definition at line 87 of file logger_esp32.cpp.

◆ process_messages_()

void esphome::logger::Logger::process_messages_ ( )

protected

Definition at line 174 of file logger.cpp.

◆ 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 204 of file logger.cpp.

◆ set_log_level() [1/2]

void esphome::logger::Logger::set_log_level	(	const char *	tag,
		uint8_t	log_level )

Set the log level of the specified tag.

Definition at line 206 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 266 of file logger.cpp.

◆ set_uart_selection()

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

inline

Definition at line 164 of file logger.h.

◆ write_log_buffer_to_console_()

void HOT esphome::logger::Logger::write_log_buffer_to_console_ ( LogBuffer & buf )

inlineprotected

Definition at line 273 of file logger.h.

◆ write_msg_() [1/2]

void HOT esphome::logger::Logger::write_msg_	(	const char *	msg,
		uint16_t	len )

inlineprotected

Definition at line 9 of file logger_esp32.h.

◆ write_msg_() [2/2]

void esphome::logger::Logger::write_msg_	(	const char *	msg,
		uint16_t	len )

inlineprotected

◆ write_to_console_()

void HOT esphome::logger::Logger::write_to_console_ ( LogBuffer & buf )

inlineprotected

Definition at line 267 of file logger.h.

Field Documentation

◆ baud_rate_

uint32_t esphome::logger::Logger::baud_rate_

protected

Definition at line 315 of file logger.h.

◆ current_level_

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

protected

Definition at line 353 of file logger.h.

◆ global_recursion_guard_

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

protected

Definition at line 366 of file logger.h.

◆ hw_serial_

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

protected

Definition at line 317 of file logger.h.

◆ level_listeners_

std::vector<LoggerLevelListener *> esphome::logger::Logger::level_listeners_

protected

Definition at line 350 of file logger.h.

◆ log_buffer_

logger::TaskLogBuffer esphome::logger::Logger::log_buffer_

protected

Definition at line 372 of file logger.h.

◆ log_callbacks_

StaticVector<LogCallback, ESPHOME_LOG_MAX_LISTENERS> esphome::logger::Logger::log_callbacks_

protected

Definition at line 347 of file logger.h.

◆ log_levels_

std::map<const char *, uint8_t, CStrCompare> esphome::logger::Logger::log_levels_ {}

protected

Definition at line 343 of file logger.h.

◆ log_recursion_key_

pthread_key_t esphome::logger::Logger::log_recursion_key_

protected

Definition at line 333 of file logger.h.

◆ main_task_

void* esphome::logger::Logger::main_task_ {nullptr}

protected

Definition at line 324 of file logger.h.

◆ main_task_recursion_guard_

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

protected

Definition at line 361 of file logger.h.

◆ main_thread_

pthread_t esphome::logger::Logger::main_thread_ {}

protected

Definition at line 327 of file logger.h.

◆ non_main_task_recursion_guard_

bool esphome::logger::Logger::non_main_task_recursion_guard_ {false}

protected

Definition at line 363 of file logger.h.

◆ tx_buffer_

char esphome::logger::Logger::tx_buffer_[ESPHOME_LOGGER_TX_BUFFER_SIZE+1]

protected

Definition at line 370 of file logger.h.

◆ uart_

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

protected

Definition at line 355 of file logger.h.

◆ uart_dev_

const device* esphome::logger::Logger::uart_dev_ {nullptr}

protected

Definition at line 321 of file logger.h.

◆ uart_num_

uart_port_t esphome::logger::Logger::uart_num_

protected

Definition at line 334 of file logger.h.

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

esphome/components/logger/logger.h
esphome/components/logger/logger.cpp
esphome/components/logger/logger_esp32.cpp
esphome/components/logger/logger_esp32.h
esphome/components/logger/logger_esp8266.cpp
esphome/components/logger/logger_esp8266.h
esphome/components/logger/logger_host.cpp
esphome/components/logger/logger_libretiny.cpp
esphome/components/logger/logger_libretiny.h
esphome/components/logger/logger_rp2.cpp
esphome/components/logger/logger_rp2.h
esphome/components/logger/logger_zephyr.cpp

Data Structures

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Logger()

Member Function Documentation

◆ add_level_listener()

◆ add_log_callback() [1/2]

◆ add_log_callback() [2/2]

◆ cdc_loop_()

◆ create_pthread_key() [1/2]

◆ create_pthread_key() [2/2]

◆ disable_loop_when_buffer_empty_()

◆ dump_config()

◆ dump_crash_()

◆ format_buffered_message_and_notify_()

◆ format_log_to_buffer_with_terminator_()

◆ format_log_to_buffer_with_terminator_P_()

◆ get_baud_rate()

◆ get_hw_serial()

◆ get_log_level()

◆ get_setup_priority()

◆ get_thread_name_() [1/4]

◆ get_thread_name_() [2/4]

◆ get_thread_name_() [3/4]

◆ get_thread_name_() [4/4]

◆ get_uart()

◆ get_uart_num()

◆ get_uart_selection_()

◆ is_non_main_task_recursive_() [1/2]

◆ is_non_main_task_recursive_() [2/2]

◆ level_for()

◆ log_message_to_buffer_and_send_()

◆ log_vprintf_() [1/2]

◆ log_vprintf_() [2/2]

◆ log_vprintf_non_main_thread_()

◆ loop()

◆ make_non_main_task_guard_() [1/2]

◆ make_non_main_task_guard_() [2/2]

◆ notify_listeners_()

◆ pre_setup()

◆ process_messages_()

◆ set_baud_rate()

◆ set_log_level() [1/2]

◆ set_log_level() [2/2]

◆ set_uart_selection()

◆ write_log_buffer_to_console_()

◆ write_msg_() [1/2]

◆ write_msg_() [2/2]

◆ write_to_console_()

Field Documentation

◆ baud_rate_

◆ current_level_

◆ global_recursion_guard_

◆ hw_serial_

◆ level_listeners_

◆ log_buffer_

◆ log_callbacks_

◆ log_levels_

◆ log_recursion_key_

◆ main_task_

◆ main_task_recursion_guard_

◆ main_thread_

◆ non_main_task_recursion_guard_

◆ tx_buffer_

◆ uart_

◆ uart_dev_

◆ uart_num_