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.
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
throughtrust_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 beforequeries
.To define an SAP HANA instance:
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
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
.
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
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
Specify the password for the SAP HANA user account that the agent is to use for querying SAP HANA. For example:
password: TempPa55word
If the SAP HANA system uses Transport Layer Secure (TLS)/Secure Sockets Layer (SSL), enable SSL support:
enable_ssl: true
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 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 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 |
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. |
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 |
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:
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:
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:
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.
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)