{"id":13414278,"url":"https://github.com/mongoose-os-libs/prometheus-metrics","last_synced_at":"2025-03-14T21:32:24.464Z","repository":{"id":54532095,"uuid":"111777594","full_name":"mongoose-os-libs/prometheus-metrics","owner":"mongoose-os-libs","description":null,"archived":false,"fork":false,"pushed_at":"2022-11-09T10:37:44.000Z","size":69,"stargazers_count":8,"open_issues_count":2,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-07-31T21:52:48.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","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/mongoose-os-libs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-23T07:32:02.000Z","updated_at":"2022-11-09T10:37:50.000Z","dependencies_parsed_at":"2023-01-21T18:00:15.159Z","dependency_job_id":null,"html_url":"https://github.com/mongoose-os-libs/prometheus-metrics","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoose-os-libs%2Fprometheus-metrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoose-os-libs%2Fprometheus-metrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoose-os-libs%2Fprometheus-metrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoose-os-libs%2Fprometheus-metrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mongoose-os-libs","download_url":"https://codeload.github.com/mongoose-os-libs/prometheus-metrics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221508978,"owners_count":16834807,"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":[],"created_at":"2024-07-30T21:00:17.789Z","updated_at":"2024-10-26T07:30:49.458Z","avatar_url":"https://github.com/mongoose-os-libs.png","language":"C","funding_links":[],"categories":["Awesome Mongoose OS [![Awesome](https://awesome.re/badge.svg)](https://awesome.re)"],"sub_categories":["Official Libraries"],"readme":"# prometheus-metrics\n\nA Mongoose OS Prometheus Metrics library.\n\n## Introduction\n\n[Prometheus](https://prometheus.io) is an open-source systems monitoring and\nalerting toolkit originally built at SoundCloud. Since its inception in 2012,\nmany companies and organizations have adopted Prometheus, and the project has\na very active developer and user community. It is now a standalone open source\nproject and maintained independently of any company.\n\n[Mongoose OS](https://mongoose-os.com) is a purpose-built secure Operating\nSystem for commercial connected devices. It focuses on stable and secure\nfunctioning of multiple connected devices in production and post-sale stages.\nKey features include secure communication (TLS), over-the-air updates (OTA)\nand remote device management. These features are usually missing from SDK and\ntheir correct implementation would be a complex and resource consuming task.\nNeglecting them may result in compromised device security and negative brand\nperception of your products.\n\n### Structure\n\n`prometheus-metrics` is a library component that can be added to the app's\n`mos.yml` file without any configuration needed out of the box, and it pulls\nin the `http-server` module. The library opens a `/metrics` endpoint which\nexposes the operating system and library vitalsigns to Prometheus.\n\nBy adding the library to the build manifest in `mos.yml`, a compiler define\n`MGOS_HAVE_PROMETHEUS_METRICS` is set, which other libraries can use to\ncreate metrics and update them. This is _non intrusive_ because if the\nlibrary is not used, no additional code is compiled in Mongoose OS and its\nlibraries.\n\n### Implementation\n\n#### Base MGOS Metrics\n\nAll Mongoose vitals (memory, WiFi/Ethernet, CPU, scheduling) are exposed\nusing the `mgos_` prefix.\n\n```\n# HELP mgos_build Build info\n# TYPE mgos_build gauge\nmgos_build{app=\"empty\",id=\"20171121-164823/???\",version=\"1.1.04\"} 1\n# HELP mgos_platform Platform information\n# TYPE mgos_platform gauge\nmgos_platform{arch=\"esp32\",mac=\"240AC4106560\",idf=\"v1.0-2815-g50a73c1\"} 1\n# HELP mgos_uptime Uptime in seconds\n# TYPE mgos_uptime counter\nmgos_uptime 1888\n# HELP mgos_heap_size System memory size\n# TYPE mgos_heap_size gauge\nmgos_heap_size 295076\n```\n\n#### Platform Specific Metrics\n\nPlatform specific vitals are exposed using the `$platform_` prefix, for\nexample `esp32_` for ESP32 and ESP-IDF metrics.\n\n```\n# HELP esp32_chip_info ESP32 Chip Information\n# TYPE esp32_chip_info gauge\nesp32_chip_info{model=0,cores=2,revision=1,features=32,sdk=\"master\"} 1\n# HELP esp32_num_tasks ESP32 FreeRTOS task count\n# TYPE esp32_num_tasks gauge\nesp32_num_tasks 9\n```\n\n#### Library Specific Metrics\n\nLibrary owners gate the code that creates, updates and exposes the metrics\nby the define `MGOS_HAVE_PROMETHEUS_METRICS`. Metrics should be defined as\nstatic variables to stay private to the implementation. Then, a callback\nfunction is installed, and `prometheus-metrics` will loop over all\nregistered callbacks to allow them to add their metrics to the output.\n\nTaking `mqtt` as an example:\n\n```\n#if MGOS_HAVE_PROMETHEUS_METRICS\n#include \"mgos_prometheus_metrics.h\"\n\nstatic uint32_t metrics_mqtt_sent_topics_count = 0;\nstatic uint32_t metrics_mqtt_sent_topics_bytes_total = 0;\nstatic uint32_t metrics_mqtt_received_topics_count = 0;\nstatic uint32_t metrics_mqtt_received_topics_bytes_total = 0;\n\nstatic void metrics_mqtt(struct mg_connection *nc, void *user_data) {\n  mgos_prometheus_metrics_printf(nc, COUNTER,\n    \"mgos_mqtt_sent_topics_count\", \"MQTT topics sent\",\n    \"%u\", metrics_mqtt_sent_topics_count);\n\n  mgos_prometheus_metrics_printf(nc, COUNTER,\n    \"mgos_mqtt_sent_topics_bytes_total\", \"Total bytes sent in MQTT topics\",\n    \"%u\", metrics_mqtt_sent_topics_bytes_total);\n\n  mgos_prometheus_metrics_printf(nc, COUNTER,\n    \"mgos_mqtt_received_topics_count\", \"MQTT topics sent\",\n    \"%u\", metrics_mqtt_received_topics_count);\n\n  mgos_prometheus_metrics_printf(nc, COUNTER,\n    \"mgos_mqtt_received_topics_bytes_total\", \"Total bytes received in MQTT topics\",\n    \"%u\", metrics_mqtt_received_topics_bytes_total);\n\n  (void) user_data;\n}\n#endif // MGOS_HAVE_PROMETHEUS_METRICS\n```\n\nThen in the library's `init` function, register the callback:\n\n```\nbool mgos_mqtt_init(void) {\n#if MGOS_HAVE_PROMETHEUS_METRICS\n  mgos_prometheus_metrics_add_handler(metrics_mqtt, NULL);\n#endif\n  return true;\n}\n```\n\nAs mentioned above, if the `prometheus-metrics` library is not included in\nthe app's `mos.yml` manifest, no code will be compiled which makes the addition\n_non intrusive_.\n\n#### Application Specific Metrics\n\nUsers are able to add their app's own metrics in the same way as libraries can.\nThey do this by registering a handler function, which is called from\n`prometheus-metrics`.\n\n```\n#include \"mgos_prometheus_metrics.h\"\nuint32_t my_counter=0;\n\nstatic void prometheus_metrics_fn(struct mg_connection *nc, void *user_data) {\n  mgos_prometheus_metrics_printf(nc, COUNTER,\n    \"my_counter\", \"Total things counted\",\n    \"%u\", my_counter);\n  (void) user_data;\n}\n\nenum mgos_app_init_result mgos_app_init(void) {\n  mgos_prometheus_metrics_add_handler(prometheus_metrics_fn, NULL);\n  return MGOS_APP_INIT_SUCCESS;\n}\n```\n\n### POSTing to Pushgateway\n\nPrometheus offers an intermediate receiver called a `Pushgateway`, see their\n[codebase](https://github.com/prometheus/pushgateway) for details. Some users\nmay not wish to have their Mongoose IoT device listen on the network for HTTP\nconnections to the `/metrics` endpoint, for security reasons. As an\nalternative, the library can be configured to close its serving endpoint, and\npush its metrics upstream instead. In `mos.yml`:\n\n```\nconfig_schema:\n  - [\"prometheus.server_enable\", false]\n  - [\"prometheus.pushgateway\", \"s\", \"example.com:9091\"]\n```\n\nAn example program using a timer to POST every 5 seconds:\n\n```\n#include \"mgos.h\"\n#include \"mgos_prometheus_metrics.h\"\n\nstatic void timer_cb(void *user_data) {\n  mgos_prometheus_metrics_push(\"test1\", \"instance1\");\n  (void) user_data;\n}\n\nenum mgos_app_init_result mgos_app_init(void) {\n  mgos_set_timer(5000, true, timer_cb, NULL);\n  return MGOS_APP_INIT_SUCCESS;\n}\n```\n\nIf needed you can also specify the `Authorization` header for pushing metrics.\nYou can do this by specifying following in `mos.yml`:\n\n```\nconfig_schema:\n  - [\"prometheus.pushgateway_auth\", \"Basic YWxhZGRpbjpvcGVuc2VzYW1l\"]\n```\n\n\n# Disclaimer\n\nThis project is not an official Google project. It is not supported by Google\nand Google specifically disclaims all warranties as to its quality,\nmerchantability, or fitness for a particular purpose.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongoose-os-libs%2Fprometheus-metrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmongoose-os-libs%2Fprometheus-metrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongoose-os-libs%2Fprometheus-metrics/lists"}