{"id":20341928,"url":"https://github.com/douglaszuqueto/esp32-prometheus","last_synced_at":"2025-04-11T23:34:20.052Z","repository":{"id":91302779,"uuid":"249768283","full_name":"douglaszuqueto/esp32-prometheus","owner":"douglaszuqueto","description":"Utilizando Prometheus com ESP32","archived":false,"fork":false,"pushed_at":"2020-03-29T19:48:15.000Z","size":591,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T19:21:20.825Z","etag":null,"topics":["esp32","esp32-prometheus","espressif","grafana","iot","prometheus","prometheus-exporter"],"latest_commit_sha":null,"homepage":"https://github.com/douglaszuqueto/esp32-prometheus","language":"C++","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/douglaszuqueto.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-24T17:05:37.000Z","updated_at":"2024-11-02T23:50:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"39449cd1-28b1-45b7-8438-2a42e97aee93","html_url":"https://github.com/douglaszuqueto/esp32-prometheus","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/douglaszuqueto%2Fesp32-prometheus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglaszuqueto%2Fesp32-prometheus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglaszuqueto%2Fesp32-prometheus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglaszuqueto%2Fesp32-prometheus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/douglaszuqueto","download_url":"https://codeload.github.com/douglaszuqueto/esp32-prometheus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248495229,"owners_count":21113588,"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":["esp32","esp32-prometheus","espressif","grafana","iot","prometheus","prometheus-exporter"],"created_at":"2024-11-14T21:29:45.868Z","updated_at":"2025-04-11T23:34:20.031Z","avatar_url":"https://github.com/douglaszuqueto.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32 Prometheus\n\nMonitorando o ESP32 com Prometheus através do Grafana\n\n![img](https://gblobscdn.gitbook.com/assets%2F-M15s4TnAJw6r_zYzKkX%2F-M3HLnucrqfFIB7ZmE3Q%2F-M3HMGF5p5p4hbrZabpI%2Fdashboard-v1.png?alt=media\u0026token=8e621170-e22f-44cb-9ba9-64e4bf0e25b9)\n\n## Introdução\n\nEm diversos projetos envolvendo sensoriamento, se faz necessário o monitoramento dos dispositivos conectados na rede. Dessa forma, necessitamos utilizar ou desenvolver sistemas capazes de suprir essa demanda para poder analisar e monitorar qualquer anomalia que possa ocorrer na comunicação dos devices. \n\nCom um sistema implementado e com a coleta de algumas métricas ,podemos por exemplo detectar reboots inesperados, temperatura interna elevada, perca de pacotes devido a oscilação do sinal wifi e etc. Tais métricas serão abordadas em um tópico futuro.\n\nNesse artigo, você aprenderá como desenvolver um sistema para monitoramento do ESP32 utilizando serviços de código aberto e gratuitos denominados Prometheus e Grafana.\n\nPortanto, por meio desse artigo você aprenderá:\n\n* Coletar métricas do ESP32\n* Montar as métricas no formato do prometheus\n* Expor as métricas coletadas através do webserver \n* Instalar o Grafana\n* Instalar o Prometheus\n* Integrar o Prometheus com ESP32\n* Criar a dashboard de monitoramento\n\nAgora, iniciaremos a apresentação completa do desenvolvimento do projeto Monitorando o ESP32 com Prometheus através do Grafana.\n\n## Desenvolvendo o projeto *Monitorando o ESP32 com Prometheus através do Grafana*\n\nAntes de botarmos a mão na massa, a fim de se ter uma clareza melhor sobre o problema que queremos resolver, observe abaixo o diagrama de fluxo que iremos implementar nesse projeto.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/douglaszuqueto/esp32-prometheus/raw/master/.github/diagrama-v2.png\"\u003e\n\u003c/p\u003e\n\nBasicamente esse diagrama pode ser dividido em 3 partes, sendo elas:\n\n* 1 - Prometheus =\u003e ESP32\n* 2 - Grafana =\u003e Prometheus\n* 3 - Usuário =\u003e Grafana\n\nAgora que demos uma pincelada sobre o fluxo que iremos implementar, seguimos para os materiais que serão necessários para o desenvolvimento do projeto.\n\n## Materiais necessários\n\nComo requisitos básicos para o desenrolar do projeto de monitoramento, precisaremos dos itens citados a seguir:\n\n* 01 x ESP32\n* 01 x Raspberry(ou qualquer outra SBC compatível / servidor)\n\nA Raspberry será onde ficará hospedado os serviços necessários para rodar o projeto. Já o ESP32 será o \"core\" da aplicação, é com ele que conseguiremos coletar as métricas que serão abordadas no tópico abaixo.\n\n## Métricas monitoradas\n\nMonitorar algumas métricas de nossos dispositivos IoT são de suma importáncia, portanto veja na lista abaixo o que iremos será monitorado.\n\n* Uptime\n* Temperatura interna\n* Boot counter\n* WiFi RSSI\n* Memória total/utilizada\n* Memória flash total/utilizada\n\nTendo uma noção das métricas que serão monitoradas, podemos ir para o próximo tópico onde iremos tratar sobre os dois serviços que serão utilizados no projeto.\n\n## Serviços\n\nOs serviços serão instalados levando-se em consideração o uso de uma Raspberry PI. Caso deseja fazer em outro ambiente que seja baseado em Linux, os procedimentos serão bem parecidos :)\n\nNa sequência abordaremos o Prometheus, o primeiro serviço que será utilizado neste projeto.\n\n### Prometheus\n\nBanco de dados focado em séries temporais - TSDB(Time Series Database), muito utilizado em ecossistemas IoT.\n\nExemplos de TSDB's:\n\n* InfluxDB\n* TimescaleDB\n* Prometheus\n\nJá ouviu o famoso ditado: \"Dividir para conquistar\", pois então.. temos um banco de dados, mas como conseguiremos observar as métricas de forma gráfica? É ai que o Grafana entra na jogada!\n\n### Grafana\n\nServiço para compor dashboards elegantes de monitoramento de forma simples, a qual possui suporte a múltiplos banco de dados(datasources). \n\nEx: Prometheus, MySQL, PostgreSQL, dentre outros.\n\nAgora que sabemos um pouco mais sobre os serviços que utilizaremos neste projeto, podemos partir para a criação das métricas no prometheus.\n\n## Métricas no Prometheus\n\nPara estar criando métricas e integrando ao prometheus, você precisa ter uma noção base dos tipos compátiveis e como cada métrica é montada respeitando o layout do serviço. \n\n### Tipos\n\nComo não temos nenhum cliente prometheus para o ESP32, se faz necessário montar manualmente as métricas, e dentre os tipos disponíveis do Prometheus, os mais acessíveis para se implementar são os citados logo abaixo.\n\n* Counter - apenas incremento\n* Gauge - semelhante ao counter porém pode aumentar e diminuir\n\nExemplos:\n\n* Counter: contador de boot\n* Gauge: temperatura interna\n\nPara implementação dessas métricas, temos que seguir um padrão determinado pelo prometheus, veja na sequência como deve ser esse modelo.\n\n### Layout\n\nO prometheus segue a risca um formato para que as métricas expostas se tornem válida. Então ele impõe uma estrutura e consequentemente precisamos nos adaptar a ela.\n\nAbaixo segue um exemplo referente a uma métrica que será coletada:\n\n```\n# esp32_uptime Uptime total do ESP32\n# TYPE esp32_uptime gauge\nesp32_uptime 23899\n```\n\nPrimeira e segunda linhas são referentes a comentários envolvendo o nome da métrica, seu tipo e descrição.\n\nJá a última linha, envolve o nome da métrica e seu devido valor.\n\nComo podemos ver, o formato é muito simples e fácil de ser implementado manualmente conforme necessidade(exemplo do projeto).\n\n### Função para abstrair a métrica a ser montada\n\nA fim de não repetir muito código e concatenação de strings para formatar as métricas no formato prometheus, foi criado uma simples função para deixar o processo mais simples.\n\n```c\nvoid setMetric(String *p, String metric, String value) {\n  *p += \"# \" + metric + \"\\n\";\n  *p += \"# TYPE \" + metric + \" gauge\\n\";\n  *p += \"\" + metric + \" \";\n  *p += value;\n  *p += \"\\n\";\n}\n```\n\nUtilizando a função:\n\n```c\nString p = \"\";\n\nString uptime = String(millis());\n\nsetMetric(\u0026p, \"esp32_uptime\", uptime);\n```\n\nAgora que já temos uma noção dos tipos de métricas aplicáveis, quais métricas serão monitoradas e principalmente o formato que devemos seguir, colocaremos a mão na massa começando com o firmware da nosso hardware.\n\n### Firmware\n\nBaixe o [repositório](https://github.com/douglaszuqueto/esp32-prometheus/archive/master.zip) e faça o upload do firmware localizado na pasta **esp32-prometheus**.\n\n*Obs:* Antes de fazer o upload não esqueça de configurar as credenciais da rede wifi como também o IP estático do esp de acordo com sua rede.\n\nDepois de efetuar o upload e o firmware estiver rodando, você pode acessar o webserver através da seguinte url: http://IP_ESP:80/metrics.\n\nAo acessar, você deverá observar o seguinte resultado:\n\n```\n# esp32_uptime\n# TYPE esp32_uptime gauge\nesp32_uptime 7152784\n# esp32_wifi_rssi\n# TYPE esp32_wifi_rssi gauge\nesp32_wifi_rssi -34\n# esp32_heap_size\n# TYPE esp32_heap_size gauge\nesp32_heap_size 342316\n# esp32_free_heap\n# TYPE esp32_free_heap gauge\nesp32_free_heap 262444\n# esp32_sketch_size\n# TYPE esp32_sketch_size gauge\nesp32_sketch_size 728592\n# esp32_flash_size\n# TYPE esp32_flash_size gauge\nesp32_flash_size 3145728\n# esp32_available_size\n# TYPE esp32_available_size gauge\nesp32_available_size 2417136\n# esp32_temperature\n# TYPE esp32_temperature gauge\nesp32_temperature 46.11\n# esp32_boot_counter\n# TYPE esp32_boot_counter gauge\nesp32_boot_counter 7\n```\n\nO resultado acima nada mais é que o layout do prometheus já implementado, observe que cada métrica que será monitorada corresponde à um bloco de 3 linhas.\n\nAgora que já temos o firmware rodando no esp32, podemos seguir em frente com a preparação da raspberry para hospedar o prometheus juntamente com o grafana.\n\n## Instalação dos serviços\n\nAntes de iniciarmos com a instalação propriamente dita, vamos criar uma pasta onde os serviços ficarão armazenados na raspberry.\n\n*Obs:* Certifique-se que você está logado com o usuário padrão da raspberry - usuário **pi**.\n\n```bash\n# 1º\nmkdir services\n\n# 2º\ncd services\n\n# 3º =\u003e /home/pi/services\npwd\n```\n\nPronto! Podemos proceder com a instalação do Grafana.\n\n### Grafana\n\n```bash\n# 1º\nwget https://dl.grafana.com/oss/release/grafana_6.6.2_armhf.deb\n\n# 2º Efetuando a instalação\nsudo dpkg -i grafana_6.6.2_armhf.deb\n\n# 3º Habilitando o grafana para iniciar automaticamente ao iniciar a raspberry\nsudo systemctl enable grafana-server \n\n# 4º Iniciando o serviço\nsudo systemctl start grafana-server \n\n# 3º Visualizando o status\nsudo systemctl status grafana-server \n\n```\n\nTudo ok?! Hora de instalar o prometheus, nosso último serviço. \n\n### Prometheus\n\n```bash\n# 1º\nwget https://github.com/prometheus/prometheus/releases/download/v2.16.0/prometheus-2.16.0.linux-armv7.tar.gz\n\n# 2º\ntar zxvf prometheus-2.16.0.linux-armv7.tar.gz\n\n# 3º \nmv prometheus-2.16.0.linux-armv7 prometheus\n\n# 4º \ncd prometheus\n\n# 5º =\u003e /home/pi/services/prometheus\npwd\n\n# 6º Criação do serviço do prometheus para se integrar ao systemd assim como o grafana já está\necho \"\n[Unit]\nDescription=Prometheus Server\nDocumentation=https://prometheus.io/docs/introduction/overview/\nAfter=network-online.target\n\n[Service]\nUser=pi\nRestart=on-failure\nExecStart=/home/pi/services/prometheus/prometheus \\\n  --config.file=/home/pi/services/prometheus/prometheus.yml \\\n  --storage.tsdb.path=/home/pi/services/prometheus/data \\\n  --web.enable-lifecycle \\\n  --web.enable-admin-api\n\n[Install]\nWantedBy=multi-user.target\n\" | sudo tee \u003e /etc/systemd/system/prometheus.service\n\n# 4º\nsudo systemctl daemon-reload\n\n# 5º\nsudo systemctl enable prometheus \n\n# 6º\nsudo systemctl start prometheus \n\n# 7º\nsudo systemctl status prometheus\n```\n\nTodas instalações feitas. Caso queira validar tudo que foi feito, atente-se ao próximo tópico.\n\n## Teste dos serviços instalados\n\nSe tudo deu certo na instalação dos serviços, você poderá fazer os acessos conforme instruções abaixo:\n\n* Grafana\n\nhttp://IP_RASP:3000\n\nUser: admin\n\nPass: admin\n\n* Prometheus\n\nhttp://IP_RASP:9090\n\nRodou tudo certinho? Olha que beleza!\n\nAgora já temos todos serviços essenciais rodando em nosso embarcado. Nos tópicos a seguir serão de suma importância, serão neles que toda a integração final ocorrerá.\n\n## Configuração dos serviços\n\nCom o Grafana e Prometheus instalados, seguiremos com o procedimento de configuração dos serviços.\n\n### Prometheus\n\n```bash\n# 1º\ncd /home/pi/services/prometheus\n\n# 2º\ncat prometheus.yml\n```\n\nCom o último comando acima, você deverá ver em seu terminal o arquivo de configuração abaixo:\n\n```yml\n# my global config\nglobal:\n  scrape_interval:     15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.\n  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.\n  # scrape_timeout is set to the global default (10s).\n\n# Alertmanager configuration\nalerting:\n  alertmanagers:\n  - static_configs:\n    - targets:\n      # - alertmanager:9093\n\n# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.\nrule_files:\n  # - \"first_rules.yml\"\n  # - \"second_rules.yml\"\n\n# A scrape configuration containing exactly one endpoint to scrape:\n# Here it's Prometheus itself.\nscrape_configs:\n  # The job name is added as a label `job=\u003cjob_name\u003e` to any timeseries scraped from this config.\n  - job_name: 'prometheus'\n\n    # metrics_path defaults to '/metrics'\n    # scheme defaults to 'http'.\n\n    static_configs:\n    - targets: ['localhost:9090']\n```\n\nÉ nesse arquivo que todas configurações são declaradas. Então temos que dizer para esse arquivo qual *URL* o prometheus deverá ir para requisitar as métricas que estão 'hospedadas' no esp32.\n\nPortanto abre o arquivo *prometheus.yml* e adicione as seguintes configurações no final do arquivo para assim termos o esp32 integrado.\n\n```yml\n  # ESP32\n  - job_name: 'esp32'\n    scrape_interval: 5s\n    static_configs:\n    - targets: ['IP_ESP:80']\n```\n\n*Obs:* Tente respeitar a indentação do arquivo. A declaração acima deve estar alinhada com **- job_name:** que encontra-se logo acima.\n\nFinalizando a configuração:\n\n```bash\n# 1º - Comando HTTP para recarregar o arquivo de configuração que foi editado no passo acima\ncurl -X POST 127.0.0.1:9090/-/reload\n```\n\nCaso queira validar que o Prometheus continua funcionando normalmente e coletando as métricas do esp32, navegue até a url: http://IP_RASP:9090/targets.\n\nSe tiver sucesso, você terá uma tela como a da imagem abaixo mostrando um **\"State UP\"**.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/douglaszuqueto/esp32-prometheus/raw/master/.github/prometheus-v1.png\"\u003e\n\u003c/p\u003e\n\nAgora temos parte do diagrama de fluxo implementado. O prometheus já está apto a recolher as métricas do esp32 dentre o intervalo de 5 segundos.\n\nCom o prometheus já salvando os dados, resta adicionar a dashboard para começar o monitoramento do device.\n\n### Grafana\n\nPor default, o grafana vem 'zerado', e como queremos pegar os dados salvos do prometheus, é necessário a criação/configuração de um datasource.\n\n#### Adicionando datasource\n\nNavegue até o menu **Configuration** \u003e **Datasources** \u003e *Add data source*.\n\nNa tela, basicamente você precisa configurar apenas a variável **URL** localizada na seção *HTTP* com o IP da sua Raspberry.\n\nEx: http://192.168.0.150:9090\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/douglaszuqueto/esp32-prometheus/raw/master/.github/grafana-datasource-v1.png\"\u003e\n\u003c/p\u003e\n\nCom o datasource criado, já podemos importar a dashboard que foi especialmente desenvolvida para este projeto.\n\n#### Importando a dashboard\n\nCopie o conteúdo do arquivo json localizado [aqui](https://github.com/douglaszuqueto/esp32-prometheus/blob/master/.github/dashboard-v1.json).\n\nNo grafana vá até a opção **Create(+)** \u003e **Import**, cole o conteúdo copiado e clique em *load*. Na tela seguinte você pode alterar o nome da dashboard como também seu identificador - pode manter o mesmo em ambos!\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/douglaszuqueto/esp32-prometheus/raw/master/.github/grafana-import-v1.png\"\u003e\n\u003c/p\u003e\n\nComo foi visto, eu entreguei uma dashboard pronta para ser utilizada, ela é totalmente customizável. Como forma de estudo, recomendo que veja como cada painel foi configurado.\n\nPara não se extender muito neste projeto, deixarei um bônus para que você possa ter um gostinho de como criar alguns painéis.\n\n## Bônus\n\nComo bônus, será demonstrado como você pode adicionar outros painéis com as devidas métricas oriundas do prometheus.\n\nPassos básicos:\n\nCom a dashboard aberta, clique em **Add Panel**, logo na sequência, **Add Query**.\n\nObserve a tela na figura abaixo:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/douglaszuqueto/esp32-prometheus/raw/master/.github/grafana-add-panel-v2.png\"\u003e\n\u003c/p\u003e\n\nPor padrão, na metade superior será apresentado um gráfico vazio e na parte inferior é onde você fará as configurações.\n\nNa retângulo 1 basicamente temos 4 principais menus, sendo eles:\n\n* Queries\n* Visualization\n* General\n* Alert\n\nQueries é o menu que fará o link com o datasource - no nosso caso se trata do prometheus.\n\nNesse menu, temos um campo(retângulo 3) onde iremos inserir a respectiva query de consulta ao prometheus. Ela retornará os dados para que os mesmos sejam utilizados no gráfico.\n\nExemplo:\n\n```\nesp32_temperature{instance=\"$instance\"}\n```\n\nBasicamente estamos requisitando a temperatura do esp filtrando pela \"instância\", que é o ip do esp. Essa instância é genérica, ou seja, você pode alterar(select localizado no topo da dashboard) entre os devices que estão integrados ao prometheus.\n\nLogo que a query é colocada no campo, o gráfico já é preenchido.\n\nVeja abaixo como criar um *gauge* e uma *table*.\n\n### Criando um *Gauge*\n\nBaseando-se no exemplo acima, vamos navegar até o menu *Visualization* e trocar o gráfico por *Gauge*. E é isso, automaticamente o componente será mudado e preenchido com os valores, tudo isso devido ao datasource já estar configurado e com a query preenchida.\n\n### Criando uma *Table*\n\nAinda com o exemplo anterior, apenas mude para o componente *Table*, percebe que o mesmo processo ocorre. Agora temos uma tabela de histórico das temperaturas :)\n\n## Conclusão\n\nPortanto, a partir do desenvolvimento desse projeto, foi possível montar um sistema simples e eficaz para monitoramento do ESP32 utilizando projetos de código aberto.\n\nDentre as inúmeras formas de realizar tal monitoramento, essa talvez, seja uma das formas mais simples. Pois se faz necessário apenas um pouco de conhecimento para encaixar as peças.\n\nFoi obtido um resultado bem satisfatório, e com a dashboard pronta, você pode aproveitar para estudar como cada componente foi configurado, e assim, aprender a criar suas próprias dashboards de acordo com seu gosto e necessidades.\n\nFizemos um uso simples das tecnologias, porém, pode se avançar bastante, incluindo sistemas de alerta via email, telegram dentre outros tipos que já são embarcados nas tecnologias utilizadas.\n\n\n## Referências\n\n* [Firmware para ESP32 com suporte a integração com WebService e configuração via WiFiManager](https://github.com/douglaszuqueto/esp32-http-firmware)\n* [Comunicação remota utilizando RPC e ESP32](https://github.com/douglaszuqueto/esp32-rpc)\n* [ESP8266 Prometheus Exporter for DS18B20 OneWire Temperature Sensors](https://github.com/theoretick/esp8266_prometheus_exporter_for_ds18b20_temperature_sensors)\n* [Example - Hello Server](https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/HelloServer/HelloServer.ino)\n* [Example - WiFiClientStaticIP](https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientStaticIP/WiFiClientStaticIP.ino)\n* [ESP32 internal temperature](https://github.com/espressif/arduino-esp32/issues/2422)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdouglaszuqueto%2Fesp32-prometheus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdouglaszuqueto%2Fesp32-prometheus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdouglaszuqueto%2Fesp32-prometheus/lists"}