Home Assistant Logger 集成动作详解：用 logger.set_default_level 统一掌控默认日志级别-育师

Home Assistant Logger 集成动作详解：用 logger.set_default_level 统一掌控默认日志级别

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

logger.set_default_level是 Home Assistant Logger 系统集成提供的一个内置动作（action），用于为所有未单独设置日志级别的集成统一指定默认的日志详细程度。本文基于本仓库中该动作的官方参考文档（logger.set_default_level 动作文档）与 Logger 集成文档（logger 集成文档），完整讲解该动作的 UI 操作、YAML 写法、参数取值，并延伸说明它与logger.set_level、configuration.yaml中logger:配置的关系，帮助你按需调整 Home Assistant 全局日志的详略程度。

动作是什么

logger.set_default_level动作用于设置默认日志级别。这个级别只对没有自己专属日志级别的集成生效，即作为全局兜底级别。当你想横跨所有集成统一调整日志的详细程度时（例如在排查问题时把整体日志提升到 debug 级别以观察更多细节，或平时把日志收紧到更安静的级别），这个动作是最直接的入口。

需要注意的权限限制：只有拥有管理员权限的用户才能执行此动作。

每次日志条目的标准形态为：

[timestamp] [level] [thread] [namespace] [message]

其中[level]对应的就是该动作可以控制的严重级别。

在 UI 中设置默认日志级别

根据文档说明，从自动化（automation）或脚本（script）中设置默认日志级别的步骤为：

进入Settings>Automations & scenes。
打开一个已有的自动化或脚本；如果是新建，选择Create automation>Create new automation。
新建自动化时，需要在When（触发条件）区域添加一个触发器；脚本不需要触发器，脚本在被其他对象调用时执行。
在Then do（执行动作）区域选择Add action。
从动作列表中搜索并选择Logger: Set logger default level。
设置你想要作为默认值的Level。
点击Save保存。

这种可视化方式无需掌握 YAML，Home Assistant 会引导你逐步完成目标选择与选项设置。

在 YAML 中引用该动作

在 YAML 中，该动作的名称是logger.set_default_level。一个最基本的示例如下：

action: logger.set_default_level data: level: info

YAML 参数说明

字段	说明	必填	类型
`level`	未单独设置级别的集成所使用的默认严重级别，取值为：`debug`、`info`、`warning`、`error`、`fatal`、`critical`	是	string

从源码文档看，该动作在 UI 中的选项与 YAML 字段完全对应，均只包含level一个字段。

级别取值的含义与顺序

Logger 集成的官方文档给出了完整的日志严重级别列表，按从最严重到最不严重的顺序排列为：

critical
fatal
error
warning
warn（warning的同义别名）
info
debug
notset

关键行为：所有低于指定级别的消息都会被日志系统忽略。也就是说，把默认级别设为error后，warning、info、debug级别的消息不会出现在日志中；设为debug则会看到尽可能多的细节。该动作接受的前缀取值（debug、info、warning、error、fatal、critical）正是这个列表的子集。

另外，如果configuration.yaml中没有启用 logger 集成，Home Assistant 的标准日志严重级别为warning。

与 logger.set_level 的分工

默认级别只作用于没有单独设置级别的集成。要为一个或多个特定集成单独设置级别，应使用配套动作Set logger level（logger.set_level），其文档位于 logger.set_level 动作文档。

两者的区别可以概括为：

logger.set_default_level：全局兜底，影响所有未单独配置的集成，适合整体性调节（如整体调高到 debug 排查问题）。
logger.set_level：精准定点，只为指定的一个或多个日志命名空间设置级别，不会让其余日志变得嘈杂，适合只排查单个集成的问题。

logger.set_level的 YAML 写法是"日志名: 级别"的映射形式，例如：

action: logger.set_level data: homeassistant.core: fatal homeassistant.components.mqtt: warning homeassistant.components.smartthings.light: info custom_components.my_integration: debug aiohttp: error

