{"id":27773073,"url":"https://github.com/zgiber/promqtt","last_synced_at":"2025-10-06T02:18:49.936Z","repository":{"id":287371443,"uuid":"964523075","full_name":"zgiber/promqtt","owner":"zgiber","description":"Simple MQTT to prometheus connector tailored to work with Tasmota devices.","archived":false,"fork":false,"pushed_at":"2025-04-13T22:01:28.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T07:51:37.511Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zgiber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-11T10:51:42.000Z","updated_at":"2025-04-13T22:01:31.000Z","dependencies_parsed_at":"2025-04-30T00:06:31.633Z","dependency_job_id":"9b13ec21-7ca0-4f4d-9dde-29a0eb6b30eb","html_url":"https://github.com/zgiber/promqtt","commit_stats":null,"previous_names":["zgiber/promqtt"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zgiber/promqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fpromqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fpromqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fpromqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fpromqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zgiber","download_url":"https://codeload.github.com/zgiber/promqtt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgiber%2Fpromqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278547936,"owners_count":26004796,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-04-30T00:06:29.786Z","updated_at":"2025-10-06T02:18:49.908Z","avatar_url":"https://github.com/zgiber.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# promqtt - MQTT to Prometheus Bridge\n\nA simple Go service that connects to an MQTT broker, subscribes\nto a specified topic structure, parses JSON payloads, and exposes the data as\nPrometheus metrics via an HTTP endpoint.\n\n## Overview\n\nThis tool acts as a bridge between MQTT messages (typically from IoT devices\nlike those running Tasmota, ESPHome, etc.) and a Prometheus monitoring system.\nIt dynamically creates Prometheus gauges based on the MQTT topic structure and\nthe fields within the JSON payload of the messages. \n\n## Limitations\n\nOnly tested with Tasmota. Only extracts gauge values from numeric measurements.\n\n## Features\n\n* Connects to an MQTT broker using various schemas (mqtt, tcp, ws, wss, ssl).\n* Subscribes to MQTT topics with wildcard support (`+`, `#`).\n* Expects a specific 3-segment topic structure (`\u003ctopic_label\u003e/\u003cdevice_label\u003e/\u003ctype_label\u003e`).\n* Parses JSON payloads from MQTT messages.\n* Dynamically creates Prometheus Gauge metrics.\n  * Metric Name: Derived from JSON keys (`\u003csensor_key\u003e_\u003cmetric_key\u003e`).\n  * Labels: Includes `topic`, `device`, `type` (from MQTT topic segments) and\n  `sensor` (from JSON sensor key).\n* Exposes metrics on a configurable HTTP port (`/metrics`) for Prometheus scraping.\n* Can be run directly or as a systemd background service.\n* Exposes only custom metrics (no default Go/process metrics).\n\nAn example collected metric:\n\n|Element|Value|\n|-------|-----|\n|scd40_carbondioxide{device=\"tasmota_5E2D5C\",instance=\"localhost:9099\",job=\"tasmota_mqtt\",sensor=\"scd40\",topic=\"tele\",type=\"SENSOR\"}|1326|\n\n## Requirements\n\n* **Go Compiler:** Required to build the binary from source (Go 1.18+ recommended).\n* **MQTT Broker:** An accessible MQTT broker where your devices publish data.\n* **Prometheus:** A running Prometheus instance to scrape the metrics exposed\nby this tool.\n\n## Installation (from Source)\n\n1. **Clone/Download:** Get the source code (assuming you have the `.go` file).\n2. **Build:** Open your terminal in the directory containing the source code\n(`main.go`) and run:\n\n    ```bash\n    go build -o promqtt .\n    ```\n\n    This will create an executable file named `promqtt` in the current directory.\n3. **Place Binary (Optional but recommended for service):** Move the compiled\nbinary to a standard location:\n\n    ```bash\n    sudo mv promqtt /usr/local/bin/promqtt\n    sudo chown root:root /usr/local/bin/promqtt\n    sudo chmod 755 /usr/local/bin/promqtt\n    ```\n\n## Configuration\n\n`promqtt` is configured via command-line flags:\n\n* `-mqtt-url`: (Required) The full URL of your MQTT broker.\n  * Examples: `mqtt://localhost:1883`, `ssl://mqtt.example.com:8883`, `ws://broker.local:9001/mqtt`\n* `-mqtt-topic`: (Required) The MQTT topic pattern to subscribe to. Wildcards\n(`+`, `#`) are allowed. **Must resolve to 3 segments** for label mapping (`topic/device/type`).\n  * Example: `tele/+/+`, `sensors/+/status`\n* `-http-port`: (Optional) The port number for the Prometheus metrics HTTP endpoint.\n  * Default: `9099`\n* `-mqtt-user`: (Optional) Username for MQTT broker authentication.\n* `-mqtt-pass`: (Optional) Password for MQTT broker authentication.\n* `-mqtt-client-id`: (Optional) Custom MQTT client ID.\n  * Default: `mqtt-prometheus-bridge-` followed by 5 random characters.\n\n## Usage\n\n### 1. Running Directly\n\nYou can run the binary directly from your terminal, providing the necessary flags:\n\n```bash\n/usr/local/bin/promqtt \\\n    -mqtt-url \"mqtt://your_broker_host:1883\" \\\n    -mqtt-topic \"tele/+/+\" \\\n    -http-port 9099 \\\n    -mqtt-user \"your_user\" \\\n    -mqtt-pass \"your_password\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzgiber%2Fpromqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzgiber%2Fpromqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzgiber%2Fpromqtt/lists"}