zhmc-prometheus-exporter


Namezhmc-prometheus-exporter JSON
Version 1.6.0 PyPI version JSON
download
home_pagehttps://github.com/zhmcclient/zhmc-prometheus-exporter
SummaryIBM Z HMC Prometheus Exporter
upload_time2024-04-03 10:47:39
maintainerAndreas Maier, Kathir Velusamy
docs_urlNone
authorJakob Naucke
requires_python>=3.6
licenseApache License, Version 2.0
keywords
VCS
bugtrack_url
requirements zhmcclient prometheus-client prometheus-client urllib3 jsonschema Jinja2 Jinja2 PyYAML PyYAML pyrsistent pyrsistent
Travis-CI
coveralls test coverage
            .. Copyright 2018 IBM Corp. All Rights Reserved.
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
..    http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

IBM Z HMC Prometheus Exporter
=============================

.. image:: https://img.shields.io/pypi/v/zhmc-prometheus-exporter.svg
    :target: https://pypi.python.org/pypi/zhmc-prometheus-exporter/
    :alt: Version on Pypi

.. image:: https://github.com/zhmcclient/zhmc-prometheus-exporter/actions/workflows/test.yml/badge.svg?branch=master
    :target: https://github.com/zhmcclient/zhmc-prometheus-exporter/actions/workflows/test.yml?query=branch%3Amaster
    :alt: Test status (master)

.. image:: https://readthedocs.org/projects/zhmc-prometheus-exporter/badge/?version=latest
    :target: https://readthedocs.org/projects/zhmc-prometheus-exporter/builds/
    :alt: Docs status (master)

.. image:: https://coveralls.io/repos/github/zhmcclient/zhmc-prometheus-exporter/badge.svg?branch=master
    :target: https://coveralls.io/github/zhmcclient/zhmc-prometheus-exporter?branch=master
    :alt: Test coverage (master)

The **IBM Z HMC Prometheus Exporter** is a `Prometheus exporter`_ written in
Python that retrieves metrics from the `IBM Z`_ Hardware Management Console (HMC)
and exports them to the `Prometheus`_ monitoring system.

The exporter supports all metrics provided by the Z HMC and in addition a number
of useful metrics that are based on properties of HMC resources (e.g. memory or
CPU weight of LPARs). The resource property based metrics are obtained in the
background via change notifications emitted by the HMC and via asynchronous
retrieval for properties where change notifications are not supported. This
keeps the time for providing the metric data to Prometheus short (sub-second to
a few seconds).

The exporter attempts to stay up as much as possible, for example it performs
automatic session renewals with the HMC if the logon session expires, and it
survives HMC reboots and automatically picks up metrics collection again once
the HMC come back up.

.. _IBM Z: https://www.ibm.com/it-infrastructure/z
.. _Prometheus exporter: https://prometheus.io/docs/instrumenting/exporters/
.. _Prometheus: https://prometheus.io

Documentation
-------------

* `Documentation`_
* `Change log`_

.. _Documentation: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/
.. _Change log: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/changes.html

Quickstart
----------

* Install the exporter and all of its Python dependencies as follows:

  .. code-block:: bash

      $ pip install zhmc-prometheus-exporter

* Provide an *HMC credentials file* for use by the exporter.

  The HMC credentials file tells the exporter which HMC to talk to for
  obtaining metrics, and which userid and password to use for logging on to
  the HMC.

  It also defines whether HTTP or HTTPS is used for Prometheus, and HTTPS
  related certificates and keys.

  Download the `sample HMC credentials file`_ as ``hmccreds.yaml`` and edit
  that copy accordingly.

  For details, see `HMC credentials file`_.

.. _HMC credentials file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#hmc-credentials-file
.. _sample HMC credentials file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#sample-hmc-credentials-file

