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

The monitoring agent for SAP HANA requires SAP HANA connection drivers and a specific version of the Java Runtime Environment (JRE).

If the server that you are installing the agent on has access to the internet, the agent downloads the files automatically during installation.

If the server does not have internet access, you can upload the files to the server yourself.

If you need to upload them yourself, before you install the agent, upload the following files into the /tmp/gcpsapdeps directory:

https://github.com/SAP/SapMachine/releases/download/sapmachine-17.0.1/sapmachine-jre-17.0.1_linux-x64_bin.tar.gz

https://repo1.maven.org/maven2/com/sap/cloud/db/jdbc/ngdbc/2.11.14/ngdbc-2.11.14.jar

Also, this guide assumes that you have:

A Google account.
A Google Cloud project.
A Google Cloud billing account.
One or more deployed instances of SAP HANA. For information about deploying SAP HANA on Google Cloud, see the SAP HANA Deployment Guide.

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, then 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, then the service account must include the Secret Manager Secret Accessor role and VM instances must include the cloud-platform access scope.

To add the required roles to your service account:

In the Google Cloud console, go to the IAM & Admin IAM page.

Go to IAM
Select your Google Cloud project.
Identify the service account to which you want to add the IAM roles.
- If the service account isn't already on the principals list, then it doesn't have any roles assigned to it. Click Add and then enter the email address of the service account.
- If the service account is already on the principals list, then it has existing roles. Click the Edit principal button against the service account that you want to edit.
Click Add another role and then make sure that the following roles are assigned to your service account:
- Monitoring > Monitoring Metric Writer
- Secret Manager > Secret Manager Secret Accessor
Click Add or Save to assign the roles to your service account.

For information on how to set access scopes for a VM instance, see Changing the service account and access scopes for an instance.

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

Establish an SSH connection with your host VM.

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=0
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
EOM

RHEL 8

Establish an SSH connection with your host VM.

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=0
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

Establish an SSH connection with your host VM.

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

Establish an SSH connection with your host VM.

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

You install the monitoring agent for SAP HANA by using the OS package manager.

To install the agent, select your operating system and follow the procedure:

Establish an SSH connection with your host VM.

Issue the following command:

RHEL

sudo yum install google-saphanamonitoring-agent

SLES

sudo zypper --no-gpg-checks 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.

Server property values that are automatically detected

By default, the cloud_properties section in the configuration.yaml file is commented out, as shown in the following example, and the monitoring agent for SAP HANA uses the project ID, instance ID, and zone of the VM instance that the agent is running on.

  # cloud_properties:
     # project_id: MONITORED_INSTANCE_PROJECT_ID
     # instance_id: MONITORED_VM_ID
     # zone: MONITORED_VM_ZONE

If the agent is running on the same VM as SAP HANA, you can leave the cloud_properties section commented out.

If the agent is running on a different VM than SAP HANA, you need to remove the comment character, #, from each line in the cloud_properties section and update the project_id, instance_id, and zone properties with the project ID, instance ID, and zone of the SAP HANA host VM.

If SAP HANA is running on a Bare Metal Solution server, you need to remove the comment character, #, from only the cloud_properties and project_id lines and specify the project ID of the project that you are using with Bare Metal Solution. Leave the instance_id and zone properties commented out.

SAP HANA property values that are automatically detected

By default, the sid property in the configuration.yaml file is commented out and the agent retrieves the SAP HANA system ID (SID) from SAP HANA M_DATABASE table. If you need to specify a different SID, remove the comment character from the sid line and specify the SID that you need.

Configuration procedure

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

Open the configuration file for editing by using your preferred text editor. For example:
```
sudo vi /usr/sap/google-saphanamonitoring-agent/conf/configuration.yaml
```

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:

