Home Assistant logger.set_level 动作完全指南按集成精准调校日志级别【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文围绕 Home Assistant 的logger.set_level动作展开讲解如何在运行时按需将**某一个或某几个集成integration**的日志级别单独调高或调低——例如在排查问题时只把目标集成提升到debug而不让整份日志被无关信息淹没。读完本文你将掌握该动作在 UI 与 YAML 中的完整用法、日志命名空间的定位方法以及它与logger.set_default_level、configuration.yaml中logger:配置的关系。动作概述为什么需要它Home Assistant 内置的Logger集成集成文档负责日志级别与过滤规则的统一管理。每条日志记录形如[timestamp] [level] [thread] [namespace] [message]其中namespace就是动作的“目标地址”。logger.set_level正是针对这一命名空间维度做定向调整把某一个集成的级别临时提上去、把另一个降下来互不影响。相比修改configuration.yaml后重启这个动作可以在不重启的情况下实时生效非常适合在线排查问题。需要注意一个重要前提只有拥有管理员权限administrator的用户才能调用此动作。这一点在该动作的官方文档中明确标注并且从核心版本更新记录source/changelogs/core-2026.5.markdown“Require admin forlogger.set_levelandlogger.set_default_levelservices”这一变更可以看出管理员权限限制是刻意设计的约束。在 UI 中调用从自动化或脚本触发如果你更习惯用可视化方式构建自动化Home Assistant 会引导你一步步完成动作配置无需编写 YAML。步骤如下进入SettingsAutomations scenes。打开一个现有的自动化或脚本新建的话选择Create automationCreate new automation。如果是新建自动化先在When部分添加一个触发器脚本则不需要触发器它们在被其他东西调用时才运行。在Then do部分选择Add action。在动作列表中搜索并选择Logger: Set logger level。选择Edit in YAML填入一个或多个 logger 名称及对应的级别。选择Save保存。UI 中的选项该动作没有固定的选项字段你提供的是一个或多个 logger 名称每个名称对应一个要设置的级别。因此在 UI 中是以自由键值对的形式录入的而非固定的下拉选择。在 YAML 中使用语法与完整示例在 YAML 中动作名写作logger.set_leveldata下直接放置“logger 名称 → 级别”的映射。官方文档给出的完整示例如下action: logger.set_level data: homeassistant.core: fatal homeassistant.components.mqtt: warning homeassistant.components.smartthings.light: info custom_components.my_integration: debug aiohttp: errorOptions in YAML两个关键字段该动作在 YAML 中没有固定选项取而代之的是若干条目其中每个键是一个 logger 名称每个值是要为该 logger 设置的级别logger 名称遵循模块路径module path。例如集成用homeassistant.components.mqtt这样的形式自定义集成用custom_components.my_integration第三方库直接写库名如aiohttp。级别level取值为debug、info、warning、error、fatal、critical之一。深入如何定位正确的 logger 名称这是使用本动作时最核心的实操问题——名字写错了级别自然调不上去。综合动作文档与 Logger 集成文档source/_integrations/logger.markdown可以总结出以下定位方法命名空间的层次结构logger 名称跟随 Python 模块路径。顶层 Core 命名空间是homeassistant.core某个集成的完整命名空间是homeassistant.components.domain还可以继续细化到子模块例如示例中的homeassistant.components.smartthings.light只针对 SmartThings 的灯光实体部分。从启动日志反查如果你不确定自己环境里的确切命名空间直接查看启动时的日志。启动过程中homeassistant.loader会输出类似loaded component from namespace的 INFO 消息那些namespace就是你可以针对其设置日志级别的候选。注意同名不同源的命名空间Logger 集成文档特别提醒了glances_api与homeassistant.components.glances的区别——二者都是根级root命名空间但背后是两套不同的 API日志输出来源不同需要分别设置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 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精确到单个脚本命名空间甚至可以细化到具体文件。比如 Logger 集成文档中的示例homeassistant.components.python_script.my_new_script.py: debug即为某个具体的 Python 脚本单独打开调试级别。提示以上示例中homeassistant.components.python_script.my_new_script.py这类粒度在实际使用时需要你的环境中确实存在对应文件路径才能命中。级别取值与生效规则logger.set_level动作支持的级别为debug、info、warning、error、fatal、critical。它与 Logger 集成文档中列举的完整级别体系critical、fatal、error、warning、warn、info、debug、notset保持同源——动作文档只对外暴露最常用的一档。级别按严重程度从高到低排列所有低于所设级别的消息都会被忽略例如设为warning则debug、info级别的记录不会输出。与默认级别的关系两条要点决定了这个动作的使用边界动作设置的是“叠加层”你通过logger.set_level设置的级别是叠加在默认级别之上的。若要改变“没有单独设置级别的集成”的全局默认值请改用 Set logger default level 动作或参考下面的configuration.yaml方案。重启即失效通过动作设置的级别会在 Home Assistant 重启后重置除非你把它们固化在配置文件中。这意味着logger.set_level适合即时、临时的排障场景如果需要长期、持久化的级别控制应在configuration.yaml中配置logger:段例如logger: default: warning logs: homeassistant.components.mqtt: debug custom_components.my_integration: info关于logger:配置的完整字段包括default、logs与正则filters参见 Logger 集成文档。实战示例在自动化中定位 MQTT 连接问题把上面的知识串起来一个典型的排障自动化长这样当检测到某个事件触发器时把 MQTT 集成临时切到debug级别同时把第三方库aiohttp压到error避免刷屏alias: Debug MQTT for 10 minutes trigger: - platform: time at: 14:00:00 action: - action: logger.set_level data: homeassistant.components.mqtt: debug aiohttp: error mode: single运行后打开日志界面即可看到 MQTT 的详细输出。排查完成后再调用一次动作把级别恢复原状或者直接重启 Home Assistant 让所有临时级别复位。如何查看调整后的日志UI 方式进入SettingsSystemLogs选择Home Assistant Core可开启Show raw logs查看完整未格式化输出也可以从该页面下载日志文件详见 Logger 集成文档。Home Assistant OS日志不写入配置目录的文件可通过 SSH 插件执行ha core logs --follow见 OS 常见任务。Container 安装日志会写入配置目录下的home-assistant.log可docker logs --follow 容器ID或tail -f /config/home-assistant.log动态跟踪若设置了HA_DISABLE_LOG_FILE1则不再生成该文件UI 中的Show raw logs与下载功能也不可用。与其他动作的关系logger.set_level的官方关联动作为 Set logger default levellogger.set_default_level二者互补logger.set_default_level为没有单独设置级别的集成设定全局默认级别同样要求管理员权限YAML 中通过level字段传入一个值如info示例action: logger.set_default_leveldata: { level: info }。logger.set_level为指定的一个或多个集成单独设置级别粒度更细。排障时两者常配合使用先用logger.set_default_level把整体输出调低以减少干扰再用logger.set_level对目标集成单独放大细节。小结场景推荐做法临时排查单个集成自动化中调用logger.set_level针对性调高该集成级别全局临时调整输出量调用logger.set_default_level长期固定级别策略在configuration.yaml的logger:段配置logs映射忘记命名空间看启动日志中loaded component from namespace的 INFO 消息恢复原状重启 Home Assistant动作设置的级别重启后自动复位logger.set_level是 Home Assistant 日志排障工具箱里最趁手的“手术刀”只切目标、不伤全局配合logger.set_default_level与configuration.yaml持久化配置即可在即时性与长期策略之间自由切换。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考