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:

To install and configure version 3.6 (latest) 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 the latest version of 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

To install Google Cloud's Agent for SAP on a Bare Metal Solution server, follow these steps:

  1. Establish an SSH connection to your Bare Metal Solution server.

  2. In your terminal, install the agent by running the command that is specific to your operating system:

    • (Recommended) To install version 3.6 (latest) of the agent:

      RHEL

      sudo tee /etc/yum.repos.d/google-cloud-sap-agent.repo << EOM
      [google-cloud-sap-agent]
      name=Google Cloud Agent for SAP
      baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-el$(cat /etc/redhat-release | cut -d . -f 1 | tr -d -c 0-9)-x86_64
      enabled=1
      gpgcheck=1
      repo_gpgcheck=0
      gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
      EOM
      sudo yum install google-cloud-sap-agent

      SLES15

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles15-x86_64 google-cloud-sap-agent
      sudo zypper install google-cloud-sap-agent

      SLES 12

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles12-x86_64 google-cloud-sap-agent
      sudo zypper install google-cloud-sap-agent
    • To install a specific version of the agent:

      RHEL

      sudo tee /etc/yum.repos.d/google-cloud-sap-agent.repo << EOM
      [google-cloud-sap-agent]
      name=Google Cloud Agent for SAP
      baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-el$(cat /etc/redhat-release | cut -d . -f 1 | tr -d -c 0-9)-x86_64
      enabled=1
      gpgcheck=1
      repo_gpgcheck=0
      gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
      EOM
      sudo yum install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      SLES15

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles15-x86_64 google-cloud-sap-agent
      sudo zypper install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      SLES 12

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles12-x86_64 google-cloud-sap-agent
      sudo zypper install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      Replace VERSION_NUMBER with the agent's version number that you want to install, such as 3.1-606637668. For information about the agent versions that you can install, see List all available versions of the agent.

  3. Open the following configuration file:

    /etc/google-cloud-sap-agent/configuration.json

    Alternatively, you can also perform this configuration by running commands. For more information, see Configuration commands for Google Cloud's Agent for SAP.

  4. Modify or add the following parameters to the configuration file:

    • In the first section:
      • bare_metal: set to true.
    • Add the cloud_properties section and specify the following parameters:
      • project_id: specify your Google Cloud project
      • instance_name: specify the name of your Bare Metal Solution server
      • region: specify the region of your Bare Metal Solution server
  5. Save the configuration file.

  6. Restart the agent:

    sudo systemctl restart google-cloud-sap-agent
For more information about the configuration parameters, see Configuration parameters and example configuration.

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

  1. Establish an SSH connection with your Bare Metal Solution server.

  2. 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:

  1. In your SAP system, enter transaction ST06.
  2. 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 enable other features of the agent by performing the following configurations. By default, the collection of SAP Host Agent metrics and Workload Manager evaluation metrics is enabled.

Prerequisites

To enable the agent to access Google Cloud resources from a Bare Metal Solution environment, you need to complete the following prerequisites:

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 Workload Manager Insights Writer (roles/workloadmanager.insightWriter) role.

To create a service account, follow these steps:

  1. 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 Workload Manager > Workload Manager Insights Writer role to the service account.

      To grant the role, find the Select a role list, then select Workload Manager > Workload Manager Insights Writer.

    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.

  2. 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 3.6 (latest) of Google Cloud's Agent for SAP:

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

To view feature-specific example configuration files, see the configuration guide for that feature.

Configuration parameters

The following table describes the configuration parameters of Google Cloud's Agent for SAP that is running on a Bare Metal Solution server, including the parameters related to the collection of metrics. For information about the configuration parameters related to the Backint feature of the agent, see Configuration parameters.

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.

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.

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.

discovery_configuration.enable_workload_discovery

Boolean

To let the agent collect the names and versions of the SAP products running on the host, specify true. The default value is true.

For more information, see the agent's codebase in the google-cloud-sap-agent GitHub repository under GoogleCloudPlatform/sapagent.

discovery_configuration.enable_discovery

Boolean

To send to Cloud Logging the information that the agent collects about the SAP products running on the host, specify true. The default value is true.

If you specify the value false, then the agent stores the collected information on the host and doesn't send it to Cloud Logging.

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 specifying a plain text password, we recommend that you use one of the following options:

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.

