Monitoring agent for SAP HANA V2.0 installation and operation guide

This guide provides instructions for installing, operating, and troubleshooting version 2.0 of the Google Cloud monitoring agent for SAP HANA.

For an overview of the monitoring agent for SAP HANA and its options, see Monitoring agent for SAP HANA V2.0 planning guide.

Prerequisites

This guide assumes that you have:

  • A Google account.
  • A Google Cloud project.
  • A Google Cloud billing account.
  • A deployed instance of SAP HANA. For information about deploying SAP HANA on Google Cloud, see the SAP HANA Deployment Guide.

Setting up Cloud Monitoring for your project

Configure a Cloud Monitoring Workspace for your project by doing the following:
  1. In the Cloud Console, select your Google Cloud project.
    Go to Cloud Console
  2. In the navigation pane, select Monitoring.

    If you have never used Cloud Monitoring, then on your first access of Monitoring in the Google Cloud Console, a Workspace is automatically created and your project is associated with that Workspace. Otherwise, if your project isn't associated with a Workspace, then a dialog appears and you can either create a Workspace or add your project to an existing Workspace. We recommend that you create a Workspace. After you make your selection, click Add.

Setting the required IAM roles

At a minimum, the service account that the monitoring agent for SAP HANA uses must include the Monitoring Metric Writer role. If it does not, you need to grant the Monitoring Metric Writer role to the service account.

Also, if you are using Secret Manager to store the SAP HANA system database user password, the service account must include the Secret Manager Secret Accessor role.

To add a required role to your service account:

  1. Go to the IAM & Admin page in the Cloud Console.

    Go to the IAM & Admin page

  2. Select your project and click Continue.

  3. Identify the service account to which you want to add a role.

    • If the service account isn't already on the members list, it doesn't have any roles assigned to it. Click Add member and enter the email address of the service account.
    • If the service account is already on the members list, it has existing roles. Click the current role dropdown list for the service account that you want to edit.
  4. Select the required role from the list of available roles:

    • Monitoring > Monitoring Metric Writer
    • Secret Manager > Secret Manager Secret Accessor
  5. Click Add or Save to apply the roles to the service account.

For more information about the IAM roles and scopes that are required to access Secret Manager, see Secret Manager Access control.

Installing the monitoring agent for SAP HANA

Add the Google Cloud RPM repository to the OS repo list

You need to add the URL for the Google Cloud RPM repository for the agent to the list of package repositories for the operating system. How you add a repository is different depending on whether you are using a Red Hat or a SUSE operating system.

Adding a repository to RHEL

To add the Google Cloud RPM repository to RHEL, select your version and follow the procedure:

RHEL 7

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo tee /etc/yum.repos.d/google-saphanamonitoring-agent.repo << EOM
    [google-saphanamonitoring-agent]
    name=Google SAP HANA Monitoring Agent
    baseurl=https://packages.cloud.google.com/yum/repos/google-saphanamonitoring-agent-el7-\$basearch
    enabled=1
    gpgcheck=0
    repo_gpgcheck=1
    gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
    EOM

RHEL 8

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo tee /etc/yum.repos.d/google-saphanamonitoring-agent.repo << EOM
    [google-saphanamonitoring-agent]
    name=Google SAP HANA Monitoring Agent
    baseurl=https://packages.cloud.google.com/yum/repos/google-saphanamonitoring-agent-el8-\$basearch
    enabled=1
    gpgcheck=0
    repo_gpgcheck=1
    gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
    EOM

Adding a repository to SLES

To add the Google Cloud RPM repository to SLES, select your version and follow the procedure:

SLES 12

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo zypper addrepo --gpgcheck-allow-unsigned-package --refresh \
    https://packages.cloud.google.com/yum/repos/google-saphanamonitoring-agent-sles12-\$basearch google-saphanamonitoring-agent

SLES 15

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo zypper addrepo --gpgcheck-allow-unsigned-package --refresh \
    https://packages.cloud.google.com/yum/repos/google-saphanamonitoring-agent-sles15-\$basearch google-saphanamonitoring-agent

Installing the agent

The monitoring agent for SAP HANA is installed by using the OS package manager.

Installing the agent on RHEL

On RHEL, use the following procedure to install the agent:

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo yum install google-saphanamonitoring-agent