gcloud_auth:
# If defined this service account will be used for API calls or else the default VM credentials
# will be used.
service_account_json: /usr/sap/google-saphanamonitoring-agent/auth/example-project-id-abcdef123456.json

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-hana-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.
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 SAP HANA is running in. In Monitoring, this value is a resource label that you can use to filter your data. Specify this property if SAP HANA is running on a different VM than the agent or on a Bare Metal Solution server. When the agent runs on the same VM as SAP HANA, by default, the agent detects the project ID automatically. You can override the default behavior by specifying a property value.
`instance_id`	String	When SAP HANA is running on a different Compute Engine VM than the agent, specifies the instance ID number of the SAP HANA host VM. In Monitoring, this value is a resource label that you can use to filter your data. If SAP HANA is running on a Bare Metal Solution server, always leave `instance_id` commented out. By default, the agent uses the instance ID of the VM that the agent is installed on.
`zone`	String	When SAP HANA is running on a Compute Engine VM in a different zone than the agent, specifies the zone of the SAP HANA host VM. In Monitoring, this value is a resource label that you can use to filter your data. If SAP HANA is running on a Bare Metal Solution server, always leave `zone` commented out. By default, the agent uses the zone of the VM that the agent is installed on.
`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 that SAP HANA is running on. This value identifies the SAP HANA instance. In Monitoring this value is a metric label that you can use to filter your data. If you are monitoring more than one database, modify this value to distinguish the databases.
`sid`	String	An optional property that specifies the SID of the SAP HANA instance that the agent is monitoring. The agent normally retrieves this value from SAP HANA automatically, so you don't have to specify it. If you need to specify a different value, or the agent isn't detecting the SID automatically, uncomment the `sid` property and specify the value that you need.
`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 Cloud Customer Care.
`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. Important: The secret and the host VM must exist in the same Google Cloud project.
`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`. Important: The secret and the host VM must exist in the same Google Cloud project.
`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`. Important: The secret and the host VM must exist in the same Google Cloud project.

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:

Establish an SSH connection with your host VM.

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:

Establish an SSH connection with your host VM.

Issue the following command:

sudo systemctl start google-saphanamonitoring-agent

Check the status of the agent:

sudo systemctl status google-saphanamonitoring-agent

If startup is successful, after a few seconds the agent begins querying SAP HANA and sending the metrics to Monitoring.

For information about viewing your metrics in Monitoring, see Install the custom dashboard to view your metrics.

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. The startup, scheduling of queries, and the sending of the metrics to Monitoring are recorded in the logs.

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

2021-04-26T20:42:53.392UTC [INFO] ******  Starting Google SAP HANA Custom Metrics Agent ******
2021-04-26T20:42:53.413UTC [INFO] Controller initializing...
2021-04-26T20:42:53.414UTC [INFO] Configuring dependencies...
2021-04-26T20:42:53.677UTC [INFO] Configuration of dependencies complete.
2021-04-26T20:42:53.678UTC [INFO] Configuration loading...
2021-04-26T20:42:53.704UTC [INFO] Loading system level metric definitions...
2021-04-26T20:42:53.767UTC [INFO] Loading conf/configuration.yaml...
2021-04-26T20:42:53.836UTC [INFO] Default Cloud Properties: projectId=example-project-id, instanceId=8254335046206112691, zone=us-central1-f
2021-04-26T20:42:53.843UTC [INFO] No "cloud_properties" field found in the config file, so using default cloud properties.
2021-04-26T20:42:53.850UTC [INFO] Configuration loaded and validated.
2021-04-26T20:42:53.865UTC [INFO] Configuration load complete.
2021-04-26T20:42:53.865UTC [INFO] Controller initialization complete
2021-04-26T20:42:53.865UTC [INFO] Starting sampling of HANA metrics...
2021-04-26T20:42:53.875UTC [INFO] Creating connection pool of size 10 for SAP HANA instance "example-hana-vm"
2021-04-26T20:42:54.289UTC [INFO] The SAP HANA agent has completed initial setup. Metrics will start being sent to Cloud Monitoring in 30 seconds.
2021-04-26T20:43:24.278UTC [INFO] Writing time series data to Cloud Monitoring
2021-04-26T20:43:24.281UTC [INFO] Writing time series data to Cloud Monitoring
2021-04-26T20:43:24.292UTC [INFO] Writing time series data to Cloud Monitoring
2021-04-26T20:43:24.292UTC [INFO] Writing time series data to Cloud Monitoring
2021-04-26T20:43:24.294UTC [INFO] Writing time series data to Cloud Monitoring
2021-04-26T20:43:24.295UTC [INFO] Writing time series data to Cloud Monitoring
2021-04-26T20:43:24.295UTC [INFO] Scheduling another execution for query "replication_query" and instance "example-hana-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.

Stop the agent:

sudo systemctl stop google-saphanamonitoring-agent

Restart the agent:

sudo systemctl start google-saphanamonitoring-agent

Install the custom dashboard to view your metrics

To install the SAP HANA custom dashboard from the GitHub repository into Monitoring, do the following:

Open the Cloud Shell:

Go to the Cloud Shell

In the Cloud Shell, clone or download the repository:

git clone https://github.com/GoogleCloudPlatform/monitoring-dashboard-samples.git

In the Cloud Shell, install the SAP HANA performance.json dashboard:

gcloud monitoring dashboards create \
--config-from-file=monitoring-dashboard-samples/dashboards/sap-hana/performance.json

The dashboard "SAP HANA Performance" is added to the available dashboards in your Google Cloud project. To see your dashboard, follow the instructions in Viewing the installed dashboard.

For more information, see:

Viewing the installed dashboard

The performance.json file in the repository creates a new custom dashboard with the title "SAP HANA Performance".

In the Google Cloud console, select Monitoring or click the following button:

Go to Monitoring
In the Monitoring navigation panel, click Dashboards.
Click on SAP HANA Performance in the list. If you have a lot of dashboards, you can filter for custom dashboards or for the name of the new dashboard. For information on filtering this list, see Viewing custom dashboards.

The following screen capture shows part of the custom dashboard for SAP HANA in Monitoring.

Screen capture shows the top two charts of the custom SAP HANA Perfromance
dashboard in Monitoring

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

Establish an SSH connection with your host VM.

Issue the following command:

sudo yum check-update google-saphanamonitoring-agent

SLES

Establish an SSH connection with your host VM.

Issue the following command:

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

Installing an update

Select your operating system:

RHEL

Establish an SSH connection with your host VM.

Issue the following command:

sudo yum update google-saphanamonitoring-agent

SLES

Establish an SSH connection with your host VM.

Issue the following command:

sudo zypper --no-gpg-checks update google-saphanamonitoring-agent

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 Products.

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.

Getting support for the monitoring agent for SAP HANA

If you need help resolving a problem with the monitoring agent for SAP HANA, gather the required diagnostic information and contact Cloud Customer Care. For more information, see Monitoring agent for SAP HANA diagnostic information.

Support

For issues with Google Cloud infrastructure or services, contact Customer Care. You can find the contact information on the Support Overview page in the Google Cloud console. If Customer Care determines that a problem resides in your SAP systems, then 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, then SAP transfers that ticket to the appropriate Google Cloud component in its system: 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:

Getting support for SAP on Google Cloud
SAP Note 2456406 - SAP on Google Cloud Platform: Support Prerequisites (An SAP user account is required)

What's next

Learn more about Cloud Monitoring.