Install and configure Google Cloud's Agent for SAP on a Bare Metal Solution server

Google Cloud's Agent for SAP is required for SAP support of SAP systems running on a Bare Metal Solution server.

If you use the following RHEL or SLES "for SAP" OS images that Google Cloud provides, then Google Cloud's Agent for SAP is packaged with the OS images:

RHEL: all "for SAP" images
SLES: SLES 15 SP4 for SAP and later versions

For information about the operating systems available for running SAP on Bare Metal Solution servers, see the following:

For SAP HANA, see Certified operating systems.
For SAP NetWeaver, see Certified operating systems.

To install and configure version 2 of Google Cloud's Agent for SAP on a Compute Engine VM instance, see Install Google Cloud's Agent for SAP on a Compute Engine VM instance.

Installation overview

You install Google Cloud's Agent for SAP by using standard operating system package management commands: on RHEL, the yum command; on SLES, the zypper command. The package management command completes the following tasks:

Downloads Google Cloud's Agent for SAP.
Creates the agent as a Linux systemd service, named google-cloud-sap-agent.
Enables and starts the service, google-cloud-sap-agent.

Install the agent

We recommend that you install the latest version of Google Cloud's Agent for SAP, which supports more features. For instructions, see Install and configure Google Cloud's Agent for SAP on a Bare Metal Solution server.

To install version 2 of Google Cloud's Agent for SAP, contact Cloud Customer Care.

After you install Google Cloud's Agent for SAP and the SAP Host Agent, validate the installation of Google Cloud's Agent for SAP, as described in Validate your installation of the agent.

Validate your installation of the agent

Establish an SSH connection with your Bare Metal Solution server.

Run the following command:

systemctl status google-cloud-sap-agent

If the agent is functioning properly, then the output contains active (running). For example:

google-cloud-sap-agent.service - Google Cloud Agent for SAP
Loaded: loaded (/usr/lib/systemd/system/google-cloud-sap-agent.service; enabled; vendor preset: disabled)
Active:  active (running)  since Fri 2022-12-02 07:21:42 UTC; 4 days ago
Main PID: 1337673 (google-cloud-sa)
Tasks: 9 (limit: 100427)
Memory: 22.4 M (max: 1.0G limit: 1.0G)
CGroup: /system.slice/google-cloud-sap-agent.service
       └─1337673 /usr/bin/google-cloud-sap-agent

If the agent isn't running, then restart the agent.

Verify that SAP Host Agent is receiving metrics

To verify that the infrastructure metrics are collected by Google Cloud's Agent for SAP and sent correctly to the SAP Host Agent, follow these steps:

In your SAP system, enter transaction ST06.
In the overview pane, check the availability and content of the following fields for the correct end-to-end setup of the SAP and Google monitoring infrastructure:
- Cloud Provider: Google Cloud Platform
- Enhanced Monitoring Access: TRUE
- Enhanced Monitoring Details: ACTIVE

Configure Google Cloud's Agent for SAP on Linux

After you install Google Cloud's Agent for SAP, optionally, you can configure the agent to collect Process Monitoring metrics, Workload Manager evaluation metrics, and SAP HANA monitoring metrics. By default, the collection of only the SAP Host Agent metrics is enabled.

Prerequisites

To enable these features for the agent instance running on your Bare Metal Solution server, you need to complete the following prerequisites:

Create an IAM service account for the agent to access the Google Cloud resources, and then grant the required IAM roles to the service account. See Set up a service account for details.
On your Bare Metal Solution server, install the gcloud CLI. See Install the gcloud CLI for details.
To access Google Cloud, authorize the gcloud CLI. See Authorize the gcloud CLI for details.
Establish connection to Google Cloud APIs. See Configuring Private Google Access for on-premises hosts for details.

Set up a service account

To enable the agent to access Google Cloud resources from a Bare Metal Solution environment, you need to set up an IAM service account.

At a minimum, the service account that the agent uses must include the Monitoring Metric Writer (roles/monitoring.metricWriter) role.

To create a service account, follow these steps:

Create a service account:
1. In the Google Cloud console, go to the Create service account page.
  Go to Create service account
2. Select your project.
3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.
  
  In the Service account description field, enter a description. For example, Service account for quickstart.
4. Click Create and continue.
5. Grant the Monitoring > Monitoring Metric Writer role to the service account.
  
  To grant the role, find the Select a role list, then select Monitoring > Monitoring Metric Writer.
  
  Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