The agent is installed in the /usr/sap/google-saphanamonitoring-agent directory.

Installing the agent on SLES

For SLES, install the agent by using the following procedure:

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo zypper install google-saphanamonitoring-agent

The agent is installed in the /usr/sap/google-saphanamonitoring-agent directory.

Configuring the agent

You configure the agent by modifying the agent configuration file: /usr/sap/google-saphanamonitoring-agent/conf/configuration.yaml.

The agent detects the following values automatically, but you can specify different values if you need to:

  • Project ID
  • Instance ID
  • Zone
  • SAP HANA system ID (SID)

You can accept or change other default values, as necessary.

The following steps specify the commonly used configuration properties. For descriptions of the all of the configuration properties, see Configuration property descriptions.

  1. Open the configuration file for editing by using your preferred text editor. For example:

    sudo vi /usr/sap/google-saphanamonitoring-agent/conf/configuration.yaml
  2. Optionally, under gcloud_auth, remove the comment character # and specify the path to a JSON file that contains the key for an IAM service account for the agent. For example:

    service_account_json: sap-example@example-project-id.iam.gserviceaccount.com
  3. Specify one or more SAP HANA instances for the agent to monitor.

    To specify more than one SAP HANA database, create a new set of properties by copying all of the applicable hana_instances properties from - name through trust_store_secret_name. You need to copy the SSL, certificate, keystore, and trustore properties only if the additional SAP HANA instance uses them. Paste the additional set of instance properties immediately after the first set and before queries.

    To define an SAP HANA instance:

    1. Specify the name of the host that the SAP HANA instance is running on. This value appears in the logs and in Monitoring. For example:

      - name: example-vm
    2. Specify the IP address of the host that the SAP HANA instance is running on.

      • If the SAP HANA instance is running on a different host VM than the agent, specify the internal IP address of the host VM. For example:
      host: 10.1.0.100
      • If the SAP HANA instance is running on a host that is not in the same Google Cloud project as the agent, specify the public IP address of the host VM.

      • If the agent is running on the same host as SAP HANA, you can accept the default value, which is the localhost loopback IP address, 127.0.0.1.

    3. Specify the port on which the SAP HANA instance accepts queries. For the first or only tenant database, the port is 3nn15, where nn is the instance number of SAP HANA.

      port: 30015
    4. Specify the SAP HANA user account that the agent is to use for querying SAP HANA. By default, the SYSTEM user account is specified:

      user: SYSTEM
    5. Specify the password for the SAP HANA user account that the agent is to use for querying SAP HANA. For example:

      password: TempPa55word
    6. If the SAP HANA system uses Transport Layer Secure (TLS)/Secure Sockets Layer (SSL), enable SSL support:

      enable_ssl: true
    7. To validate certificates when SAP HANA uses TLS/SSL, enable certificate checking and specify the certificate name, keystore, and trustore properties, as necessary.

      validate_certificate: true

      For a description of the certificate name, keystore, and trustore properties, see Configuration property descriptions.

  4. Save and close the configuration.yaml file.

Configuration property descriptions

The following table shows all of the properties that you can use to define your SAP HANA instances, connections, TLS/SSL support, and certificate validation support.

Except for sample_interval and query_timeout, which define global defaults for queries, all other properties that are used to define or enable individual queries are documented in the Monitoring agent for SAP HANA planning guide.

