{"id":13581900,"url":"https://github.com/sh0rez/promqtt","last_synced_at":"2025-03-25T00:31:38.800Z","repository":{"id":45079224,"uuid":"379418360","full_name":"sh0rez/promqtt","owner":"sh0rez","description":"Generic Prometheus ⟷ MQTT Bridge","archived":false,"fork":false,"pushed_at":"2022-01-10T13:25:41.000Z","size":24,"stargazers_count":18,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T05:42:10.731Z","etag":null,"topics":["bridge","iot","mqtt","prometheus","tasmota"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sh0rez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-22T22:43:33.000Z","updated_at":"2024-02-20T17:39:14.000Z","dependencies_parsed_at":"2022-08-26T09:41:07.836Z","dependency_job_id":null,"html_url":"https://github.com/sh0rez/promqtt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rez%2Fpromqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rez%2Fpromqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rez%2Fpromqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sh0rez%2Fpromqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sh0rez","download_url":"https://codeload.github.com/sh0rez/promqtt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245377920,"owners_count":20605374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bridge","iot","mqtt","prometheus","tasmota"],"created_at":"2024-08-01T15:02:18.561Z","updated_at":"2025-03-25T00:31:38.514Z","avatar_url":"https://github.com/sh0rez.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"![](./logo.svg)\n\n# Promqtt: Prometheus ⟷ MQTT Bridge\n\nPromqtt makes Prometheus MQTT capable in a truly generic way.\n\nIt has no assumptions on message payloads or topic layout.\n\n## Installation\n\nPromqtt is best used with Docker, an image is available at [`shorez/promqtt`](https://hub.docker.com/r/shorez/promqtt).\n\nIf that is no option, Promqtt can also be installed from source using Go:\n\n```sh\n$ go install github.com/sh0rez/promqtt@latest\n```\n\nPromqtt accepts very little configuration which is exposed as command line flags:\n\n```bash\npromqtt \u003cbroker\u003e [flags]\n```\n\n**Arguments**:\n\n- `broker`: Any MQTT broker (e.g. `myBroker:1883`)\n\n**Flags**:\n\n- `--client-id`: The MQTT Client ID to use. Defaults to `promqtt@HOSTNAME`\n- `--listen`: The address to bind the HTTP server to. Defaults to `:9337`\n\nAbove list may be incomplete, consult `promqtt --help` for what your current build supports\n\n## Usage\n\nIn similar fashion to the `blackbox_exporter` and `snmp_exporter`, Promqtt acts\nas a general purpose relay, meaning you do not configure specific topics, etc.\nahead of time.\n\nInstead, these must be provided by Prometheus while scraping. Using clever\nrelabeling it makes Prometheus look like it supported MQTT itself:\n\n### Basic\n\nThe most basic use-case assumes a sender literally publishes `float64`\ncompatible values (any kind of number really) to some MQTT topic:\n\n\u003e **Topic**: `diox/06FE2A3/co2`  \n\u003e **Payload**: `42.0`\n\nA possible `scrape_configs` entry for looks like this:\n\n```yaml\n- job_name: diox\n  metrics_path: /mqtt # Promqtt serves MQTT metrics under this path\n  static_configs:\n    - targets:\n        - diox/.+/.+ # regular expression matching some MQTT topic\n  relabel_configs:\n    # copy above address (diox/...) into the \"topic\" URL parameter\n    - source_labels: [__address__]\n      target_label: __param_topic\n    # and also to the instance label\n    - source_labels: [__param_topic]\n      target_label: instance\n    # make Prometheus scrape Promqtt at ADDRESS\n    - target_label: __address__\n      replacement: ADDRESS:9337\n```\n\nConsidering above MQTT message, this would yield the following series:\n\n```bash\n# TYPE diox_06FE2A3_co2 gauge\ndiox_06FE2A3_co2{topic=\"diox/06FE2A3/co2\", instance=\"diox/.+/.+\"} 42.0\n```\n\n### Regex\n\nObviously, not all MQTT devices publish perfect float values to distinct topics.\nTo accompany for that, Promqtt lets you optionally a regular expression using\nnamed capture groups to extract parts of messages:\n\n\u003e **Topic**: `tele/tv/SENSOR`  \n\u003e **Payload**:\n\u003e\n\u003e ```js\n\u003e {\"Time\":\"2021-06-27T17:38:56\",\"ENERGY\":{\"TotalStartTime\":\"2021-01-16T13:12:08\",\"Total\":56.040,\"Yesterday\":0.923,\"Today\":0.536,\"Period\":1,\"Power\":10,\"ApparentPower\":32,\"ReactivePower\":30,\"Factor\":0.32,\"Voltage\":233,\"Current\":0.136}}\n\u003e ```\n\nWe could use the following regular expression, to parse out the `Power`,\n`Voltage` and `Current` fields\n([Explanation](https://regex101.com/r/igWHKh/1/)):\n\n```regex\n\"Power\":(?P\u003c_power\u003e[\\d.]+).*\"Voltage\":(?P\u003c_voltage\u003e[\\d.]+).*\"Current\":(?P\u003c_current\u003e[\\d.]+)\n```\n\nThis gives us the following `scrape_configs` entry:\n\n```yaml\n- job_name: tasmota\n  metrics_path: /mqtt # Promqtt serves MQTT metrics under this path\n  static_configs:\n    - targets:\n        - tele/.+/SENSOR # regular expression matching some MQTT topic\n  params:\n    regex:\n      - '\"Total\": *(?P\u003c_total_kWh\u003e[\\d.]+).*\"Power\": *(?P\u003c_power_watt\u003e[\\d.]+).*\"ApparentPower\": *(?P\u003c_apparent_power_VA\u003e[\\d.]+).*\"ReactivePower\": *(?P\u003c_reactive_power_VAr\u003e[\\d.]+).*\"Factor\": *(?P\u003c_factor\u003e[\\d.]+).*\"Voltage\": *(?P\u003c_voltage\u003e[\\d.]+).*\"Current\": *(?P\u003c_current\u003e[\\d.]+)'\n\n  relabel_configs:\n    # copy above address (tele/...) into the \"topic\" URL parameter\n    - source_labels: [__address__]\n      target_label: __param_topic\n    # and also to the instance label\n    - source_labels: [__param_topic]\n      target_label: instance\n    # make Prometheus scrape Promqtt at ADDRESS\n    - target_label: __address__\n      replacement: ADDRESS:9337\n```\n\nThe names of the capture groups (`_power`, `_voltage` and `_current`) are\nappended to the generated series name, yielding the following:\n\n```bash\n# TYPE tele_tv_SENSOR_power gauge\ntele_tv_SENSOR_power{topic=\"tele/tv/SENSOR\", instance=\"tele/.+/SENSOR\"} 10\n\n# TYPE tele_tv_SENSOR_voltage gauge\ntele_tv_SENSOR_voltage{topic=\"tele/tv/SENSOR\", instance=\"tele/.+/SENSOR\"} 233\n\n# TYPE tele_tv_SENSOR_current gauge\ntele_tv_SENSOR_current{topic=\"tele/tv/SENSOR\", instance=\"tele/.+/SENSOR\"} 0.136\n```\n\n### Series renaming\n\nAbove series obviously don't quite comply with the [Prometheus naming\nconventions](https://prometheus.io/docs/practices/naming/).\n\nBut again, this can be fixed by adding some `metric_relabel_configs`. Continuing above example:\n\n```yaml\n- job_name: tasmota\n  # ...\n  metric_relabel_configs:\n    # rename series to tasmota_\u003cfield\u003e style\n    - source_labels: [__name__]\n      target_label: __name__\n      regex: tele.+_SENSOR_(.+)\n      replacement: tasmota_$1\n    # extract device from topic to its own label\n    - source_labels: [topic]\n      target_label: dev\n      regex: tele/(.+)/.+\n```\n\nAfterwards, we get the following:\n\n```bash\n# TYPE tele_tv_SENSOR_power gauge\ntasmota_power{topic=\"tele/tv/SENSOR\", instance=\"tele/.+/SENSOR\", dev=\"tv\"} 10\n\n# TYPE tele_tv_SENSOR_voltage gauge\ntasmota_voltage{topic=\"tele/tv/SENSOR\", instance=\"tele/.+/SENSOR\", dev=\"tv\"} 233\n\n# TYPE tele_tv_SENSOR_current gauge\ntasmota_current{topic=\"tele/tv/SENSOR\", instance=\"tele/.+/SENSOR\", dev=\"tv\"} 0.136\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsh0rez%2Fpromqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsh0rez%2Fpromqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsh0rez%2Fpromqtt/lists"}