其中日志名遵循模块路径规则：集成用homeassistant.components.xxx形式，自定义集成用custom_components.xxx，第三方 Python 库直接用库名（如aiohttp）。

重要注意事项：无论是logger.set_default_level还是logger.set_level，通过动作设置的级别在重启 Home Assistant 后都会重置，除非你在configuration.yaml的logger:配置中固化这些设置。

持久化配置：在 configuration.yaml 中固化级别

动作设置的级别是临时的（重启即失效）。要长期生效，应在configuration.yaml中启用并配置 logger 集成，相关说明见 logger 集成文档。

最小启用方式：

# Example configuration.yaml entry logger:

完整配置参考如下：

配置键	说明	必填	类型
`default`	默认日志级别，参见日志级别列表	否	string
`logs`	各集成及其日志级别的映射表	否	map
`filters`	正则表达式日志过滤器	否	map

一个覆盖默认级别与单个集成级别的典型配置：

logger: default: critical logs: # Log level for Home Assistant Core homeassistant.core: fatal # Log level for MQTT integration homeassistant.components.mqtt: warning # Log level for all python scripts homeassistant.components.python_script: warning # Individual log level for this python script homeassistant.components.python_script.my_new_script.py: debug # Log level for SmartThings lights homeassistant.components.smartthings.light: info # Log level for a custom integration custom_components.my_integration: debug # Log level for the `aiohttp` Python package aiohttp: error # Log level for both 'glances_api' and 'glances' integration homeassistant.components.glances: fatal glances_api: fatal

从该示例可以看出，不同命名空间可能对应同一组件但由不同的 API 记录日志：例如glances_api与homeassistant.components.glances都是根级命名空间，却由不同 API 输出日志。如果你想知道自己环境中有哪些可用命名空间，可以查看启动时的日志：homeassistant.loader会输出形如loaded <component> from <namespace>的 INFO 消息，其中的命名空间就是你可以针对设置日志级别的对象。

正则过滤器：进一步屏蔽噪音

除了设置级别，logger 集成还支持按正则表达式过滤日志消息：消息一旦匹配正则表达式就会被省略。例如：

logger: default: info filters: # Filters out all entries containing "unable to connect" system wide "": - "unable to connect" # Filters out all "HTTP 429" errors for my_integration custom_components.my_integration: - "HTTP 429"

上述配置把默认级别设为info，同时系统级过滤掉所有包含 "unable to connect" 的日志，并对custom_components.my_integration命名空间过滤掉 "HTTP 429" 相关消息。空字符串命名空间表示系统级过滤。该过滤语法遵循 Python 的re模块规范。

查看日志结果

设置日志级别后，可以通过以下途径查看效果：

UI 方式（推荐）：进入Settings>System>Logs，选择Home Assistant Core。页面顶部的Show raw logs开关可查看未经格式化的完整日志输出，也可以从该页面下载日志文件。
Home Assistant OS：日志不写入配置目录中的文件，应使用 UI 方式，或在 SSH 应用中运行ha core logs --follow实时跟踪。
Home Assistant Container：日志也会写入配置目录下的home-assistant.log文件，可用docker logs --follow MY_CONTAINER_ID或tail -f /config/home-assistant.log动态查看。若设置环境变量HA_DISABLE_LOG_FILE为1（或true），则 Home Assistant 不再写home-assistant.log，此时/config/home-assistant.log不可用，UI 中的Show raw logs与日志下载功能也会随之失效。

实用场景小结

整体排查问题：临时执行logger.set_default_level并把level设为debug，观察所有集成的详细日志；排查结束后再执行一次，恢复为info或warning。
单独调试某个集成：使用logger.set_level只对homeassistant.components.xxx或custom_components.xxx设置debug，避免日志全局刷屏。
长期生效：将默认级别与个别级别写入configuration.yaml的logger:配置块，配合filters正则过滤持续抑制噪音。
恢复出厂行为：不启用 logger 集成时，系统标准日志级别为warning。