Property Data type Description
sample_interval Int Defines the default interval, in seconds, between between queries. The value specified here can be overridden for an individual query by specifying sample_interval in the query definition. The default value is `300` (5 minutes).
query_timeout Int Time allowed for query execution in seconds, default is 5 minutes.
cloud_properties Properties that identify the environment in which the agent is running. These values are detected automatically, but can be modified.
project_id String The ID of the Google Cloud project that uploads metrics to and, if you use Secret Manager, that contains the secret that has the required SAP HANA credentials.
instance_id String The ID number of the VM that agent is running on. Optionally, you can specify another value to use as an identifier in Monitoring. If you are running on a Bare Metal Solution machine, leave instance_id blank.
zone String The Google Cloud zone the agent is running in. If you are running on a Bare Metal Solution machine, leave zone blank.
gcloud_auth Properties related to the service account that the agent uses for identity and access management.
service_account_json String Specifies the path to a JSON file that contains the key of a custom service account that you create. Google Cloud uses the service account to authenticate the agent and to determine which Google Cloud APIs and resources that agent is authorized to access. When service_account_json is omitted, the agent uses the service account of the host VM.
hana_instances Properties that identify an SAP HANA database to be monitored. To specify more than one SAP HANA database, create a new set of properties by copying the existing instance properties from - name to enable_ssl, inclusive, and pasting them immediately after the first set. Define the additional database with the new set of properties.
- name String The name of the host SAP HANA is running on. The value is used to identify the HANA instance in Monitoring. If you are monitoring more than one database, modify to distinguish the databases.
host String The IP address of the SAP HANA host. If the agent is running on the same host as SAP HANA, you can accept the default, which is the localhost loopback IP address.
port Int The port number of the SAP HANA server, as defined by SAP. For the first or only tenant database, specify 3nn15, where nn is the SAP HANA instance number. For more information SAP HANA ports, see TCP/IP Ports of All SAP Products.
connections Int For connection pooling, the number of connections to maintain in the connection pool. Do not modify this property unless directed to do so by Google Cloud Support.
user String The SAP HANA database user account the agent uses to query SAP HANA. SYSTEM is the default.
password String The password for the database user account that the monitoring agent uses to query SAP HANA. Do not specify a password if you are using Secret Manager to store the database user credentials.
secret_name String If you are using Secret Manager to store the database user credentials, specify the name of the secret that contains the security credentials.
enable_ssl Boolean Specifies whether SSL or TSL is enabled in SAP HANA. Valid values are true or false.
validate_certificate Boolean Specifies whether the agent checks the server's certificate. Valid values are true or false.
host_name_in_certificate Specifies the SAP HANA host name that is contained in the certificate. This property is required when monitoring agent for SAP HANA is running on the same host VM as SAP HANA and the SAP HANA host VM uses `localhost` to complete the connection between the agent and host VM instead of the actual host name.
key_store Specifies the path to a JKS or PKCS12 Java keystore. If this property is not specified, the monitoring agent for SAP HANA uses JVM default.

If the key store is password protected, either key_store_password or key_store_secret_name must be specified.

key_store_password When a keystore is password protected, specifies a plain text password for the keystore. The specification of key_store_password is mutually exclusive with the specification of key_store_secret_name.
key_store_secret_name When a keystore is password protected, specifies the name of a secret in Secret Manager that contains the password for the keystore. The specification of key_store_secret_name is mutually exclusive with the specification of key_store_password.
trust_store Specifies the path to the truststore JKS file that contains the SAP HANA server's public certificate(s). Typically, the truststore contains the root certificate or the certificate of the certification authority that signed the SAP HANA server's certificate(s). If trust_store is omitted, the agent uses the default truststore of the JVM.
trust_store_password When a truststore is password protected, specifies a plain text password for the truststore. The specification of trust_store_password is mutually exclusive with the specification of trust_store_secret_name.
trust_store_secret_name When a truststore is password protected, specifies the name of a secret in Secret Manager that contains the password for the truststore. The specification of trust_store_secret_name is mutually exclusive with the specification of trust_store_password.

Enable the agent

After the monitoring agent for SAP HANA is configured, but before you start it, enable the agent as a systemd service so that the service restarts any time the VM instance is rebooted.

To enable the agent:

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo systemctl enable google-saphanamonitoring-agent

    You should see the output that is similar to the following example:

    Created symlink /etc/systemd/system/multi-user.target.wants/google-saphanamonitoring-agent.service → /usr/sap/google-saphanamonitoring-agent/service/google-saphanamonitoring-agent.service.
    Created symlink /etc/systemd/system/google-saphanamonitoring-agent.service → /usr/sap/google-saphanamonitoring-agent/service/google-saphanamonitoring-agent.service.
    

Start the agent

To start the agent:

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo systemctl start google-saphanamonitoring-agent
  3. Check the status of the agent:

    sudo systemctl status google-saphanamonitoring-agent

    The startup status is written to the logs.

Checking the logs

To check the logs, issue:

tail -n 100 -f /var/log/google-saphanamonitoring-agent.log

When the agent starts, it records the startup events in the logs. If startup is successful, after a few seconds the agent begins querying SAP HANA, and writes an entry to the logs for each metric sent to Monitoring.