6. Click Continue.
7. Click Done to finish creating the service account.
  
  Do not close your browser window. You will use it in the next step.
Create a service account key:
1. In the Google Cloud console, click the email address for the service account that you created.
2. Click Keys.
3. Click Add key, and then click Create new key.
4. Click Create. A JSON key file is downloaded to your computer.
5. Click Close.

After you create the service account, make sure to upload its JSON key file on to a secure location on the Bare Metal Solution server that is accessible to the agent.

Enable features

Once you set up a service account for your Bare Metal Solution and grant it the required roles, you can enable other features of the Google Cloud's Agent for SAP by performing the following configurations:

Default configuration file

The following snippet is an example of the default configuration of version 2 of Google Cloud's Agent for SAP:

{
  "provide_sap_host_agent_metrics": true,
  "bare_metal": ,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": false,
    "collect_process_metrics": false,
    "sap_system_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}

Configuration parameters

The following table explains the configuration parameters of version 2 of Google Cloud's Agent for SAP.

Parameters
`provide_sap_host_agent_metrics`	`Boolean` To enable the collection of the metrics required by the SAP Host Agent, specify `true`. Default is `true`. Don't set `provide_sap_host_agent_metrics` to `false` unless you are directed by Cloud Customer Care or SAP Support.
`bare_metal`	`Boolean` When the agent is installed on a Bare Metal Solution server, specify `true`. Default is `false`.
`log_level`	`String` To set the logging level of the agent, set the required value. The available log levels are as follows: `DEBUG` `INFO` `WARNING` `ERROR` Default is `INFO`. Don't change the logging level unless you are directed by Cloud Customer Care.
`log_to_cloud`	`Boolean` To redirect the agent's logs to Cloud Logging, specify `true`. The default is `true`.
`sap_system_discovery`	`Boolean` To enable the SAP system discovery, specify `true`. Default is `true`.
`cloud_properties.project_id`	`String` If your SAP system is running on a Bare Metal Solution server, then specify the project ID of the Google Cloud project that you are using with Bare Metal Solution. When the agent runs on a VM instance, by default, the agent detects the project ID automatically.
`cloud_properties.instance_name`	`String` Specify the name of the Bare Metal Solution server on which you have installed the agent. In agent version 2.5 or earlier, specify the Bare Metal Solution server name for the property `instance_id`.
`cloud_properties.region`	`String` If your SAP system is running on a Bare Metal Solution server, then specify the region of the Bare Metal Solution server. When the agent runs on a VM instance, by default, the agent uses the region of the VM instance that the agent is installed on.
`cloud_properties.zone`	`String` When the agent runs on a VM instance, by default, the agent uses the zone of the VM instance that the agent is installed on.
`cloud_properties.image`	`String` Specify the OS image name of the instance. When the agent runs on a VM instance, by default, the agent detects the OS image of the VM instance that the agent is installed on.
`cloud_properties.numeric_project_id`	`String` Specify the numeric ID of the Google Cloud project that the SAP system is running in. When the agent runs on a VM instance, by default, the agent detects the numeric project ID automatically.
`collection_configuration.collect_process_metrics`	`Boolean` To enable Process Monitoring metrics collection, specify `true`. Default is `false`. This parameter is applicable only for Linux. If you enable Process metrics collection for SAP HANA, then you need to set up additional parameters listed under `hana_metrics_config`.
`collection_configuration.process_metrics_frequency`	`Int` From version 2.6, this parameter determines the collection frequency of the fast-changing Process Monitoring metrics, in seconds. Fast-changing Process Monitoring metrics are: `sap/hana/availability`, `sap/hana/ha/availability`, and `sap/nw/availability`. The default value for this parameter is `5` seconds. We recommend that you use this default value. All other (slow-changing) Process Monitoring metrics are collected at a default frequency of 30 seconds. To change the collection frequency of the slow-changing Process Monitoring metrics, use the parameter `slow_process_metrics_frequency`.
`collection_configuration.slow_process_metrics_frequency`	`Int` Specify the collection frequency of the slow-changing Process Monitoring metrics, in seconds. The default value for this parameter is `30` seconds.
`collection_configuration.process_metrics_to_skip`	`Array` Specify the Process Monitoring metrics that you don't want the agent to collect. This parameter accepts a comma-separated value of Process Monitoring metric names. For example: `"process_metrics_to_skip": ["/sap/nw/abap/sessions", "/sap/nw/abap/rfc"]`.
`collection_configuration.hana_metrics_config.hana_db_user`	`String` Specify the database user account that the agent uses to query SAP HANA. Default is `SYSTEM`.
`collection_configuration.hana_metrics_config.hana_db_password`	`String` Specify the plain text password for the database user account that the agent uses to query SAP HANA. Instead of using a plain text password, we recommend that you use a secret in Secret Manager by specifying the name of the secret in `hana_db_password_secret_name`. Don't specify a password if you are using Secret Manager to store the database user credentials. When both `hana_db_password` and `hana_db_password_secret_name` are specified in the configuration, then an error is triggered and the agent cannot connect to the database.
`collection_configuration.hana_metrics_config.hana_db_password_secret_name`	`String` To securely provide the password for the database user account that the agent uses to query SAP HANA, specify the name of the secret that contains the security credentials for the database user account. SAP HANA related metrics are collected only if either `hana_db_password_secret_name` or `hana_db_password` is set. Important: The secret and the host VM instance must exist in the same Google Cloud project.
`collection_configuration.collect_workload_validation_metrics`	`Boolean` To enable Workload Manager evaluation metrics collection, specify `true`. From version 3.2, the default value is `true`. This parameter is applicable only for Linux.
`collection_configuration.workload_validation_metrics_frequency`	`Int` The collection frequency of the Workload Manager evaluation metrics in seconds. The default value is `300` seconds. We recommend that you don't modify the default collection frequency as it might impact the entire feature itself. If you need to modify the collection frequency of the Workload Manager metrics, then add the `workload_validation_metrics_frequency` parameter under the `collection_configuration` section and provide the required value.
`collection_configuration.workload_validation_db_metrics_config.hana_db_user`	`String` Specify the user account that is used to query the SAP HANA instance. The user account must have the read permission to the SAP HANA database.
`collection_configuration.workload_validation_db_metrics_config.hana_db_password_secret_name`	`String` Specify the name of the secret in Secret Manager that stores the user account's password.
`collection_configuration.workload_validation_db_metrics_config.hostname`	`String` Specify the identifier for the machine, either local or remote, that hosts your SAP HANA instance. The following are the supported values: If the host is a local machine, then specify the string `localhost` or the localhost loopback IP address, like `127.0.0.1`. If the host is a remote machine, then specify its internal or external IP address.
`collection_configuration.workload_validation_db_metrics_config.port`	`String` Specify the port on which your SAP HANA instance accepts queries. For the first or only tenant database instance, the port is `3NN15`, where `NN` is the instance number of the SAP HANA instance.
`collection_configuration.workload_validation_db_metrics_frequency`	`Int` The collection frequency of the SAP HANA database metrics, in seconds, for Workload Manager evaluation. Default is `3600` seconds. Although you can update the collection frequency of the SAP HANA database metrics, we recommend that you use the default value. If you need to modify the default value, then add the `workload_validation_db_metrics_frequency` parameter under the `collection_configuration` section and provide the required value. Make sure that you don't set a collection frequency greater than `3600` seconds.
`hana_monitoring_configuration.enabled`	`Boolean` Optional. To enable Google Cloud's Agent for SAP to collect the SAP HANA monitoring metrics, specify `true`. The default value is `false`. The following child parameters are applicable only when you specify `hana_monitoring_configuration.enabled: true`.
`hana_monitoring_configuration.sample_interval_sec`	`Int` Optional. Specify the sample interval, in seconds, which determines the frequency at which Google Cloud's Agent for SAP queries your SAP HANA instances to collect the SAP HANA monitoring metrics. The default value is 300 seconds. For each query defined in the configuration file of Google Cloud's Agent for SAP, you can overwrite the global sample interval by specifying the required interval to the parameter `sample_interval_sec`. Sample intervals must be 5 seconds or longer.
`hana_monitoring_configuration.query_timeout_sec`	`Int` Optional. Specify the timeout for each query made to the SAP HANA instances. The default value is 300 seconds.
`hana_monitoring_configuration.execution_threads`	`Int` Optional. Specify the number of threads used to send queries to the SAP HANA instances. Each query runs on its own thread. The default value is 10.
`hana_monitoring_configuration.hana_instances.name`	`String` Specify the name identifier for your SAP HANA instance.
`hana_monitoring_configuration.hana_instances.sid`	`String` Specify the SID of your SAP HANA instance. This string is added as a label to all the metrics resulting from querying your SAP HANA instances.
`hana_monitoring_configuration.hana_instances.host`	`String` Specify the identifier for the machine, either local or remote, that hosts your SAP HANA instance. The following are the supported values: If the host is a local machine, then specify the string `localhost` or the localhost loopback IP address, like `127.0.0.1`. If the host is a remote machine, then specify its internal or external IP address.
`hana_monitoring_configuration.hana_instances.port`	`String` Specify the port on which your SAP HANA instance accepts queries. For the first or only tenant database instance, the port is `3NN15`, where `NN` is the instance number of the SAP HANA instance.
`hana_monitoring_configuration.hana_instances.user`	`String` Specify the user account that is used to query the SAP HANA instance.
`hana_monitoring_configuration.hana_instances.password`	`String` Optional. Specify the password, as plain text, that authenticates the user account for querying the SAP HANA instance. To enable authentication, you must specify one of the following: The plain text password to the parameter `password`. (Recommended) If you use Secret Manager to store the password as a secret, then you must specify the corresponding secret name to the parameter `secret_name`. If you use both the parameters, then the parameter `password` is used.
`hana_monitoring_configuration.hana_instances.secret_name`	`String` Optional. Specify the name of the secret in Secret Manager that stores the user account's password.
`hana_monitoring_configuration.hana_instances.enable_ssl`	`Boolean` Optional. Specifies whether or not SSL is enabled in your SAP HANA instance. The default value is `false`.
`hana_monitoring_configuration.hana_instances.host_name_in_certificate`	`String` If you specify `enable_ssl: true` for an SAP HANA instance, then you must specify the hostname that is set in the SSL certificate.
`hana_monitoring_configuration.hana_instances.tls_root_ca_file`	`String` If you specify `enable_ssl: true` for an SAP HANA instance, then you must specify the path for your security certificate.
`hana_monitoring_configuration.queries.enabled`	`Boolean` Optional. To enable a SQL query for all your SAP HANA instances, specify the value `true` for the parameter `enabled` for that SQL query.
`hana_monitoring_configuration.queries.name`	`String` If you have defined custom queries in your configuration file, then you must specify a unique name for each custom query. The query name must be unique because it is used to build the metric's default URL in Monitoring.
`hana_monitoring_configuration.queries.sql`	`String` Specify the SQL statement that the agent issues to your SAP HANA instances. The SQL statement must conform to the SQL syntax defined by SAP in SAP HANA SQL and System Views Reference.
`hana_monitoring_configuration.queries.sample_interval_sec`	`Int` Optional. Specify the sample interval for the SQL query. This overrides the global sample interval. The value must be 5 seconds or longer.
`hana_monitoring_configuration.queries.columns.name`	`String` Specify a name that uniquely identifies each column. The column name must be unique because it is used to build the metric's default URL in Monitoring.
`hana_monitoring_configuration.queries.columns.metric_type`	`String` For handling by Monitoring, specify one of the following metric types: `METRIC_LABEL`, `METRIC_GAUGE`, or `METRIC_CUMULATIVE`. Metrics of type `METRIC_LABEL` are appended as labels to all the `METRIC_GAUGE` and `METRIC_CUMULATIVE` metrics that are sent to Monitoring.
`hana_monitoring_configuration.queries.columns.value_type`	`String` For handling by Monitoring, specify a data type that is supported by the metric type. The supported data types are as follows: `VALUE_BOOL`, `VALUE_INT64`, `VALUE_STRING`, or `VALUE_DOUBLE`. For more information, see Supported combination.
`hana_monitoring_configuration.queries.columns.name_override`	`String` Optional. For handling by Monitoring, specify the path that you want to show in the metric URL instead of the query and column names. For example: Metric's default URL: `workload.googleapis.com/sap/hanamonitoring/QUERY_NAME/COLUMN_NAME` Metric URL using custom path: `workload.googleapis.com/sap/hanamonitoring/CUSTOM_PATH`

Troubleshooting

For information about diagnosing and resolving issues that you might encounter when you install and configure Google Cloud's Agent for SAP, see Google Cloud's Agent for SAP troubleshooting guide.

Get support

If you need help resolving problems with Google Cloud's Agent for SAP, then collect all available diagnostic information and contact Cloud Customer Care. For information about contacting Customer Care, see Getting support for SAP on Google Cloud.