The agent collects the SAP HANA related metrics only when you specify either hana_db_password_secret_name ,hdbuserstore_key, or hana_db_password.

collection_configuration.hana_metrics_config.hdbuserstore_key

String

To securely connect to an SAP HANA system, specify a Secure user store (hdbuserstore) key that you've created for that system.

To use an hdbuserstore key for authentication, ensure the following:

  • The SAP tools hdbsql and hdbuserstore are installed on the compute instance hosting the agent.
  • The hdbuserstore key corresponds to one specific SAP HANA instance. You can't use keys that contain hostnames of multiple SAP HANA instances.
  • The SIDadm user can query the SAP HANA database using this key. Here SID refers to the value that you've specified for the sid parameter. You can verify this by running the following command as the SIDadm user:
    hdbsql -U HDB_USERSTORE_KEY "SELECT * FROM DUMMY"

This configuration parameter is supported from version 3.3 of the agent.

collection_configuration.hana_metrics_config.sid

String

Specify the SID of your SAP HANA instance. If using a HANA Userstore key, refer to the hdbuserstore_key section.

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.

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_collection_definition.fetch_latest_config

Boolean

Optional. The default value is true, which enables the agent to collect the latest set of Workload Manager evaluation metrics without requiring you to update the agent. If you want to turn off this behavior, then specify this parameter in your configuration file and set its value to false.

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

String

Specify the password for the user account that is used to query the SAP HANA instance.

For SAP HANA authentication, the agent uses the following order of preference: if specified, the hdbuserstore_key configuration parameter is preferred over the hana_db_password parameter, which is preferred over the hana_db_password_secret_name parameter. We recommend that you set only one authentication option in your configuration file.

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.

Alternatively, you can specify the hdbuserstore_key configuration parameter to authenticate the specified SAP HANA user.

For SAP HANA authentication, the agent uses the following order of preference: if specified, the hdbuserstore_key configuration parameter is preferred over the hana_db_password parameter, which is preferred over the hana_db_password_secret_name parameter. We recommend that you set only one authentication option in your configuration file.

collection_configuration.workload_validation_db_metrics_config.hdbuserstore_key

String

To securely connect to an SAP HANA system, specify a Secure user store (hdbuserstore) key that you've created for that system.

To use an hdbuserstore key for authentication, ensure the following:

  • The SAP tools hdbsql and hdbuserstore are installed on the compute instance hosting the agent.
  • The hdbuserstore key corresponds to one specific SAP HANA instance. You can't use keys that contain hostnames of multiple SAP HANA instances.
  • The SIDadm user can query the SAP HANA database using this key. Here SID refers to the value that you've specified for the sid parameter. You can verify this by running the following command as the SIDadm user:
    hdbsql -U HDB_USERSTORE_KEY "SELECT * FROM DUMMY"

This configuration parameter is supported from version 3.3 of the agent.

If you specify hdbuserstore_key, then you can skip specifying the hostname and port parameters.

For SAP HANA authentication, the agent uses the following order of preference: if specified, the hdbuserstore_key configuration parameter is preferred over the hana_db_password parameter, which is preferred over the hana_db_password_secret_name parameter. We recommend that you set only one authentication option in your configuration file.

collection_configuration.workload_validation_db_metrics_config.sid

String

Specify the SID of your SAP HANA instance.

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.

Make sure that this user has the privilege to read the monitoring views in your SAP HANA database. If this privilege is not granted, then the SAP HANA monitoring metrics related to the monitoring views contain no data.

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.

For 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.
  • (Recommended) An hdbuserstore key to the parameter hdbuserstore_key.
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.hdbuserstore_key

String

To securely connect to an SAP HANA system, specify a Secure user store (hdbuserstore) key that you've created for that system.

To use an hdbuserstore key for authentication, ensure the following:

  • The SAP tools hdbsql and hdbuserstore are installed on the compute instance hosting the agent.
  • The hdbuserstore key corresponds to one specific SAP HANA instance. You can't use keys that contain hostnames of multiple SAP HANA instances.
  • The SIDadm user can query the SAP HANA database using this key. Here SID refers to the value that you've specified for the sid parameter. You can verify this by running the following command as the SIDadm user:
    hdbsql -U HDB_USERSTORE_KEY "SELECT * FROM DUMMY"

This configuration parameter is supported from version 3.3 of the agent.

If you specify hdbuserstore_key, then you can skip specifying the host and port parameters.

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.