The following example shows the startup logs and the log entries for the first successful query to SAP HANA.

2020-12-15T02:28:20.779UTC [INFO] ******  Starting Google SAP HANA Custom Metrics Agent ******
2020-12-15T02:28:20.812UTC [INFO] Controller initializing...
2020-12-15T02:28:20.813UTC [INFO] Configuring dependencies...
2020-12-15T02:28:21.227UTC [INFO] Configuration of dependencies complete.
2020-12-15T02:28:21.227UTC [INFO] Configuration loading...
2020-12-15T02:28:21.269UTC [INFO] Loading system level metric definitions...
2020-12-15T02:28:21.377UTC [INFO] Loading conf/configuration.yaml...
2020-12-15T02:28:21.491UTC [INFO] Default Cloud Properties: projectId=example-project-id, instanceId=5376220384318079736, zone=us-central1-c
2020-12-15T02:28:21.502UTC [INFO] No "cloud_properties" field found in the config file, so using default cloud properties.
2020-12-15T02:28:21.505UTC [INFO] No "gcloud_auth" field found in the config file, so using default instance credentials.
2020-12-15T02:28:21.511UTC [INFO] Configuration loaded and validated.
2020-12-15T02:28:21.511UTC [INFO] Configuration load complete.
2020-12-15T02:28:21.511UTC [INFO] Controller initialization complete
2020-12-15T02:28:21.512UTC [INFO] Starting sampling of HANA metrics...
2020-12-15T02:28:21.523UTC [INFO] Creating connection pool of size 10 for SAP HANA instance "example-vm"
2020-12-15T02:28:21.976UTC [INFO] The SAP HANA agent has completed initial setup. Metrics will start being sent to Cloud Monitoring in 30 seconds.
2020-12-15T02:28:51.957UTC [INFO] Writing time series data to Stackdriver
2020-12-15T02:28:51.961UTC [INFO] Writing time series data to Stackdriver
2020-12-15T02:28:51.977UTC [INFO] Writing time series data to Stackdriver
2020-12-15T02:28:51.980UTC [INFO] Writing time series data to Stackdriver
2020-12-15T02:28:51.981UTC [INFO] Writing time series data to Stackdriver
2020-12-15T02:28:51.981UTC [INFO] Scheduling another execution for query "replication_query" and instance "example-vm" in 300 seconds

Stopping the agent

If you add a custom query or otherwise change the configuration of the agent, you need to stop and start the agent before the new query or other configuration changes take effect.

  1. Stop the agent:

    sudo systemctl stop google-saphanamonitoring-agent
  2. Restart the agent:

    sudo systemctl start google-saphanamonitoring-agent

Updating the monitoring agent for SAP HANA

To ensure that you have the latest version of the monitoring agent for SAP HANA, check for updates periodically. Updates are announced on the SAP on Google Cloud Release Notes page.

Checking for updates

Select your operating system:

RHEL

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo yum check-update google-saphanamonitoring-agent

SLES

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo zypper list-updates -r google-saphanamonitoring-agent

Installing an update

Select your operating system:

RHEL

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo yum update google-saphanamonitoring-agent

SLES

  1. Establish an SSH connection with your host VM.

  2. Issue the following command:

    sudo zypper update google-saphanamonitoring-agent

Updating from version 1 to version 2 or later

The installation script for version 2 of the monitoring agent for SAP HANA checks for version 1 and automatically adds the SAP HANA instance definitions from version 1 configuration file to the version 2 configuration file.

You need to recreate any custom queries that were used in version 1 by adding them to the configuration.yaml file in the version 2 custom query format.

To use certain version 2 configuration options, you might need to add the properties to the configuration file yourself.

