2025.3.4
首页 ▸ Integrations ▸

日志记录器

logger 集成允许你定义 Home Assistant 中日志记录活动的级别。

要在你的安装中启用 logger 集成，请将以下内容添加到你的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中：

# 示例 configuration.yaml 条目
logger:

如果在 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 中未启用日志记录器集成，则日志严重性级别为 warning。

要记录所有消息并忽略指定集成中低于危急的事件：

# 示例 configuration.yaml 条目
logger:
  default: info
  logs:
    homeassistant.components.yamaha: critical
    custom_components.my_integration: critical

要忽略所有低于危急的消息并记录指定集成的事件：

# 示例 configuration.yaml 条目
logger:
  default: critical
  logs:
    # HA 核心的日志级别
    homeassistant.core: fatal

    # MQTT 集成的日志级别
    homeassistant.components.mqtt: warning

    # 所有 Python 脚本的日志级别
    homeassistant.components.python_script: warning

    # 此 Python 脚本的单独日志级别
    homeassistant.components.python_script.my_new_script.py: debug

    # SmartThings 灯的日志级别
    homeassistant.components.smartthings.light: info

    # 自定义集成的日志级别
    custom_components.my_integration: debug

    # `aiohttp` Python 包的日志级别
    aiohttp: error

    # 'glances_api' 和 'glances' 集成的日志级别
    homeassistant.components.glances: fatal
    glances_api: fatal

日志条目格式如下
时间戳 日志级别 线程 [命名空间] 消息
其中 命名空间 是当前记录日志的 <component_namespace>。

Configuration Variables

Looking for your configuration file?
default string (Optional)

默认日志级别。参见 log_level。

logs map (Optional)

集成及其日志级别的列表。

<component_namespace> string

集成的日志记录命名空间。参见 log_level。

filters map (Optional)

正则表达式日志过滤器。

<component_namespace> list

集成的日志记录命名空间以及正则表达式列表。参见 Log Filters。

在示例中，请注意 ‘glances_api’ 和 ‘homeassistant.components.glances’ 命名空间之间的区别， 它们均处于根级别。它们由不同的 API 记录。

如果你想知道在你自己的环境中有哪些命名空间，则检查启动时的日志文件。 你将看到来自 homeassistant.loader 的 INFO 日志消息，内容为 loaded <component> from <namespace>。 这些是你可以设置 log level 的可用命名空间。

日志级别

可能的日志严重性级别，按从最严重到最轻微的顺序列出，有：

  • critical
  • fatal
  • error
  • warning
  • warn
  • info
  • debug
  • notset

日志过滤器

服务特定的正则表达式日志过滤器。如果消息与正则表达式匹配，则会被忽略。

示例配置可能如下所示：

# 示例 configuration.yaml 条目
logger:
  default: info
  logs:
    custom_components.my_integration: critical
  filters:
    custom_components.my_integration:
      - "HTTP 429" # 过滤所有 HTTP 429 错误
      - "Request to .*unreliable.com.* Timed Out"
    homeassistant.components.nws:
      - "^Error handling request$"

操作

操作 set_default_level

你可以使用 logger.set_default_level 操作更改默认日志级别（对于没有指定日志级别的集成）。

示例调用可能如下所示：

action: logger.set_default_level
data:
  level: info

操作 set_level

你可以使用 logger.set_level 操作更改一个或多个集成的日志级别。 它接受与配置中 logs 相同的格式。

示例调用可能如下所示：

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

查看日志

日志信息存储在 配置目录 中，文件名为 home-assistant.log 你可以使用命令行工具 cat 读取它，或使用 tail -f 动态跟踪它。

你可以使用下面的示例，当通过 SSH 插件 登录时：

tail -f /config/home-assistant.log

在 Docker 中，你可以直接使用你的主机命令行 - 动态跟踪日志：

# 动态跟踪日志
docker logs --follow MY_CONTAINER_ID

要查看其他选项，请改用 --help，或直接不带选项显示整个日志。