2025.3.4
首页 ▸ Integrations ▸

系统日志

system_log 集成存储关于 Home Assistant 所有记录的错误和警告的信息。要查看您的日志，请导航到 设置 -> 系统 -> 日志。为了不让 Home Assistant 超载于日志数据，仅会存储最近的 50 条错误和警告。较旧的条目会自动从日志中丢弃。可以使用参数 max_entries 来更改存储的日志条目数量。

配置

此集成由 frontend 自动加载（因此如果您使用前端就无需做任何操作）。如果您没有使用前端，或希望更改某个参数，请将以下部分添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中：

system_log:
  max_entries: MAX_ENTRIES

Configuration Variables

Looking for your configuration file?
max_entries integer (Optional, default: 50)

存储的条目数量（旧条目将被丢弃）。

fire_event string (Optional, default: false)

是否触发事件（在作为触发器使用时是必需的）。

动作

动作 clear

要手动清除系统日志，请使用此动作。

动作 write

写入日志条目

数据属性 可选 描述
message 否 要记录的消息
level 是 日志级别：debug, info, warning, error, critical。默认为 ‘error’。
logger 是 记录消息的日志名称。默认为 ‘system_log.external’。

事件

错误和警告以事件 system_log_event 的形式发布，因此可以编写自动化，在发生警告或错误时触发。每个事件中包含以下信息：

字段 描述
level 根据严重性为 WARNING 或 ERROR。
source 触发错误的文件，例如 core.py 或 media_player/yamaha.py。
exception 如果可用则为完整的堆栈跟踪，否则为空字符串。
message 错误的描述性消息，例如 “处理请求时出错”。
name 集成名称，例如 homeassistant.components.device_tracker。
timestamp 以双精度表示的 Unix 时间戳，例如 1517241010.237416。

这些事件的实时示例可以在 Home Assistant 日志文件（home-assistant.log）中找到，或通过查看系统日志即可。示例可能如下所示：

2019-02-14 16:20:35 ERROR (MainThread) [homeassistant.loader] 找不到集成 system_healt
2019-02-14 16:20:36 ERROR (MainThread) [homeassistant.components.device_tracker] 设置平台 google_maps 时出错
回溯（最近的调用最后）：
  文件 "/home/fab/Documents/repos/ha/home-assistant/homeassistant/integrations/device_tracker/__init__.py"，行 184，在
[...]

消息（“找不到集成 system_healt”）、名称（homeassistant.loader）和级别（ERROR）可以很容易地从日志中提取。确切的时间戳以及是否显示堆栈跟踪也是如此。

示例

以下是一些使用 system_log 发布的事件的示例。fire_event 必须设置为 true 才能使这些生效。

计算警告数量

这将创建一个 counter，每当记录警告时增加一次：

counter:
  warning_counter:
    name: 警告
    icon: mdi:alert

automation:
  - alias: "计数警告"
    triggers:
      - trigger: event
        event_type: system_log_event
        event_data:
          level: WARNING
    actions:
      - action: counter.increment
        target:
          entity_id: counter.warning_counter

条件消息

每当记录包含 “action” 词的错误或警告时，此自动化将创建一个持久通知：

automation:
  - alias: "为 'action' 错误创建通知"
    triggers:
      - trigger: event
        event_type: system_log_event
    conditions:
      - condition: template
        value_template: '{{ "action" in trigger.event.data.message[0] }}'
    actions:
      - action: persistent_notification.create
        data:
          title: "发生了不好的事情"
          message: "{{ trigger.event.data.message[0] }}"

写入日志

当门被打开时，此自动化将创建一个新的日志条目：

automation:
  - alias: "门已打开日志"
    triggers:
      - trigger: state
        entity_id: binary_sensor.door
        from: "off"
        to: "on"
    actions:
      - action: system_log.write
        data:
          message: "门已打开！"
          level: info