* Provide a *metric definition file* for use by the exporter.

  The metric definition file maps the metrics returned by the HMC to metrics
  exported to Prometheus.

  Furthermore, the metric definition file allows optimizing the access time to
  the HMC by disabling the fetching of metrics that are not needed.

  Download the `sample metric definition file`_ as ``metrics.yaml``. It can
  be used as it is and will have all metrics enabled and mapped properly. You
  only need to edit the file if you want to adjust the metric names, labels, or
  metric descriptions, or if you want to optimize access time by disabling
  metrics not needed.

  For details, see `Metric definition file`_.

.. _Metric definition file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#metric-definition-file
.. _sample metric definition file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#sample-metric-definition-file

* Run the exporter as follows:

  .. code-block:: bash

      $ zhmc_prometheus_exporter -c hmccreds.yaml -m metrics.yaml
      Exporter is up and running on port 9291

  Depending on the number of CPCs managed by your HMC, and dependent on how many
  metrics are enabled, it will take some time until the exporter reports to be
  up and running. You can see what it does in the mean time by using the ``-v``
  option. Subsequent requests to the exporter will be sub-second.

* Direct your web browser at http://localhost:9291 (or https://localhost:9291
  when using HTTPS) to see the exported Prometheus metrics. Refreshing the
  browser will update the metrics.

Reporting issues
----------------

If you encounter a problem, please report it as an `issue on GitHub`_.

.. _issue on GitHub: https://github.com/zhmcclient/zhmc-prometheus-exporter/issues

License
-------

This package is licensed under the `Apache 2.0 License`_.

