{"id":17511734,"url":"https://github.com/claws/prometheus_metrics_proto","last_synced_at":"2025-09-03T18:34:30.476Z","repository":{"id":40625769,"uuid":"81702094","full_name":"claws/prometheus_metrics_proto","owner":"claws","description":"Prometheus binary format metrics data structures for Python client libraries","archived":false,"fork":false,"pushed_at":"2020-04-16T11:18:04.000Z","size":41,"stargazers_count":4,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-03T15:56:49.157Z","etag":null,"topics":["prometheus","protobuf","python"],"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/claws.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}},"created_at":"2017-02-12T04:12:13.000Z","updated_at":"2021-05-02T04:16:23.000Z","dependencies_parsed_at":"2022-09-20T12:44:33.523Z","dependency_job_id":null,"html_url":"https://github.com/claws/prometheus_metrics_proto","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/claws/prometheus_metrics_proto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fprometheus_metrics_proto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fprometheus_metrics_proto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fprometheus_metrics_proto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fprometheus_metrics_proto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claws","download_url":"https://codeload.github.com/claws/prometheus_metrics_proto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fprometheus_metrics_proto/sbom","scorecard":{"id":285568,"data":{"date":"2025-08-11","repo":{"name":"github.com/claws/prometheus_metrics_proto","commit":"b0dc027ac62f94c7c7d5e7003d57bdabf872e66c"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Code-Review","score":1,"reason":"Found 1/7 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/claws/prometheus_metrics_proto/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/claws/prometheus_metrics_proto/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/claws/prometheus_metrics_proto/ci.yml/master?enable=pin","Warn: pipCommand not pinned by hash: tests/test-dist.bash:23","Warn: pipCommand not pinned by hash: tests/test-dist.bash:26","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:26","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:27","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:42","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   6 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":4,"reason":"6 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-48 / GHSA-fj7x-q9j7-g6q6","Warn: Project is vulnerable to: PYSEC-2022-43017 / GHSA-qwmp-2cf2-g9g6","Warn: Project is vulnerable to: PYSEC-2022-48 / GHSA-77rm-9x9h-xj3g","Warn: Project is vulnerable to: GHSA-8gq9-2x98-w8hf","Warn: Project is vulnerable to: GHSA-8qvm-5x2c-j2w7","Warn: Project is vulnerable to: PYSEC-2017-65 / GHSA-jwvw-v7c5-m82h"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 11 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T17:09:25.590Z","repository_id":40625769,"created_at":"2025-08-17T17:09:25.590Z","updated_at":"2025-08-17T17:09:25.590Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273490526,"owners_count":25115164,"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","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["prometheus","protobuf","python"],"created_at":"2024-10-20T05:09:46.877Z","updated_at":"2025-09-03T18:34:30.448Z","avatar_url":"https://github.com/claws.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build Status](https://github.com/claws/prometheus_metrics_proto/workflows/Build%20Workflow/badge.svg?branch=master) [![pypi](https://img.shields.io/pypi/v/prometheus_metrics_proto.svg)](https://pypi.python.org/pypi/prometheus_metrics_proto) ![License](https://img.shields.io/github/license/claws/prometheus_metrics_proto) ![pyversions](https://img.shields.io/pypi/pyversions/prometheus_metrics_proto) ![Style](https://img.shields.io/badge/code%20style-black-000000.svg)\n\n# prometheus_metrics_proto\n\nThe ``prometheus_metrics_proto`` package provides Prometheus Protobuf data\nstructures and a set of helper functions to assist generating Prometheus\nProtocol Buffer format metrics and serializing them in preparation for\nnetwork transfer.\n\nThe collection of metrics and the management of Summary Quantiles and\nHistogram Buckets are outside the scope of functionality provided by\nthis package.\n\nAn example of a project using ``prometheus_metrics_proto`` is\n[aioprometheus](https://github.com/claws/aioprometheus\u003e) which uses it\nwithin the the BinaryFormatter.\n\nThe Protocol Buffer specification used by ``prometheus_metrics_proto`` was\nobtained from the Prometheus [client model[(\u003chttps://github.com/prometheus/client_model/blob/master/metrics.proto\u003e)\nrepo.\n\n\n## Install\n\n```console\n$ pip install prometheus_metrics_proto\n```\n\n## Example\n\nThe ``prometheus_metrics_proto`` package provides helper functions to assist with\ngenerating Prometheus metrics objects.\n\nThe example below shows how these functions can be used to construct metrics\nand encode them into a format suitable to send to Prometheus server in a\nresponse.\n\n```python\n#!/usr/bin/env python\n\"\"\"\nThis script demonstrates the high level helper functions used to assist\ncreating various metrics kinds as well as how to encode the metrics into\na form that can be sent to Prometheus server.\n\"\"\"\n\nimport prometheus_metrics_proto as pmp\n\n\ndef main():\n\n    # Define some labels that we want added to all metrics. These labels are\n    # independent of the instance labels that define a metric as unique.\n    # These could be used to add hostname, app name, etc.\n    const_labels = {\"host\": \"examplehost\", \"app\": \"my_app\"}\n\n    # Create a Counter metric to track logged in users. This counter has\n    # 5 separate instances.\n    # We'll make use of the optional const_labels argument to add extra\n    # constant labels.\n    # We will also add a timestamp to the metric instances.\n    # We will request that the labels be sorted.\n    cm = pmp.create_counter(\n        \"logged_users_total\",\n        \"Logged users in the application.\",\n        (\n            ({\"country\": \"sp\", \"device\": \"desktop\"}, 520),\n            ({\"country\": \"us\", \"device\": \"mobile\"}, 654),\n            ({\"country\": \"uk\", \"device\": \"desktop\"}, 1001),\n            ({\"country\": \"de\", \"device\": \"desktop\"}, 995),\n            ({\"country\": \"zh\", \"device\": \"desktop\"}, 520),\n        ),\n        timestamp=True,\n        const_labels=const_labels,\n        ordered=True,\n    )\n\n    # Create a Gauge metric, similar to the counter above.\n    gm = pmp.create_gauge(\n        \"logged_users_total\",\n        \"Logged users in the application.\",\n        (\n            ({\"country\": \"sp\", \"device\": \"desktop\"}, 520),\n            ({\"country\": \"us\", \"device\": \"mobile\"}, 654),\n            ({\"country\": \"uk\", \"device\": \"desktop\"}, 1001),\n            ({\"country\": \"de\", \"device\": \"desktop\"}, 995),\n            ({\"country\": \"zh\", \"device\": \"desktop\"}, 520),\n        ),\n        timestamp=True,\n        const_labels=const_labels,\n        ordered=True,\n    )\n\n    # Now lets create a Summary and Histogram metric object. These forms\n    # of metrics are slightly more complicated.\n    #\n    # Remember, the collection of metrics and the management of Summary\n    # Quantiles and Histogram Buckets are outside the scope of\n    # functionality provided by this package.\n    #\n    # The following examples assume they are taking the data values from\n    # a management library that can also emit the sum and count fields\n    # expected for both Summary and Histogram metrics.\n\n    # Create a Summary metric. The values for a summary are slightly\n    # different to a Counter or Gauge. They are composed of a dict representing\n    # the various quantile values of the metric. The count and sum are\n    # expected to be present in this dict.\n    sm = pmp.create_summary(\n        \"request_payload_size_bytes\",\n        \"Request payload size in bytes.\",\n        (\n            ({\"route\": \"/\"}, {0.5: 4.0, 0.9: 5.2, 0.99: 5.2, \"sum\": 25.2, \"count\": 4}),\n            (\n                {\"route\": \"/data\"},\n                {0.5: 4.0, 0.9: 5.2, 0.99: 5.2, \"sum\": 25.2, \"count\": 4},\n            ),\n        ),\n        timestamp=True,\n        const_labels=const_labels,\n        ordered=True,\n    )\n\n    # Create a Histogram metric. The values for a histogram are slightly\n    # different to a Counter or Gauge. They are composed of a dict representing\n    # the various bucket values of the metric. The cumulative count and sum\n    # values are expected to be present in this dict.\n    #\n    # Libraries manageing buckets typically have add a POS_INF upper bound to\n    # catch values beyond the largest bucket bound. Simulate this behavior in\n    # the data below.\n    POS_INF = float(\"inf\")\n\n    hm = pmp.create_histogram(\n        \"request_latency_seconds\",\n        \"Request latency in seconds.\",\n        (\n            (\n                {\"route\": \"/\"},\n                {5.0: 3, 10.0: 2, 15.0: 1, POS_INF: 0, \"count\": 6, \"sum\": 46.0},\n            ),\n            (\n                {\"route\": \"/data\"},\n                {5.0: 3, 10.0: 2, 15.0: 1, POS_INF: 0, \"count\": 6, \"sum\": 46.0},\n            ),\n        ),\n        timestamp=True,\n        const_labels=const_labels,\n        ordered=True,\n    )\n\n    # Serialize a sequence of metrics into a payload suitable for network\n    # transmission.\n    input_metrics = (cm, gm, sm, hm)\n    payload = pmp.encode(*input_metrics)\n    assert isinstance(payload, bytes)\n\n    # De-serialize the payload into a sequence of MetricsFamily objects.\n    recovered_metrics = pmp.decode(payload)\n\n    # Confirm that the round trip re-produced the same number of metrics\n    # and that the metrics are identical.\n    assert len(recovered_metrics) == len(input_metrics)\n    for recovered_metric, input_metric in zip(recovered_metrics, input_metrics):\n        assert recovered_metric == input_metric\n\n    for metric in input_metrics:\n        print(metric)\n\n\nif __name__ == \"__main__\":\n    main()\n```\n\nIf you simply want to access the Prometheus Protocol Buffer objects directly\nand generate instances yourself simply import them from the package as\nfollows:\n\n```python\nfrom prometheus_metrics_proto import (\n    COUNTER,\n    GAUGE,\n    SUMMARY,\n    HISTOGRAM,\n    Bucket,\n    Counter,\n    Gauge,\n    Histogram,\n    LabelPair,\n    Metric,\n    MetricFamily,\n    Summary,\n    Quantile)\n```\n\n## License\n\nThis project is released under the MIT license.\n\n\n## Background\n\nCreating metrics that can be ingested by Prometheus is relatively simple,\nbut does require knowledge of how they are composed.\n\nThe Prometheus server expects to ingest ``MetricsFamily`` objects when it\nscrapes an endpoint exposing Protocol Buffer format data.\n\nA ``MetricFamily`` object is a container that holds the metric name, a help\nstring and ``Metric`` objects. Each ``MetricFamily`` within the same\nexposition must have a unique name.\n\nA ``Metric`` object is a container for a single instance of a specific metric\ntype. Valid metric types are Counter, Gauge, Histogram and Summary. Each\n``Metric`` within the same ``MetricFamily`` must have a unique set of\n``LabelPair`` fields. This is commonly referred to as multi-dimensional metrics.\n\n\n## Development\n\n\n### Get the source\n\n```console\n$ git clone git@github.com:claws/prometheus_metrics_proto.git\n$ cd prometheus_metrics_proto\n```\n\n### Setup\n\nThe best way to work on `prometheus_metrics_proto` is to create a virtual env.\nThis isolates your work from other project's dependencies and ensures that any\ncommands are pointing at the correct tools.\n\n\u003e You may need to explicitly specify which Python to use if you have\n\u003e multiple Python's available on your system  (e.g. ``python3``,\n\u003e ``python3.8``).\n\n```console\n$ python3 -m venv venv --prompt pmp\n$ source venv/bin/activate\n(pmp) $\n(pmp) $ pip install pip --upgrade\n```\n\n\u003e The following steps assume you are operating in a virtual environment.\n\nTo exit the virtual environment simply type ``deactivate``.\n\n### Install Development Environment\n\nRules in the convenience Makefile depend on the development dependencies\nbeing installed. Install the developmental dependencies using ``pip``. Then\ninstall the `prometheus_metrics_proto` package (and its normal dependencies)\nin a way that allows you to edit the code after it is installed so that any\nchanges take effect immediately.\n\n```console\n(pmp) $ pip install -r requirements.dev.txt\n(pmp) $ pip install -e .\n```\n\nFamiliarise yourself with the convenience Makefile rules by running make\nwithout any rule specified.\n\n```console\n$ make\n```\n\n### Code Style\n\nThis project uses the Black code style formatter for consistent code style.\nA Makefile convenience rule is available to apply code style compliance.\n\n```console\n(pmp) $ make style\n```\n\n### Test\n\nThe easiest method to run all of the unit tests is to run the ``make test``\nrule from the top level directory. This runs the standard library ``unittest``\ntool which discovers all the unit tests and runs them.\n\n```console\n(pmp) $ make test\n```\n\nor\n\n```console\n(pmp) $ make test-verbose\n```\n\n### Coverage\n\nA Makefile convenience rule is available to check how much of the code is\ncovered by tests.\n\n```console\n(pmp) $ make coverage\n```\n\nThe test code coverage report can be found `here \u003chtmlcov/index.html\u003e`_\n\n\n### Regenerate\n\nThe project has placed the code stub (``prometheus_metrics_pb2.py``),\ngenerated by the Google Protocol Buffers code generation tool, under source\ncontrol.\n\nIf this file needs to be regenerated in the future use the following procedure:\n\n```console\n(pmp) $ make regenerate\n```\n\n## Release Process\n\nThe following steps are used to make a new software release:\n\n- Ensure that the version label in ``__init__.py`` is updated.\n\n- Create the distribution. This project produces an artefact called a pure\n  Python wheel. Only Python3 is supported by this package.\n\n  ```console\n  (pmp) $ make dist\n  ```\n\n- Test distribution. This involves creating a virtual environment, installing\n  the distribution in it and running the tests. These steps have been captured\n  for convenience in a Makefile rule.\n\n  ```console\n  (pmp) $ make dist-test\n  ```\n\n- Upload to PyPI.\n\n  ```console\n  (pmp) $ make dist-upload\n  ```\n\n- Create and push a repo tag to Github.\n\n  ```console\n  git tag YY.MM.MICRO -m \"A meaningful release tag comment\"\n  git tag  # check release tag is in list\n  git push --tags origin master\n  ```\n\n  - Github will create a release tarball at:\n\n    \u003e https://github.com/{username}/{repo}/tarball/{tag}.tar.gz\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fprometheus_metrics_proto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaws%2Fprometheus_metrics_proto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fprometheus_metrics_proto/lists"}