跳转到内容
ESPHome - 让智能家居更简单2026.7.0

Prometheus 组件

prometheus 组件为 Web Server 启用一个 HTTP 端点，以便集成 Prometheus 安装。

这可以直接将数据抓取到你的基于 Prometheus 的监控和告警系统中， 无需任何其他软件。

可用的指标列表可以通过直接浏览你的节点下的 <ip 或 node_name.local>/metrics 来查看，未来可能还会增加。

# 示例配置条目
web_server:


# 激活 prometheus /metrics 端点
prometheus:

配置变量

Section titled “配置变量”

  • id (可选, ID): 手动指定用于代码生成的 ID。

  • include_internal (可选, boolean): internal（内部）实体是否应显示在 Web 界面上。默认为 false。

  • relabel (可选): 覆盖指标标签。参见 relabel

NOTE

集成到你的 prometheus 配置中的示例：

scrape_configs:
  - job_name: esphome
    static_configs:
      - targets: [<ip 或 node_name.local>]

受支持的 ESPHome 组件

Section titled “受支持的 ESPHome 组件”
  • Sensor
  • Binary Sensor
  • Fan
  • Light
  • Cover
  • Switch
  • Lock
  • Text Sensor
  • Text
  • Event
  • Number
  • Select
  • Media Player
  • Update
  • Valve
  • Climate

受支持的 Prometheus 标签

Section titled “受支持的 Prometheus 标签”

以下标签在所有 Prometheus 指标中受支持。某些指标可能有更多标签。

  • entity id（实体 ID）
  • entity name（实体名称）
  • entity friendly name（实体友好名称）
  • area（区域）
  • node name（节点名称）

指标重命名

Section titled “指标重命名”

ESPHome 允许你对 Prometheus 指标进行一些基本的重命名（relabeling）。 如果你想使用与 Home Assistant 或 Web 界面中显示的不同指标名称或 ID，这会很有用。

你可以通过在 prometheus 配置中添加一个 relabel 块， 然后为你想要覆盖标签的每个传感器添加一个包含 id 和/或 name 字段的块，来重命名指标名称或 ID 标签。

relabel

Section titled “relabel”

为指定 ID 的传感器设置 Prometheus 指标的 id 和 name 标签值。

# 示例配置条目
prometheus:
  relabel:
    my_voltage_sensor:
      id: angry_pixies
      name: "Angry Pixies"

示例指标

Section titled “示例指标”

下面是许多可用 prometheus 指标中一部分的示例：

