{"id":26059669,"url":"https://github.com/orange-cloudfoundry/promfetcher","last_synced_at":"2026-02-03T01:09:08.035Z","repository":{"id":40347478,"uuid":"274233698","full_name":"orange-cloudfoundry/promfetcher","owner":"orange-cloudfoundry","description":"Promfetcher was made for cloud foundry and the idea behind is to give ability to fetch  metrics from all app instances in a cloud foundry environment","archived":false,"fork":false,"pushed_at":"2025-04-09T18:44:44.000Z","size":20145,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-09T19:41:59.233Z","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/orange-cloudfoundry.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}},"created_at":"2020-06-22T20:19:40.000Z","updated_at":"2025-04-09T18:44:38.000Z","dependencies_parsed_at":"2023-12-28T19:39:15.931Z","dependency_job_id":"1d06bb13-2b1a-41f7-a39d-b0dd0592269a","html_url":"https://github.com/orange-cloudfoundry/promfetcher","commit_stats":null,"previous_names":[],"tags_count":241,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orange-cloudfoundry%2Fpromfetcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orange-cloudfoundry%2Fpromfetcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orange-cloudfoundry%2Fpromfetcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orange-cloudfoundry%2Fpromfetcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orange-cloudfoundry","download_url":"https://codeload.github.com/orange-cloudfoundry/promfetcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248358548,"owners_count":21090401,"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":"2025-03-08T13:27:28.331Z","updated_at":"2026-01-05T20:12:12.724Z","avatar_url":"https://github.com/orange-cloudfoundry.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Promfetcher\n\nPromfetcher was made for [Cloud Foundry] in order to expose [OpenMetrics] from all instances\nof an App in a Cloud Foundry environment.\n\nUser can retrieve the metrics by simply calling `/v1/apps/${org_name}/${space_name}/${app_name}/metrics`,\nor by the application route URL through `/v1/apps/metrics?route_url=my.route.com`,\nwhich will merge all the metrics from an App instances,\nthen add the following labels (similar to what can be found in the variable [`VCAP_APPLICATION`]):\n\n- `organization_id` - The GUID identifying the org where the app is deployed.\n- `organization_name` - The human-readable name of the org where the app is deployed.\n- `space_id` - The GUID identifying the space where the app is deployed.\n- `space_name` - The human-readable name of the space where the app is deployed.\n- `app_id` - The GUID identifying the app.\n- `app_name` - The name assigned to the app when it was pushed.\n- `index` - The index number of the app instance.\n- `instance_id` - (same as the `index`)\n- `instance` - The real IP address and port of the container running the App instance.\n\nIt is also a Cloud Foundry [service broker] able to expose an endpoint containing some system metrics\nfor applications without one.\n\n[Cloud Foundry]: https://cloudfoundry.org\n[service broker]: https://docs.cloudfoundry.org/services/overview.html\n[`VCAP_APPLICATION`]: https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION\n\n## Usage\n\n### Set up\n\nOn Cloud Foundry, you should deploy it through its corresponding [BOSH release]:\nhttps://github.com/orange-cloudfoundry/promfetcher-release\n\n[BOSH release]: https://bosh.io/releases/\n\n### Standard endpoint\n\nIf your Apps metrics are available on the `/metrics` path (as per [OpenMetrics] recommendations),\nyou have nothing else to do and you can retrieve App instances metrics by simply calling one of:\n\n- `promfetcher.example.net/v1/apps/{org_name}/{space_name}/{app_name}/metrics`\n- `promfetcher.example.net/v1/apps/{app_id}/metrics`\n- `promfetcher.example.net/v1/apps/metrics?app=\"[org_name]/[space_name]/[app_name]\"`\n- `promfetcher.example.net/v1/apps/metrics?app=\"[app_id]\"`\n- `promfetcher.example.net/v1/apps/{route.url.com}/metrics`\n- `promfetcher.example.net/v1/apps/metrics?route_url=\"[route.url.com]\"`\n\nTo retrieve only the metrics exposed from your application (without the Promfetcher sugar coating),\nuse `/only-app-metrics` instead of `/metrics`, i.e.:\n\n- `promfetcher.example.net/v1/apps/{org_name}/{space_name}/{app_name}/only-app-metrics`\n- `promfetcher.example.net/v1/apps/only-app-metrics?app=\"[app_id]\"`\n\n### Setting a custom endpoint\n\nAdd to your querystring the parameter `metric_path={/my-metrics/endpoint}`, i.e.:\n\n- `promfetcher.example.net/v1/apps/{org_name}/{space_name}/{app_name}/metrics?metric_path=/my-metrics/endpoint`\n\n### Pass HTTP headers to the App\n\nIf you do a request with headers, they are all passed to the App.\n\nThis is useful for authentication purpose, for example:\n\n1. I have an App with metrics on `/metrics` which is protected with HTTP Basic Auth\n2. You can perform curl: `curl https://username:password@promfetcher.example.net/v1/apps/my-app/metrics`\n3. HTTP Basic Auth headers are passed to the App, and you can retrieve the information\n   (note that Promfetcher does not store any data)\n\n## Under the hood\n\n### How does it work?\n\nPromfetcher only needs [NATS](https://nats.io/) an infrastructure that allows data exchange, segmented in the form of messages (We call this a \"message oriented middleware\"). Promfetcher subscribes to NATS in order to receive messages about routes and then manages its own routing table in memory.\n\nWhen asking metrics for an App, Promfetcher will asynchronously call all App instances\n(provided by the gorouter routing table) metrics endpoint and merge them together with new labels.\n\nExample, given an App with metrics from instance 0:\n\n```\ngo_memstats_mspan_sys_bytes{} 65536\n```\n\nAnd metrics from App instance 1:\n\n```\ngo_memstats_mspan_sys_bytes{} 5600\n```\n\nPromfetcher will merge them to:\n\n```\ngo_memstats_mspan_sys_bytes{organization_id=\"7d66c7e7-196a-40e5-a259-f5afaf6a56f4\",space_id=\"2ac205af-e18f-49a9-9a8b-48ef2bab2292\",app_id=\"621617db-9dd9-4211-8848-b245f3ea16b2\",organization_name=\"system\",space_name=\"tools\",app_name=\"app\",index=\"0\",instance_id=\"0\",instance=\"172.76.112.90:61038\"} 65536\ngo_memstats_mspan_sys_bytes{organization_id=\"7d66c7e7-196a-40e5-a259-f5afaf6a56f4\",space_id=\"2ac205af-e18f-49a9-9a8b-48ef2bab2292\",app_id=\"621617db-9dd9-4211-8848-b245f3ea16b2\",organization_name=\"system\",space_name=\"tools\",app_name=\"app\",index=\"1\",instance_id=\"1\",instance=\"172.76.112.91:61010\"} 65536\n```\n\n\n### Graceful shutdown\n\nUpon receiving `SIGINT`, `SIGTERM` or `SIGUSR1`, Promfetcher will stop listening to new connections\nand will wait up to 15 seconds to let the processing transactions a chance to finish before exiting.\n\n### Health Check\n\nThe default Promfetcher [Health Check] is of \"port\" type on `8080`.\n\nPromfetcher answers with an HTTP 200 status if healthy and HTTP 503 otherwise.\n\n[Health Check]: https://docs.cloudfoundry.org/devguide/deploy-apps/healthchecks.html\n\nThe administrator can send a `SIGUSR1` to force an unhealthy status in addition to stop it gracefully.\n\n### Promfetcher's internal metrics\n\nPromfetcher metrics are exposed on the [OpenMetrics] standard path `/metrics` and contains the following:\n\n[//]: # (curl -s https://promfetcher.example.net/metrics | sed -n 's/^# HELP \\\u0026#40;promfetch_[^ ]*\\\u0026#41;/- `\\1`:/p')\n\n- `promfetch_metric_fetch_failed_total`: Number of non-fetched metrics without be a normal error.\n- `promfetch_metric_fetch_success_total`: Number of fetched metrics succeeded for an App (App instances calls are summed).\n- `promfetch_latest_time_scrape_route`: Last time that route has been scraped, in seconds.\n- `promfetch_scrape_route_failed_total`: Number of non-fetched metrics without be an normal error.\n\n[OpenMetrics]: https://github.com/OpenObservability/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forange-cloudfoundry%2Fpromfetcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forange-cloudfoundry%2Fpromfetcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forange-cloudfoundry%2Fpromfetcher/lists"}