To update from version 1 to version 2 or later:

  1. SSH into the host VM of the version 1 agent.

  2. Add the Google Cloud RPM repository to the OS repo list.

  3. Install the new agent by selecting your operating system and issuing the applicable install command:

    RHEL

    Issue the following command:

    sudo yum install google-saphanamonitoring-agent

    SLES

    Issue the following command:

    sudo zypper install google-saphanamonitoring-agent

    During installation of version 2, the installation script takes the following actions:

    • Checks for version 1 of the agent.
    • Stops version 1.
    • Creates a a version 2 configuration file, /usr/sap/google-saphanamonitoring-agent/conf/configuration.yaml, that includes the instance definitions from the version 1 configuration file and the default query statements for version 2. Queries from version 1 are not copied over. Other version 2 configuration properties must be added manually.
    • Saves a copy of the default version 2 configuration file as /usr/sap/google-saphanamonitoring-agent/conf/configuration.yaml.original
    • Saves the version 1 configuration file as /etc/default/gcm.save.
  4. In the version 2 configuration.yaml file, validate the instance definitions and make any other required changes. For a list of all of the configuration properties for version 2, see Configuration property descriptions.

    1. Confirm that the instance definitions were correctly imported from the version 1 configuration file /etc/default/gcm into the new configuration file /usr/sap/google-saphanamonitoring-agent/conf/configuration.yaml.

    2. If you are using Secret Manager, replace the password value with a secret_name value.

    3. If your SAP HANA instances use SSL/TLS, set the SSL/TLS properties.

    4. Review the set of default queries and disable any that you don't need. The default metrics collected by version 2 are different than the default metrics in version 1. For more information about the version 2 default queries, see Default query reference.

    5. Recreate any custom queries that were used in version 1 in the version 2 configuration.yaml file. For more information about defining custom queries in version 2, see Defining custom queries.

  5. Enable the agent as a systemd service:

    sudo systemctl enable google-saphanamonitoring-agent
  6. Start the agent:

    sudo systemctl start google-saphanamonitoring-agent
  7. Confirm the agent is writing metrics to Monitoring by checking the logs:

    tail -n 100 -f /var/log/google-saphanamonitoring-agent.log
  8. Update your Monitoring dashboards, graphs, and alerts for the new, changed, or discontinued metrics:

    Go to Monitoring

Troubleshooting

The following sections provide steps to take if you encounter problems with installation, queries, or sending the metrics to Monitoring.

Installation fails

Confirm that you are using an operating system that is supported by monitoring agent for SAP HANA. For more information, see Supported operating systems.

Check for error messages in the shell that you used to install the agent.

Confirm that the Google Cloud RPM repository for the agent was added to operating system's list of repositories, as described in Add the Google Cloud RPM repository to the OS repo list.

Default queries are failing

On the host VM, check for error messages in the log file, /var/log/google-saphanamonitoring-agent.log.

On the host VM, confirm that the correct port is specified on the port property of each SAP HANA instance definition in the configuration.yaml file. For information from SAP about which ports to use for SAP HANA SQL queries, see TCP/IP Ports of All SAP Productstarget="external" track-type="userGuide" track-name="externalLink" track-metadata-position="body" class="external" }.

Make sure that your SAP HANA database user has access to the following SAP HANA system views:

  • M_CONNECTIONS
  • M_CS_ALL_COLUMNS
  • M_CS_TABLES
  • M_HOST_RESOURCE_UTILIZATION
  • M_RS_TABLES
  • M_SERVICE_COMPONENT_MEMORY
  • M_SERVICE_MEMORY
  • M_SERVICE_REPLICATION
  • M_WORKLOAD
  • STATISTICS_CURRENT_ALERTS view of the _SYS_STATISTICS schema

Metrics are not being sent to Monitoring

On the host VM, check for error messages in the log file, /var/log/google-saphanamonitoring-agent.log.

If the agent is not using the service account of a host VM, confirm that the path to the JSON service account key is properly specified on the service_account_json property in the configuration.yaml file.

On the IAM & Admin home page, make sure that the service account that the agent is using has the Monitoring Metric Writer role (roles/monitoring.metricWriter). For more information, see Setting the required IAM roles.

Support

For issues with Google Cloud infrastructure or services, contact Google Cloud Support. You can find contact information on the Support Overview page in the Google Cloud Console. If Google Cloud Support determines that a problem resides in your SAP systems, you are referred to SAP Support.

For SAP product-related issues, log your support request with SAP support. SAP evaluates the support ticket and, if it appears to be a Google Cloud infrastructure issue, transfers the ticket to the Google Cloud component BC-OP-LNX-GOOGLE or BC-OP-NT-GOOGLE.

Support requirements

Before you can receive support for SAP systems and the Google Cloud infrastructure and services that they use, you must meet the minimum support plan requirements.

For more information about the minimum support requirements for SAP on Google Cloud, see:

What's next