跳转到内容
ESPHome - 智能家居，简单易用

Prometheus 组件

prometheus 组件为 Web 服务器启用 HTTP 端点，以便集成 Prometheus 安装。

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

可用指标列表可以通过直接在您的节点下浏览 <ip 或 node_name.local>/metrics 找到，将来可能会增加。

# 示例配置项
web_server:


# 激活 prometheus /metrics 端点
prometheus:

配置变量

Section titled “配置变量”

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

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

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

NOTE

集成到您的 prometheus 配置的示例：

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

支持的 ESPHome 组件

Section titled “支持的 ESPHome 组件”
  • 传感器
  • 二进制传感器
  • 风扇
  • 灯光
  • 卷帘
  • 开关
  • 锁
  • 文本传感器
  • 文本
  • 事件
  • 数值
  • 选择器
  • 媒体播放器
  • 更新
  • 阀门
  • 恒温器

支持的 Prometheus 标签

Section titled “支持的 Prometheus 标签”

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

  • 实体 id
  • 实体名称
  • 实体友好名称
  • 区域
  • 节点名称

指标重新标记

Section titled “指标重新标记”

ESPHome 允许您对 Prometheus 指标进行一些基本的重新标记。 如果您想要与 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: "愤怒的小精灵"

指标示例

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 “另请参阅”