.. _Apache 2.0 License: http://apache.org/licenses/LICENSE-2.0

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/zhmcclient/zhmc-prometheus-exporter",
    "name": "zhmc-prometheus-exporter",
    "maintainer": "Andreas Maier, Kathir Velusamy",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "maiera@de.ibm.com, kathir.velu@in.ibm.com",
    "keywords": null,
    "author": "Jakob Naucke",
    "author_email": "jakob.naucke@ibm.com",
    "download_url": "https://files.pythonhosted.org/packages/59/90/ad5f527f608ab067898e60e083245f0a589e5b6518f1a652b7b835d95593/zhmc_prometheus_exporter-1.6.0.tar.gz",
    "platform": "any",
    "description": ".. Copyright 2018 IBM Corp. All Rights Reserved.\n..\n.. Licensed under the Apache License, Version 2.0 (the \"License\");\n.. you may not use this file except in compliance with the License.\n.. You may obtain a copy of the License at\n..\n..    http://www.apache.org/licenses/LICENSE-2.0\n..\n.. Unless required by applicable law or agreed to in writing, software\n.. distributed under the License is distributed on an \"AS IS\" BASIS,\n.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n.. See the License for the specific language governing permissions and\n.. limitations under the License.\n\nIBM Z HMC Prometheus Exporter\n=============================\n\n.. image:: https://img.shields.io/pypi/v/zhmc-prometheus-exporter.svg\n    :target: https://pypi.python.org/pypi/zhmc-prometheus-exporter/\n    :alt: Version on Pypi\n\n.. image:: https://github.com/zhmcclient/zhmc-prometheus-exporter/actions/workflows/test.yml/badge.svg?branch=master\n    :target: https://github.com/zhmcclient/zhmc-prometheus-exporter/actions/workflows/test.yml?query=branch%3Amaster\n    :alt: Test status (master)\n\n.. image:: https://readthedocs.org/projects/zhmc-prometheus-exporter/badge/?version=latest\n    :target: https://readthedocs.org/projects/zhmc-prometheus-exporter/builds/\n    :alt: Docs status (master)\n\n.. image:: https://coveralls.io/repos/github/zhmcclient/zhmc-prometheus-exporter/badge.svg?branch=master\n    :target: https://coveralls.io/github/zhmcclient/zhmc-prometheus-exporter?branch=master\n    :alt: Test coverage (master)\n\nThe **IBM Z HMC Prometheus Exporter** is a `Prometheus exporter`_ written in\nPython that retrieves metrics from the `IBM Z`_ Hardware Management Console (HMC)\nand exports them to the `Prometheus`_ monitoring system.\n\nThe exporter supports all metrics provided by the Z HMC and in addition a number\nof useful metrics that are based on properties of HMC resources (e.g. memory or\nCPU weight of LPARs). The resource property based metrics are obtained in the\nbackground via change notifications emitted by the HMC and via asynchronous\nretrieval for properties where change notifications are not supported. This\nkeeps the time for providing the metric data to Prometheus short (sub-second to\na few seconds).\n\nThe exporter attempts to stay up as much as possible, for example it performs\nautomatic session renewals with the HMC if the logon session expires, and it\nsurvives HMC reboots and automatically picks up metrics collection again once\nthe HMC come back up.\n\n.. _IBM Z: https://www.ibm.com/it-infrastructure/z\n.. _Prometheus exporter: https://prometheus.io/docs/instrumenting/exporters/\n.. _Prometheus: https://prometheus.io\n\nDocumentation\n-------------\n\n* `Documentation`_\n* `Change log`_\n\n.. _Documentation: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/\n.. _Change log: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/changes.html\n\nQuickstart\n----------\n\n* Install the exporter and all of its Python dependencies as follows:\n\n  .. code-block:: bash\n\n      $ pip install zhmc-prometheus-exporter\n\n* Provide an *HMC credentials file* for use by the exporter.\n\n  The HMC credentials file tells the exporter which HMC to talk to for\n  obtaining metrics, and which userid and password to use for logging on to\n  the HMC.\n\n  It also defines whether HTTP or HTTPS is used for Prometheus, and HTTPS\n  related certificates and keys.\n\n  Download the `sample HMC credentials file`_ as ``hmccreds.yaml`` and edit\n  that copy accordingly.\n\n  For details, see `HMC credentials file`_.\n\n.. _HMC credentials file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#hmc-credentials-file\n.. _sample HMC credentials file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#sample-hmc-credentials-file\n\n* Provide a *metric definition file* for use by the exporter.\n\n  The metric definition file maps the metrics returned by the HMC to metrics\n  exported to Prometheus.\n\n  Furthermore, the metric definition file allows optimizing the access time to\n  the HMC by disabling the fetching of metrics that are not needed.\n\n  Download the `sample metric definition file`_ as ``metrics.yaml``. It can\n  be used as it is and will have all metrics enabled and mapped properly. You\n  only need to edit the file if you want to adjust the metric names, labels, or\n  metric descriptions, or if you want to optimize access time by disabling\n  metrics not needed.\n\n  For details, see `Metric definition file`_.\n\n.. _Metric definition file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#metric-definition-file\n.. _sample metric definition file: https://zhmc-prometheus-exporter.readthedocs.io/en/stable/usage.html#sample-metric-definition-file\n\n* Run the exporter as follows:\n\n  .. code-block:: bash\n\n      $ zhmc_prometheus_exporter -c hmccreds.yaml -m metrics.yaml\n      Exporter is up and running on port 9291\n\n  Depending on the number of CPCs managed by your HMC, and dependent on how many\n  metrics are enabled, it will take some time until the exporter reports to be\n  up and running. You can see what it does in the mean time by using the ``-v``\n  option. Subsequent requests to the exporter will be sub-second.\n\n* Direct your web browser at http://localhost:9291 (or https://localhost:9291\n  when using HTTPS) to see the exported Prometheus metrics. Refreshing the\n  browser will update the metrics.\n\nReporting issues\n----------------\n\nIf you encounter a problem, please report it as an `issue on GitHub`_.\n\n.. _issue on GitHub: https://github.com/zhmcclient/zhmc-prometheus-exporter/issues\n\nLicense\n-------\n\nThis package is licensed under the `Apache 2.0 License`_.\n\n.. _Apache 2.0 License: http://apache.org/licenses/LICENSE-2.0\n",
    "bugtrack_url": null,
    "license": "Apache License, Version 2.0",
    "summary": "IBM Z HMC Prometheus Exporter",
    "version": "1.6.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/zhmcclient/zhmc-prometheus-exporter/issues",
        "Change Log": "https://zhmc-prometheus-exporter.readthedocs.io/en/stable/changes.html",
        "Documentation": "https://zhmc-prometheus-exporter.readthedocs.io/en/stable/",
        "Homepage": "https://github.com/zhmcclient/zhmc-prometheus-exporter"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "00d86edbe5ac4b5e0898d374d354d0ceed7769bb96c00eeb53a81e15d58e7717",
                "md5": "2cae7f018731ce856106ba2f921a8eba",
                "sha256": "0722f5c552eaa89ddda3d1d65e33a4823531c9fa7bb53d2d92ab0abbdd680d86"
            },
            "downloads": -1,
            "filename": "zhmc_prometheus_exporter-1.6.0-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2cae7f018731ce856106ba2f921a8eba",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">=3.6",
            "size": 33605,
            "upload_time": "2024-04-03T10:47:37",
            "upload_time_iso_8601": "2024-04-03T10:47:37.447009Z",
            "url": "https://files.pythonhosted.org/packages/00/d8/6edbe5ac4b5e0898d374d354d0ceed7769bb96c00eeb53a81e15d58e7717/zhmc_prometheus_exporter-1.6.0-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "5990ad5f527f608ab067898e60e083245f0a589e5b6518f1a652b7b835d95593",
                "md5": "e9bfc271067ba4228a037a3180456427",
                "sha256": "e9e3fc64d45d7aaa494ca4e62c55dc862a29c435f7ceb9e5137cb326b2bc24e1"
            },
            "downloads": -1,
            "filename": "zhmc_prometheus_exporter-1.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "e9bfc271067ba4228a037a3180456427",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 38236,
            "upload_time": "2024-04-03T10:47:39",
            "upload_time_iso_8601": "2024-04-03T10:47:39.475508Z",
            "url": "https://files.pythonhosted.org/packages/59/90/ad5f527f608ab067898e60e083245f0a589e5b6518f1a652b7b835d95593/zhmc_prometheus_exporter-1.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-04-03 10:47:39",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "zhmcclient",
    "github_project": "zhmc-prometheus-exporter",
    "travis_ci": true,
    "coveralls": true,
    "github_actions": true,
    "requirements": [
        {
            "name": "zhmcclient",
            "specs": [
                [
                    ">=",
                    "1.14.0"
                ]
            ]
        },
        {
            "name": "prometheus-client",
            "specs": [
                [
                    ">=",
                    "0.17.1"
                ]
            ]
        },
        {
            "name": "prometheus-client",
            "specs": [
                [
                    ">=",
                    "0.19.0"
                ]
            ]
        },
        {
            "name": "urllib3",
            "specs": [
                [
                    ">=",
                    "1.26.18"
                ]
            ]
        },
        {
            "name": "jsonschema",
            "specs": [
                [
                    ">=",
                    "3.2.0"
                ]
            ]
        },
        {
            "name": "Jinja2",
            "specs": [
                [
                    ">=",
                    "3.0.3"
                ]
            ]
        },
        {
            "name": "Jinja2",
            "specs": [
                [
                    ">=",
                    "3.1.3"
                ]
            ]
        },
        {
            "name": "PyYAML",
            "specs": [
                [
                    "!=",
                    "5.4.0"
                ],
                [
                    "!=",
                    "5.4.1"
                ],
                [
                    ">=",
                    "5.3.1"
                ]
            ]
        },
        {
            "name": "PyYAML",
            "specs": [
                [
                    "!=",
                    "6.0.0"
                ],
                [
                    "!=",
                    "5.4.0"
                ],
                [
                    "!=",
                    "5.4.1"
                ],
                [
                    ">=",
                    "5.3.1"
                ]
            ]
        },
        {
            "name": "pyrsistent",
            "specs": [
                [
                    ">=",
                    "0.17.3"
                ]
            ]
        },
        {
            "name": "pyrsistent",
            "specs": [
                [
                    ">=",
                    "0.18.1"
                ]
            ]
        }
    ],
    "lcname": "zhmc-prometheus-exporter"
}
        
Elapsed time: 0.35121s