#TYPE esphome_sensor_value gauge
#TYPE esphome_sensor_failed gauge
esphome_sensor_failed{id="dev_idf_prometheus_goober_wifi_signal_db",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal dB"} 0
esphome_sensor_value{id="dev_idf_prometheus_goober_wifi_signal_db",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal dB",unit="dBm"} -35
esphome_sensor_failed{id="dev_idf_prometheus_goober_wifi_signal_percent",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal Percent"} 0
esphome_sensor_value{id="dev_idf_prometheus_goober_wifi_signal_percent",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal Percent",unit="Signal %"} 100
esphome_sensor_failed{id="dev_idf_prometheus_goober_uptime_sensor",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Uptime Sensor"} 0
esphome_sensor_value{id="dev_idf_prometheus_goober_uptime_sensor",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Uptime Sensor",unit="s"} 4
esphome_sensor_failed{id="dev_idf_prometheus_goober_uptime_timestamp",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Uptime Timestamp"} 1
esphome_sensor_failed{id="dev_idf_prometheus_goober_esphome_internal_temperature",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober ESPHome Internal Temperature"} 0
esphome_sensor_value{id="dev_idf_prometheus_goober_esphome_internal_temperature",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober ESPHome Internal Temperature",unit="°C"} 33.1
esphome_sensor_failed{id="heap_free",area="Dev",node="devidfprometheus",name="Heap Free"} 0
esphome_sensor_value{id="heap_free",area="Dev",node="devidfprometheus",name="Heap Free",unit="B"} 224724
esphome_sensor_failed{id="heap_max_block",area="Dev",node="devidfprometheus",name="Heap Max Block"} 0
esphome_sensor_value{id="heap_max_block",area="Dev",node="devidfprometheus",name="Heap Max Block",unit="B"} 147456
esphome_sensor_failed{id="loop_time",area="Dev",node="devidfprometheus",name="Loop Time"} 0
esphome_sensor_value{id="loop_time",area="Dev",node="devidfprometheus",name="Loop Time",unit="ms"} 17
esphome_sensor_failed{id="cpu_frequency",area="Dev",node="devidfprometheus",name="CPU Frequency"} 0
esphome_sensor_value{id="cpu_frequency",area="Dev",node="devidfprometheus",name="CPU Frequency",unit="Hz"} 160000000
#TYPE esphome_binary_sensor_value gauge
#TYPE esphome_binary_sensor_failed gauge
esphome_binary_sensor_failed{id="dev_idf_prometheus_goober_button",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Button"} 0
esphome_binary_sensor_value{id="dev_idf_prometheus_goober_button",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Button"} 0.000000
esphome_binary_sensor_failed{id="dev_idf_prometheus_goober_connected_status",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Connected Status"} 0
esphome_binary_sensor_value{id="dev_idf_prometheus_goober_connected_status",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Connected Status"} 0.000000
#TYPE esphome_light_state gauge
#TYPE esphome_light_color gauge
#TYPE esphome_light_effect_active gauge
esphome_light_state{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light"} 0.000000
esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="brightness"} 0.000000
esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="r"} 0.000000
esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="g"} 0.000000
esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="b"} 0.000000
esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="w"} 0.000000
esphome_light_effect_active{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",effect="None"} 0
#TYPE esphome_switch_value gauge
#TYPE esphome_switch_failed gauge
esphome_switch_failed{id="beta_firmware",area="Dev",node="devidfprometheus",name="Beta firmware"} 0
esphome_switch_value{id="beta_firmware",area="Dev",node="devidfprometheus",name="Beta firmware"} 0.000000
#TYPE esphome_text_sensor_value gauge
#TYPE esphome_text_sensor_failed gauge
esphome_text_sensor_failed{id="esphome_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Version Detailed"} 0
esphome_text_sensor_value{id="esphome_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Version Detailed",value="2025.8.0b1 Aug 16 2025, 13:48:52"} 1.0
esphome_text_sensor_failed{id="esphome_version",area="Dev",node="devidfprometheus",name="ESPHome Version"} 0
esphome_text_sensor_value{id="esphome_version",area="Dev",node="devidfprometheus",name="ESPHome Version",value="2025.8.0b1"} 1.0
esphome_text_sensor_failed{id="esphome_project_version",area="Dev",node="devidfprometheus",name="ESPHome Project Version"} 0
esphome_text_sensor_value{id="esphome_project_version",area="Dev",node="devidfprometheus",name="ESPHome Project Version",value="4.13.8"} 1.0
esphome_text_sensor_failed{id="esphome_project_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Project Version Detailed"} 0
esphome_text_sensor_value{id="esphome_project_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Project Version Detailed",value="4.13.8 Aug 16 2025, 13:48:52"} 1.0
esphome_text_sensor_failed{id="esphome_board",area="Dev",node="devidfprometheus",name="ESPHome Board"} 0
esphome_text_sensor_value{id="esphome_board",area="Dev",node="devidfprometheus",name="ESPHome Board",value="esp32-s3-devkitc-1"} 1.0
esphome_text_sensor_failed{id="esphome_board_variant",area="Dev",node="devidfprometheus",name="ESPHome Board Variant"} 0
esphome_text_sensor_value{id="esphome_board_variant",area="Dev",node="devidfprometheus",name="ESPHome Board Variant",value="ESP32-S3"} 1.0
esphome_text_sensor_failed{id="esphome_framework_type",area="Dev",node="devidfprometheus",name="ESPHome Framework Type"} 0
esphome_text_sensor_value{id="esphome_framework_type",area="Dev",node="devidfprometheus",name="ESPHome Framework Type",value="ESP-IDF"} 1.0
esphome_text_sensor_failed{id="esphome_idf_version",area="Dev",node="devidfprometheus",name="ESPHome IDF Version"} 0
esphome_text_sensor_value{id="esphome_idf_version",area="Dev",node="devidfprometheus",name="ESPHome IDF Version",value="5.4.2"} 1.0
esphome_text_sensor_failed{id="reset_reason",area="Dev",node="devidfprometheus",name="Reset Reason"} 0
esphome_text_sensor_value{id="reset_reason",area="Dev",node="devidfprometheus",name="Reset Reason",value="USB peripheral"} 1.0
#TYPE esphome_number_value gauge
#TYPE esphome_number_failed gauge
esphome_number_failed{id="template_number",area="Dev",node="devidfprometheus",name="Template number"} 0
esphome_number_value{id="template_number",area="Dev",node="devidfprometheus",name="Template number"} 0.000000
#TYPE esphome_select_value gauge
#TYPE esphome_select_failed gauge
esphome_select_failed{id="template_select",area="Dev",node="devidfprometheus",name="Template select"} 0
esphome_select_value{id="template_select",area="Dev",node="devidfprometheus",name="Template select",value="two"} 1.0
#TYPE esphome_update_entity_state gauge
#TYPE esphome_update_entity_info gauge
#TYPE esphome_update_entity_failed gauge
esphome_update_entity_failed{id="firmware_update",area="Dev",node="devidfprometheus",name="Firmware Update"} 1
#TYPE esphome_text_value gauge
#TYPE esphome_text_failed gauge
esphome_text_failed{id="template_text",area="Dev",node="devidfprometheus",name="Template text"} 0
esphome_text_value{id="template_text",area="Dev",node="devidfprometheus",name="Template text",value="Hello World"} 1.0
#TYPE esphome_event_value gauge
#TYPE esphome_event_failed gauge
esphome_event_failed{id="template_event",area="Dev",node="devidfprometheus",name="Template Event"} 0
esphome_event_value{id="template_event",area="Dev",node="devidfprometheus",name="Template Event",last_event_type="custom_event_1"} 1.0

另请参阅

Section titled “另请参阅”