Metadata-Version: 1.1
Name: hanadb-exporter
Version: 0.7.4
Summary: SAP HANA database data exporter
Home-page: UNKNOWN
Author: xarbulu
Author-email: xarbulu@suse.de
License: 
                                 Apache License
                           Version 2.0, January 2004
                        https://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   Copyright 2019-2020 SUSE LLC

   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

       https://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.

Description: # SAP HANA Database exporter
        
        [![Exporter CI](https://github.com/SUSE/hanadb_exporter/workflows/Exporter%20CI/badge.svg)](https://github.com/SUSE/hanadb_exporter/actions?query=workflow%3A%22Exporter+CI%22)
        [![Dashboards CI](https://github.com/SUSE/hanadb_exporter/workflows/Dashboards%20CI/badge.svg)](https://github.com/SUSE/hanadb_exporter/actions?query=workflow%3A%22Dashboards+CI%22)
        
        Prometheus exporter written in Python, to export SAP HANA database metrics. The
        project is based in the official prometheus exporter: [prometheus_client](https://github.com/prometheus/client_python).
        
        The exporter is able to export the metrics from more than 1 database/tenant if the `multi_tenant` option is enabled in the configuration file (enabled by default).
        
        The labels `sid` (system identifier), `insnr` (instance number), `database_name` (database name) and `host` (machine hostname) will be exported for all the metrics.
        
        
        ## Prerequisites
        
        1. A running and reachable SAP HANA database (single or multi container). Running the exporter in the
        same machine where the HANA database is running is recommended. Ideally each database
        should be monitored by one exporter.
        
        2. A SAP HANA Connector, for that, you have two options:
          - [`dbapi` (SAP/official)](https://help.sap.com/viewer/1efad1691c1f496b8b580064a6536c2d/Cloud/en-US/39eca89d94ca464ca52385ad50fc7dea.html)
          - [`pyhdb` (unofficial/open source)](https://github.com/SAP/PyHDB)
        
        The installation of the connector is covered in the [Installation](#installation) section.
        
        3. Some metrics are collected on the HANA monitoring views by the [SAP Host agent](https://help.sap.com/saphelp_nwpi711/helpdata/en/21/98c443122744efae67c0352033691d/frameset.htm). Make sure to have it installed and running to have access to all the monitoring metrics.
        
        
        ## Metrics file
        
        The exporter uses an additional file to know the metrics that are going to be exported. Here more information about the [metrics file](./docs/METRICS.md).
        
        ## Installation
        
        The project can be installed in many ways, including but not limited to:
        
        1. [RPM](#rpm)
        2. [Manual clone](#manual-clone)
        
        ### RPM
        
        On openSUSE or SUSE Linux Enterprise use `zypper` package manager:
        ```shell
        zypper install prometheus-hanadb_exporter
        ```
        
        Find the latest development repositories at [SUSE's Open Build Service](https://build.opensuse.org/package/show/network:ha-clustering:sap-deployments:devel/prometheus-hanadb_exporter).
        
        ### Manual clone
        
        > The exporter is developed to be used with Python3.\
        > The usage of a virtual environment is recommended.
        
        ```
        git clone https://github.com/SUSE/hanadb_exporter
        cd hanadb_exporter # project root folder
        virtualenv virt
        source virt/bin/activate
        # uncomment one of the next two options (to use hdbcli, you will need to have the HANA client folder where this python package is available)
        # pip install pyhdb
        # pip install path-to-hdbcli-N.N.N.tar.gaz
        pip install .
        # pip install -e . # To install in development mode
        # deactivate # to exit from the virtualenv
        ```
        
        If you prefer, you can install the PyHDB SAP HANA connector as a RPM package doing (example for Tumbleweed, but available for other versions):
        
        ```
        # All the commands must be executed as root user
        zypper addrepo https://download.opensuse.org/repositories/network:/ha-clustering:/sap-deployments:/devel/openSUSE_Tumbleweed/network:ha-clustering:sap-deployments:devel.repo
        zypper ref
        zypper in python3-PyHDB
        ```
        
        ## Configuring the exporter
        
        Create the `config.json` configuration file.
        An example of `config.json` available in [config.json.example](config.json.example). Here the most
        important items in the configuration file:
          - `listen_address`: Address where the prometheus exporter will be exposed (0.0.0.0 by default).
          - `exposition_port`: Port where the prometheus exporter will be exposed (9968 by default).
          - `multi_tenant`: Export the metrics from other tenants. To use this the connection must be done with the System Database (port 30013).
          - `timeout`: Timeout to connect to the database. After this time the app will fail (even in daemon mode).
          - `hana.host`: Address of the SAP HANA database.
          - `hana.port`: Port where the SAP HANA database is exposed.
          - `hana.userkey`: Stored user key. This is the secure option if you don't want to have the password in the configuration file. The `userkey` and `user/password` are self exclusive being the first the default if both options are set.
          - `hana.user`: An existing user with access right to the SAP HANA database.
          - `hana.password`: Password of an existing user.
          - `hana.ssl`: Enable SSL connection (False by default). Only available for `dbapi` connector
          - `hana.ssl_validate_cert`: Enable SSL certification validation. This field is required by HANA cloud. Only available for `dbapi` connector
          - `hana.aws_secret_name`: The secret name containing the username and password. This is a secure option to use AWS secrets manager if SAP HANA database is stored on AWS. `aws_secret_name` and `user/password` are self exclusive, `aws_secret_name` is the default if both options are set.
          - `logging.config_file`: Python logging system configuration file (by default WARN and ERROR level messages will be sent to the syslog)
          - `logging.log_file`: Logging file (/var/log/hanadb_exporter.log by default)
        
        The logging configuration file follows the python standard logging system style: [Python logging](https://docs.python.org/3/library/logging.config.html).
        
        Using the default [configuration file](./logging_config.ini), it will redirect the logs to the file assigned in the [json configuration file](./config.json.example) and to the syslog (only logging level up to WARNING).
        
        ### Using the stored user key
        
        This is the recommended option if we want to keep the database secure (for development environments the `user/password` with `SYSTEM` user can be used as it's faster to setup).
        To use the `userkey` option the `dbapi` must be installed (usually stored in `/hana/shared/PRD/hdbclient/hdbcli-N.N.N.tar.gz` and installable with pip3).
        It cannot be used from other different client (the key is stored in the client itself). This will raise the `hdbcli.dbapi.Error: (-10104, 'Invalid value for KEY')` error.
        For that a new stored user key must be created with the user that is running python. For that (please, notice that the `hdbclient` is the same as the `dbapi` python package):
        ```
        /hana/shared/PRD/hdbclient/hdbuserstore set yourkey host:30013@SYSTEMDB hanadb_exporter pass
        ```
        
        ### Using AWS Secrets Manager
        
        If SAP HANA database is stored on AWS EC2 instance, this is a secure option to store the `user/password` without having them in the configuration file. 
        To use this option:
        - Create a [secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) in key/value pairs format, specify Key `username` and then for Value enter the database user. Add a second Key `password` and then for Value enter the password.
        For the secret name, enter a name for your secret, and pass that name in the configuration file as a value for `aws_secret_name` item. Secret json example:
        
        ```
        {
          "username": "database_user",
          "password": "database_password"
        }
        ```
        - Allow read-only access from EC2 IAM role to the secret by attaching a [resource-based policy](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-based-policies.html) to the secret. Policy Example:
        ```
        {
          "Version" : "2012-10-17",
          "Statement" : [
            {
              "Effect": "Allow",
              "Principal": {"AWS": "arn:aws:iam::123456789012:role/EC2RoleToAccessSecrets"},
              "Action": "secretsmanager:GetSecretValue",
              "Resource": "*",
            }
          ]
        }
        ```
        
        
        
        Some tips:
        - Set `SYSTEMDB` as default database, this way the exporter will know where to get the tenants data.
        - Don't use the stored user key created for the backup as this is created using the sidadm user.
        - The usage of a user with access only to the monitoring tables is recommended instead of using SYSTEM user.
        - If a user with monitoring role is used the user must exist in all the databases (SYSTEMDB+tenants).
        
        ### Create a new user with monitoring role
        Run the next commands to create a user with moniroting roles (**the commands must be executed in all the databases**):
        ```
        su - prdadm
        hdbsql -u SYSTEM -p pass -d SYSTEMDB #(PRD for the tenant in this example)
        CREATE USER HANADB_EXPORTER_USER PASSWORD MyExporterPassword NO FORCE_FIRST_PASSWORD_CHANGE;
        CREATE ROLE HANADB_EXPORTER_ROLE;
        GRANT MONITORING TO HANADB_EXPORTER_ROLE;
        GRANT HANADB_EXPORTER_ROLE TO HANADB_EXPORTER_USER;
        ```
        
        ## Running the exporter
        
        Start the exporter by running the following command:
        ```
        hanadb_exporter -c config.json -m metrics.json
        # Or
        python3 hanadb_exporter/main.py -c config.json -m metrics.json
        ```
        
        If a `config.json` configuration file is stored in `/etc/hanadb_exporter` the exporter can be started with the next command too:
        ```
        hanadb_exporter --identifier config # Notice that the identifier matches with the config file without extension
        ```
        
        ### Running as a daemon
        
        The hanadb_exporter can be executed using `systemd`. For that, the best option is to install the project using the rpm package as described in [Installation](#installation).
        
        After that we need to create the configuration file as `/etc/hanadb_exporter/my-exporter.json` (the name of the file is relevant as we will use it to start the daemon).
        The [config.json.example](./config.json.example) can be used as example (the example file is stored in `/usr/etc/hanadb_exporter` folder too).
        
        The default [metrics file](./metrics.json) is stored in `/usr/etc/hanadb_exporter/metrics.json`. If a new `metrics.json` is stored in `/etc/hanadb_exporter` this will be used.
        
        The logging configuration file can be updated as well to customize changing the new configuration file `logging.config_file` entry (default one available in `/usr/etc/hanadb_exporter/logging_config.ini`).
        
        Now, the exporter can be started as a daemon. As we can have multiple `hanadb_exporter` instances running in one machine, the service is created using a template file, so an extra information must be given to `systemd` (this is done adding the `@` keyword after the service name together with the name of the configuration file created previously in `/etc/hanadb_exporter/{name}.json`):
        ```
        # All the command must be executed as root user
        systemctl start prometheus-hanadb_exporter@my-exporter
        # Check the status with
        systemctl status prometheus-hanadb_exporter@my-exporter
        # Enable the exporter to be started at boot time
        systemctl enable prometheus-hanadb_exporter@my-exporter
        ```
        
        ## License
        
        See the [LICENSE](LICENSE) file for license rights and limitations.
        
        ## Authors
        
        - Kristoffer Gronlund (kgronlund@suse.com)
        - Xabier Arbulu Insausti (xarbulu@suse.com)
        - Ayoub Belarbi (abelarbi@suse.com)
        - Diego Akechi (dakechi@suse.com)
        
        ## Reviewers
        
        *Pull request* preferred reviewers for this project:
        - Kristoffer Gronlund (kgronlund@suse.com)
        - Xabier Arbulu Insausti (xarbulu@suse.com)
        - Ayoub Belarbi (abelarbi@suse.com)
        
        ## References
        
        https://prometheus.io/docs/instrumenting/writing_exporters/
        
        https://prometheus.io/docs/practices/naming/
        
        http://sap.optimieren.de/hana/hana/html/sys_statistics_views.html
        
        https://help.sap.com/viewer/1efad1691c1f496b8b580064a6536c2d/Cloud/en-US/39eca89d94ca464ca52385ad50fc7dea.html
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: Unix
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3 :: Only
