企业官网建设流程全解析

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。步骤如下：

1. 进入Settings>Automations & scenes。
2. 打开一个现有的自动化或脚本；新建的话选择Create automation>Create new automation。
3. 如果是新建自动化，先在When部分添加一个触发器；脚本则不需要触发器，它们在被其他东西调用时才运行。
4. 在Then do部分选择Add action。
5. 在动作列表中搜索并选择Logger: Set logger level。
6. 选择Edit in YAML，填入一个或多个 logger 名称及对应的级别。
7. 选择Save保存。

UI 中的选项

该动作没有固定的选项字段：你提供的是一个或多个 logger 名称，每个名称对应一个要设置的级别。因此在 UI 中是以自由键值对的形式录入的，而非固定的下拉选择。

在 YAML 中使用：语法与完整示例

在 YAML 中，动作名写作logger.set_level，data下直接放置“logger 名称 → 级别”的映射。官方文档给出的完整示例如下：

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

Options 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），可以总结出以下定位方法：

1. 命名空间的层次结构：logger 名称跟随 Python 模块路径。顶层 Core 命名空间是homeassistant.core；某个集成的完整命名空间是homeassistant.components.<domain>；还可以继续细化到子模块，例如示例中的homeassistant.components.smartthings.light只针对 SmartThings 的灯光实体部分。
2. 从启动日志反查：如果你不确定自己环境里的确切命名空间，直接查看启动时的日志。启动过程中homeassistant.loader会输出类似loaded <component> from <namespace>的 INFO 消息，那些namespace就是你可以针对其设置日志级别的候选。
3. 注意同名不同源的命名空间：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

4. 精确到单个脚本：命名空间甚至可以细化到具体文件。比如 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 方式：进入Settings>System>Logs，选择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_FILE=1，则不再生成该文件，UI 中的Show raw logs与下载功能也不可用。

与其他动作的关系

logger.set_level的官方关联动作为 Set logger default level（logger.set_default_level），二者互补：

• logger.set_default_level：为没有单独设置级别的集成设定全局默认级别，同样要求管理员权限，YAML 中通过level字段传入一个值（如info），示例：action: logger.set_default_level+data: { level: info }。
• logger.set_level：为指定的一个或多个集成单独设置级别，粒度更细。

排障时两者常配合使用：先用logger.set_default_level把整体输出调低以减少干扰，再用logger.set_level对目标集成单独放大细节。

小结

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