{"id":13736816,"url":"https://github.com/atheriel/openmetrics","last_synced_at":"2025-05-08T13:31:36.919Z","repository":{"id":48920514,"uuid":"254420092","full_name":"atheriel/openmetrics","owner":"atheriel","description":"An opinionated Prometheus client for R conforming to the OpenMetrics standard","archived":false,"fork":false,"pushed_at":"2021-11-15T18:49:27.000Z","size":255,"stargazers_count":35,"open_issues_count":3,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-29T16:17:29.068Z","etag":null,"topics":["metrics","openmetrics","plumber","prometheus","prometheus-client","r","shiny"],"latest_commit_sha":null,"homepage":"https://atheriel.github.io/openmetrics/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atheriel.png","metadata":{"files":{"readme":"README.Rmd","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}},"created_at":"2020-04-09T16:12:42.000Z","updated_at":"2024-10-08T19:54:38.000Z","dependencies_parsed_at":"2022-09-22T14:24:48.552Z","dependency_job_id":null,"html_url":"https://github.com/atheriel/openmetrics","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheriel%2Fopenmetrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheriel%2Fopenmetrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheriel%2Fopenmetrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheriel%2Fopenmetrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atheriel","download_url":"https://codeload.github.com/atheriel/openmetrics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224168535,"owners_count":17267271,"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":["metrics","openmetrics","plumber","prometheus","prometheus-client","r","shiny"],"created_at":"2024-08-03T03:01:29.154Z","updated_at":"2024-11-15T05:30:38.547Z","avatar_url":"https://github.com/atheriel.png","language":"R","funding_links":[],"categories":["Developer Tools","R"],"sub_categories":["Monitoring and Analytics"],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\nlibrary(openmetrics)\n```\n\n# openmetrics \u003cimg src='man/figures/logo.png' align=\"right\" height=\"139\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![travis-ci build status](https://travis-ci.org/atheriel/openmetrics.svg?branch=master)](https://travis-ci.org/atheriel/openmetrics)\n[![CRAN status](https://www.r-pkg.org/badges/version/openmetrics)](https://cran.r-project.org/package=openmetrics)\n\u003c!-- badges: end --\u003e\n\n**openmetrics** is an opinionated client for\n[Prometheus](https://prometheus.io/) and the related\n[OpenMetrics](https://openmetrics.io/) project. It makes it possible to add\npredefined and custom metrics to any R web application and expose them on a\n`/metrics` endpoint, where they can be consumed by Prometheus services.\n\nThe package includes built-in support for [Plumber](https://www.rplumber.io/)\nand [Shiny](https://shiny.rstudio.com/) applications, but is highly extensible.\n\n## Installation\n\nYou can install **openmetrics** from CRAN with\n\n```r\ninstall.packages(\"openmetrics\")\n```\n\nor from GitHub with\n\n```r\n# install.packages(\"remotes\")\nremotes::install_github(\"atheriel/openmetrics\")\n```\n\n## Use with Plumber\n\nYou can easily wrap an existing Plumber router object to add metrics for HTTP\nrequests and their duration:\n\n```r\nsrv \u003c- plumber::plumb(\"plumber.R\")\nsrv \u003c- register_plumber_metrics(srv)\nsrv$run()\n```\n\nThis will automatically create a `/metrics` endpoint that exposes these metrics\n(and any others you have defined).\n\n### Authentication\n\nTo add authentication to this endpoint, set the `METRICS_HTTP_AUTHORIZATION`\nenvironment variable to the expected [`Authorization`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)\nheader you want Prometheus to use. For example, to grant access to the username\n\"aladdin\" with password \"opensesame\":\n\n```\nSys.setenv(METRICS_HTTP_AUTHORIZATION = \"Basic YWxhZGRpbjpvcGVuc2VzYW1l\")\n```\n\nMeanwhile, in your Prometheus configuration:\n\n```yaml\nscrape_configs:\n# ...\n- job_name: my-plumber-api\n  basic_auth:\n    username: aladdin\n    password: opensesame\n  # ...\n```\n\n## Use with Shiny\n\nYou can also wrap an existing Shiny app object to add metrics on reactive flush\nduration and a running session count. In your `app.R` file, you can use\nsomething like the following:\n\n```r\napp \u003c- shiny::shinyApp(...)\napp \u003c- register_shiny_metrics(app)\napp\n```\n\nWhich will be picked up by `shiny::runApp()`.\n\nAgain, this will automatically create a `/metrics` endpoint that exposes these\nmetrics (and any others you have defined). It supports the same authentication\nmethod as well.\n\n**This feature should be considered experimental**. It relies on certain\nunstable Shiny internals to add the `/metrics` endpoint, which [is not usually\npossible](https://github.com/rstudio/shiny/issues/2395).\n\n## Default Process Metrics\n\nYou can enable the [default process metrics](https://prometheus.io/docs/instrumenting/writing_clientlibs/#process-metrics)\n(which track CPU time, memory usage, and open files) with\n\n```{r default-metrics, eval = FALSE}\nregister_default_metrics()\n```\n\nNote that not all metrics are supported (or even meaningful) on all operating\nsystems.\n\n## Custom Metrics\n\nAll required metrics and features of [the informal Prometheus client\nspecification](https://prometheus.io/docs/instrumenting/writing_clientlibs/) are\nsupported, so you can create app-specific [counters, gauges, and\nhistograms](https://prometheus.io/docs/concepts/metric_types/). If you want to\nmake use of labels, you must pass a default value at the time of creation.\n\nHere are some examples collected from around the house:\n\n```{r custom-metrics}\nmeows \u003c- counter_metric(\"meows\", \"Heard around the house.\", labels = \"cat\")\nmeows$inc(cat = \"Shamus\") # Count one meow from Shamus.\nmeows$inc(3, cat = \"Unknown\") # Count three meows of unknown origin.\n\nthermostat \u003c- gauge_metric(\"thermostat\", \"Thermostat display.\")\nthermostat$set(21.3) # Read from the display...\nthermostat$dec(2) # ... and then turn it down 2 degrees.\n\ntemperature \u003c- histogram_metric(\n  \"temperature\", \"Ambient room temperature measurements.\",\n  buckets = c(10, 15, 20, 22, 25), room = \"kitchen\"\n)\nset.seed(9090)\n# Simulate taking ambient temperature samples.\nfor (measure in rnorm(20, mean = 21.5)) {\n  temperature$observe(measure, room = sample(c(\"kitchen\", \"bathroom\"), 1))\n}\n```\n\nAll metrics (in fact all exported functions) take a `registry` parameter in case\nyou want to avoid using the default global registry in some part of your\napplication. You can construct new registries with `registry()`.\n\n### Performance\n\nBecause metrics may be gathered with high frequency, some effort has been made\nto ensure that using them is fast -- usually around 10 microseconds.\n\n### Rendering Metrics Manually\n\nThe `render_metrics()` function exposes the [text-based OpenMetrics\nformat](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md)\nunderstood by Prometheus. Here's what the metrics above look like:\n\n```{r render-metrics, collapse = FALSE, comment = \"\"}\ncat(render_metrics())\n```\n\nYou can use this to implement a `/metrics` endpoint in your application if it is\nnot supported directly. For example, using a raw **httpuv** server:\n\n```r\nhttpuv::runServer(\n  \"127.0.0.1\", 8080,\n  list(call = function(req) {\n    list(\n      status = 200L,\n      headers = list(\"Content-Type\" = \"text/plain; version=0.0.4\"),\n      body = render_metrics()\n    )\n  })\n)\n```\n\n## Pushgateway Support\n\nSome workloads may not want to run an HTTP server to expose metrics, especially\nin the case of short-lived batch jobs. For these cases metrics can also be\nmanually \"pushed\" to a Prometheus Pushgateway instance, though [there are\ndrawbacks to this approach](https://prometheus.io/docs/practices/pushing/).\n\n`push_to_gateway()` can be used to push metrics, and `delete_from_gateway()`\ncan be used to clean them up when the workload is finished:\n\n```{r pushgateway, eval = FALSE}\npush_to_gateway(\"localhost:9091\", job = \"openmetrics-readme\")\n# Some time later...\ndelete_from_gateway(\"localhost:9091\", job = \"openmetrics-readme\")\n```\n\n## Limitations\n\n* The Summary metric is not available, as it is not required by the spec if a\n  Histogram is available. It is also difficult to implement, and [could be\n  considered a design error](https://www.robustperception.io/how-does-a-prometheus-summary-work).\n\n* Most of the default process metrics are absent on non-Linux systems. This is\n  basically because they were designed with Linux in mind, and very few\n  Prometheus clients support them for anything but Linux.\n\n## License\n\nThe package is made available under the terms of the MIT license. See `LICENSE`\nfor details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatheriel%2Fopenmetrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatheriel%2Fopenmetrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatheriel%2Fopenmetrics/lists"}