{"id":36687979,"url":"https://github.com/converged-computing/flux-metrics-api","last_synced_at":"2026-01-12T11:16:31.004Z","repository":{"id":170826509,"uuid":"647092558","full_name":"converged-computing/flux-metrics-api","owner":"converged-computing","description":"An experiment to make a custom metrics API (for Kubernetes) just for a Flux instance","archived":false,"fork":false,"pushed_at":"2024-07-23T19:45:09.000Z","size":42,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-28T00:12:54.005Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/converged-computing.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-05-30T03:35:48.000Z","updated_at":"2024-07-23T19:45:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"8723d851-dd6d-4cdf-94b4-1eaa47ebbaff","html_url":"https://github.com/converged-computing/flux-metrics-api","commit_stats":null,"previous_names":["converged-computing/flux-metrics-api"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/converged-computing/flux-metrics-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/converged-computing%2Fflux-metrics-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/converged-computing%2Fflux-metrics-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/converged-computing%2Fflux-metrics-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/converged-computing%2Fflux-metrics-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/converged-computing","download_url":"https://codeload.github.com/converged-computing/flux-metrics-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/converged-computing%2Fflux-metrics-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:58:46.209Z","status":"ssl_error","status_checked_at":"2026-01-12T10:58:42.742Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-01-12T11:16:30.937Z","updated_at":"2026-01-12T11:16:30.989Z","avatar_url":"https://github.com/converged-computing.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flux Metrics API\n\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n[![PyPI](https://img.shields.io/pypi/v/flux-metrics-api)](https://pypi.org/project/flux-metrics-api/)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12802643.svg)](https://doi.org/10.5281/zenodo.12802643)\n\nThis is an experiment to create a metrics API for Kubernetes that can be run directly from the Flux\nleader broker pod. We made this after creating [prometheus-flux](https://github.com/converged-computing/prometheus-flux)\nand wanting a more minimalist design. I'm not even sure it will work, but it's worth a try!\n\n## Usage\n\n### Install\n\nYou can install from pypi or from source:\n\n```bash\n$ python -m venv env\n$ source env/bin/activate\n$ pip install flux-metrics-api\n\n# or\n\n$ git clone https://github.com/converged-computing/flux-metrics-api\n$ cd flux-metrics-api\n$ pip install .\n# you can also do \"pip install -e .\"\n```\n\nThis will install the executable to your path, which might be your local user bin:\n\n```bash\n$ which flux-metric-api\n/home/vscode/.local/bin/flux-metrics-api\n```\n\nNote that the provided [.devcontainer](.devcontainer) includes an environment for VSCode where you have Flux\nand can install this and use ready to go!\n\n### Start\n\nYou'll want to be running in a Flux instance, as we need to connect to the broker handle.\n\n```bash\n$ flux start --test-size=4\n```\n\nAnd then start the server. This will use a default port and host (0.0.0.0:8443) that you can customize\nif desired.\n\n```bash\n$ flux-metrics-api start\n\n# customize the port or host\n$ flux-metrics-api start --port 9000 --host 127.0.0.1\n```\n\n#### SSL\n\nIf you want ssl (port 443) you can provide the path to a certificate and keyfile:\n\n```bash\n$ flux-metrics-api start --ssl-certfile /etc/certs/tls.crt --ssl-keyfile /etc/certs/tls.key\n```\n\nAn example of a full command we might run from within a pod:\n\n```bash\n$ flux-metrics-api start --port 8443 --ssl-certfile /etc/certs/tls.crt --ssl-keyfile /etc/certs/tls.key --namespace flux-operator --service-name custom-metrics-apiserver\n```\n\n#### On the fly custom metrics!\n\nIf you want to provide custom metrics, you can write a function in an external file that we will read it and add to the server.\nAs a general rule:\n\n - The name of the function will be the name of the custom metric\n - You can expect the only argument to be the flux handle\n - You'll need to do imports within your function to get them in scope\n\nThis likely can be improved upon, but is a start for now! We provide an [example file](example/custom-metrics.py). As an example:\n\n```bash\n$ flux-metrics-api start --custom-metric ./example/custom-metrics.py\n```\n\nAnd then test it:\n\n```bash\n$ curl -s http://localhost:8443/apis/custom.metrics.k8s.io/v1beta2/namespaces/flux-operator/metrics/my_custom_metric_name | jq\n```\n```console\n{\n  \"items\": [\n    {\n      \"metric\": {\n        \"name\": \"my_custom_metric_name\"\n      },\n      \"value\": 4,\n      \"timestamp\": \"2023-06-01T01:39:08+00:00\",\n      \"windowSeconds\": 0,\n      \"describedObject\": {\n        \"kind\": \"Service\",\n        \"namespace\": \"flux-operator\",\n        \"name\": \"custom-metrics-apiserver\",\n        \"apiVersion\": \"v1beta2\"\n      }\n    }\n  ],\n  \"apiVersion\": \"custom.metrics.k8s.io/v1beta2\",\n  \"kind\": \"MetricValueList\",\n  \"metadata\": {\n    \"selfLink\": \"/apis/custom.metrics.k8s.io/v1beta2\"\n  }\n}\n```\n\nSee `--help` to see other options available.\n\n### Endpoints\n\n#### Metric\n\n**GET /apis/custom.metrics.k8s.io/v1beta2/namespaces/\u003cnamespace\u003e/metrics/\u003cmetric_name\u003e**\n\nHere is an example to get the \"node_up_count\" metric:\n\n```bash\n curl -s http://localhost:8443/apis/custom.metrics.k8s.io/v1beta2/namespaces/flux-operator/metrics/node_up_count | jq\n```\n```console\n{\n  \"items\": [\n    {\n      \"metric\": {\n        \"name\": \"node_up_count\"\n      },\n      \"value\": 2,\n      \"timestamp\": \"2023-05-31T04:44:57+00:00\",\n      \"windowSeconds\": 0,\n      \"describedObject\": {\n        \"kind\": \"Service\",\n        \"namespace\": \"flux-operator\",\n        \"name\": \"custom-metrics-apiserver\",\n        \"apiVersion\": \"v1beta2\"\n      }\n    }\n  ],\n  \"apiVersion\": \"custom.metrics.k8s.io/v1beta2\",\n  \"kind\": \"MetricValueList\",\n  \"metadata\": {\n    \"selfLink\": \"/apis/custom.metrics.k8s.io/v1beta2\"\n  }\n}\n```\n\nThe following metrics are supported:\n\n - **node_up_count**: number of nodes up in the MiniCluster\n - **node_free_count**: number of nodes free in the MiniCluster\n - **node_cores_free_count**: number of node cores free in the MiniCluster\n - **node_cores_up_count**: number of node cores up in the MiniCluster\n - **job_queue_state_new_count**: number of new jobs in the queue\n - **job_queue_state_depend_count**: number of jobs in the queue in state \"depend\"\n - **job_queue_state_priority_count**: number of jobs in the queue in state \"priority\"\n - **job_queue_state_sched_count**: number of jobs in the queue in state \"sched\"\n - **job_queue_state_run_count**: number of jobs in the queue in state \"run\"\n - **job_queue_state_cleanup_count**: number of jobs in the queue in state \"cleanup\"\n - **job_queue_state_inactive_count**: number of jobs in the queue in state \"inactive\"\n\n\n### Docker\n\nWe have a docker container, which you can customize for your use case, but it's more intended to\nbe a demo. You can either build it yourself, or use our build.\n\n```bash\n$ docker build -t flux_metrics_api .\n$ docker run -it -p 8443:8443 flux_metrics_api\n```\nor\n\n```bash\n$ docker run -it -p 8443:8443 ghcr.io/converged-computing/flux-metrics-api\n```\n\n### Development\n\nNote that this is implemented in Python, but (I found this after) we could [also use Go](https://github.com/kubernetes-sigs/custom-metrics-apiserver).\nSpecifically, I found this repository useful to see the [spec format](https://github.com/kubernetes-sigs/custom-metrics-apiserver/blob/master/pkg/generated/openapi/custommetrics/zz_generated.openapi.go).\n\nYou can then open up the browser at [http://localhost:8443/metrics/](http://localhost:8443/metrics) to see\nthe metrics!\n\n## 😁️ Contributors 😁️\n\nWe use the [all-contributors](https://github.com/all-contributors/all-contributors)\ntool to generate a contributors graphic below.\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://vsoch.github.io\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/814322?v=4?s=100\" width=\"100px;\" alt=\"Vanessasaurus\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eVanessasaurus\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/converged-computing/flux-metrics-api/commits?author=vsoch\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## License\n\nHPCIC DevTools is distributed under the terms of the MIT license.\nAll new contributions must be made under this license.\n\nSee [LICENSE](https://github.com/converged-computing/flux-metrics-api/blob/main/LICENSE),\n[COPYRIGHT](https://github.com/converged-computing/flux-metrics-api/blob/main/COPYRIGHT), and\n[NOTICE](https://github.com/converged-computing/flux-metrics-api/blob/main/NOTICE) for details.\n\nSPDX-License-Identifier: (MIT)\n\nLLNL-CODE- 842614\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconverged-computing%2Fflux-metrics-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconverged-computing%2Fflux-metrics-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconverged-computing%2Fflux-metrics-api/lists"}