Version 2: Configure SAP HANA Monitoring metrics collection

This guide shows you how to configure version 2 of Google Cloud's Agent for SAP to collect the SAP HANA monitoring metrics from your SAP HANA systems.

For information about this feature, see Monitoring SAP HANA using Google Cloud's Agent for SAP.

Before you begin

Validate your installation of Google Cloud's Agent for SAP. For instructions, see the installation guide for your scenario.
If you have installed the agent on a Bare Metal Solution server, then make sure that you have completed the required prerequisites and set up a service account. For instructions, see Configure Google Cloud's Agent for SAP on Linux.

Set IAM roles

To allow Google Cloud's Agent for SAP collect the SAP HANA Monitoring metrics, you must ensure that the service account being used by your Compute Engine instance or Bare Metal Solution server includes the following roles:

Compute Viewer (roles/compute.viewer)
Monitoring Metric Writer (roles/monitoring.metricWriter)
Secret Manager Secret Accessor (roles/secretmanager.secretAccessor), if you use Secret Manager for storing SAP HANA database password.

To add these required roles to your service account, follow these steps:

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

Go to IAM
Select your Google Cloud project.
Identify the service account to which you want to add a role.
- If the service account isn't already on the principals list, then it doesn't have any roles assigned to it. Click Add and 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 button for the service account that you want to edit.
Select the required role from the list of available roles:
- Compute Viewer
- Monitoring > Monitoring Metric Writer
- Secret Manager > Secret Manager Secret Accessor
Click Add or Save to apply the roles to the service account.

Enable SAP HANA Monitoring metrics collection

To enable the collection of SAP HANA Monitoring metrics using Google Cloud's Agent for SAP, follow these steps:

Establish an SSH connection with your Compute Engine instance or Bare Metal Solution server.

Open the agent's configuration file:

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

In the hana_monitoring_configuration section, perform the following:
- For the parameter enabled, set the value true.
- In the hana_instances section, specify the SAP HANA instances that you want the agent to monitor.
- Optionally, define custom queries. For information about defining custom queries and see examples, see Defining custom queries.
- Optionally, disable the built-in or default queries. For instructions, see Disable a SQL query.
  
  For information about the configuration parameters, see Configuration parameters.
Optionally, under the cloud_properties section, you can update the parameter values that are set automatically. To do so, add the cloud_properties section to your configuration file, and then specify the required parameters and their values.
Save the configuration file.
Restart the agent for the new settings to take effect:
```
sudo systemctl restart google-cloud-sap-agent
```

Example configuration files

Compute Engine instance

The following example is a completed configuration file of Google Cloud's Agent for SAP running on a Compute Engine instance, where the collection of SAP HANA monitoring metrics is enabled. Note that the custom query included in this example, named custom_query, follows the custom query definition guidelines specified in Defining custom queries.

{
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "collect_process_metrics": false
  },
  "cloud_properties": {
    "project_id": "my-project",
    "instance_name": "instance-1",
    "image": "rhel-8"
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": true,
    "sample_interval_sec": 60,
    "query_timeout_sec": 30,
    "execution_threads": 20,
    "hana_instances": [
      {
        "name": "local",
        "sid": "DEH",
        "host": "localhost",
        "port": "30015",
        "user": "system",
        "secret_name": "password-secret-name"
      },
      {
        "name": "remote",
        "sid": "DEH",
        "host": "10.123.0.12",
        "port": "30015",
        "user": "system",
        "secret_name": "password-secret-name"
      }
    ],
    "queries": [
      {
        "name": "custom_query",
        "enabled": true,
        "sql": "SELECT * FROM MyTable;",
        "columns": [
          {
            "name": "string",
            "metric_type": "METRIC_LABEL",
            "value_type": "VALUE_STRING"
          },
          {
            "name": "bool",
            "metric_type": "METRIC_GAUGE",
            "value_type": "VALUE_BOOL"
          },
          {
            "name": "int",
            "metric_type": "METRIC_GAUGE",
            "value_type": "VALUE_INT64"
          },
          {
            "name": "double",
            "metric_type": "METRIC_GAUGE",
            "value_type": "VALUE_DOUBLE"
          }
        ]
      },
      {
        "name": "default_host_queries",
        "enabled": false
      }
    ]
  }
}

Bare Metal Solution server

The following example is a completed configuration file of Google Cloud's Agent for SAP running on a Bare Metal Solution server, where the collection of SAP HANA monitoring metrics is enabled. Note that the custom query included in this example, named custom_query, follows the custom query definition guidelines specified in Defining custom queries.

{
  "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
  },
  "cloud_properties": {
    "project_id": "my-project",
    "instance_name": "bms-machine-1"
    "region": "us-central1",
    "image": "rhel-8"
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": true,
    "sample_interval_sec": 60,
    "query_timeout_sec": 30,
    "execution_threads": 20,
    "hana_instances": [
      {
        "name": "local",
        "sid": "DEH",
        "host": "localhost",
        "port": "30015",
        "user": "system",
        "secret_name": "password-secret-name"
      },
      {
        "name": "remote",
        "sid": "DEH",
        "host": "10.123.0.12",
        "port": "30015",
        "user": "system",
        "secret_name": "password-secret-name"
      }
    ],
    "queries": [
      {
        "name": "custom_query",
        "enabled": true,
        "sql": "SELECT * FROM MyTable;",
        "columns": [
          {
            "name": "string",
            "metric_type": "METRIC_LABEL",
            "value_type": "VALUE_STRING"
          },
          {
            "name": "bool",
            "metric_type": "METRIC_GAUGE",
            "value_type": "VALUE_BOOL"
          },
          {
            "name": "int",
            "metric_type": "METRIC_GAUGE",
            "value_type": "VALUE_INT64"
          },
          {
            "name": "double",
            "metric_type": "METRIC_GAUGE",
            "value_type": "VALUE_DOUBLE"
          }
        ]
      },
      {
        "name": "default_host_queries",
        "enabled": false
      }
    ]
  }
}

Define a custom SQL query

Google Cloud's Agent for SAP collects the SAP HANA monitoring metrics by running SQL queries on your SAP HANA instances. In addition to these default queries, you can define and run custom SQL queries by completing the following steps:

Establish an SSH connection with your Compute Engine instance or Bare Metal Solution server.

Open the agent's configuration file:

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

Under the hana_monitoring_configuration.queries section, define your custom query.

For information about defining custom queries and see examples, see Defining custom queries.
To enable a custom query, set its enabled parameter to true.
Save the configuration file.
Restart the agent for the new settings to take effect:
```
sudo systemctl restart google-cloud-sap-agent
```

Disable a SQL query

If you don't want to run any of the built-in SQL queries that Google Cloud's Agent for SAP provides by default, or any of the custom queries that you define, then you can disable the SQL query by completing the following steps:

Establish an SSH connection with your Compute Engine instance or Bare Metal Solution server.

Open the agent's configuration file:

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

To disable a built-in or default query, include the following under the hana_monitoring_configuration.queries section:
```
{
"name": "default_QUERY_NAME",
"enabled": false
}
```
Replace QUERY_NAME with the name of the default query. For information about the default queries, see Default query reference.
To disable a custom query, set the enabled parameter to false for that custom query.
Save the configuration file.
Restart the agent for the new settings to take effect:
```
sudo systemctl restart google-cloud-sap-agent
```

Configuration parameters

The following table explains the configuration parameters of Google Cloud's Agent for SAP that are specific to the collection of the SAP HANA Monitoring metrics.

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 Compute Engine instance, by default, the agent detects the project ID automatically.
`cloud_properties.instance_name`	`String` If your SAP system is running on a Compute Engine instance, then specify the name of that compute instance. The agent automatically detects the compute instance name upon installation. If your SAP system is running on a Bare Metal Solution server, then specify the name of that server. 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 compute instance, by default, the agent uses the region where the compute instance is deployed.
`cloud_properties.zone`	`String` When the agent runs on a compute instance, by default, the agent uses the zone where the compute instance is deployed.
`cloud_properties.image`	`String` Specify the OS image name of the instance. When the agent runs on a compute instance, by default, the agent automatically detects the OS image used by the compute instance.
`cloud_properties.numeric_project_id`	`String` Specify the numeric ID of the Google Cloud project where the SAP system is running. When the agent runs on a compute instance, by default, the agent automatically detects project number.
`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`.
`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`

View the collected metrics

To visualize the SAP HANA Monitoring metrics that the agent collects, you can use the following custom dashboards that Google Cloud provides:

Agent for SAP - Detailed HANA Overview: This dashboard provides charts that display status overview for the following metrics: Instance memory, service memory used, schema estimated maximum memory, rowstore memory total size, schema read outliers, schema write outliers, schema last compressed record count outliers, system connections, alerts, CPU percentage for the top 5 compute instances, memory percentage for the top 5 compute instances, and the hosts by region.

The JSON file for this dashboard is agent-for-sap-hana-detailed-overview.json.
Agent for SAP - HANA performance: This dashboard provides charts that display raw metric values for the following metrics: Instance memory, schema read and write outliers, schema performance, memory usage, schema record count outliers, service total memory used, rowstore memory size, system idle and running connections, connection and rowstore memory, schema total records, and the schema estimated maximum total size.

The JSON file for this dashboard is agent-for-sap-hana-performance.json.

Install dashboards

To install a custom dashboard, complete the following steps:

Google Cloud console

In the Google Cloud console, go to the Monitoring page:

Go to Monitoring
In the Monitoring navigation panel, click Dashboards.
Click the Sample library tab.
To filter the agent-specific custom dashboards, in the Filter field, type Agent for SAP.
(Optional) To view details about a dashboard or to preview its contents, click Preview.
Select the dashboard that you want to install.
Click Import, and then click Confirm.

The dashboard is added to the available dashboards in your Google Cloud project. To see your dashboard, follow the instructions in View the installed dashboard.

Google Cloud CLI

Open the Cloud Shell:

Open Cloud Shell

In the Cloud Shell, clone or download the repository:

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

In the Cloud Shell, install the required dashboard using the corresponding JSON file:
```
gcloud monitoring dashboards create --config-from-file=CONFIG_FROM_FILE
```
Replace CONFIG_FROM_FILE with the path to the JSON file that contains the dashboard configuration. Dashboard configuration files can be located at path: monitoring-dashboard-samples/dashboards/google-cloud-agent-for-sap.

The dashboard is added to the available dashboards in your Google Cloud project. To see your dashboard, follow the instructions in View the installed dashboard.

View the installed dashboards

To view the installed dashboards, follow these steps:

In the Google Cloud console, go to the Monitoring page:

Go to Monitoring
In the Monitoring navigation panel, click Dashboards.
Click the dashboard name in the list.

If you have a lot of dashboards, then you can filter for custom dashboards or for the name of the new dashboard. For information on filtering this list, see View custom dashboards.

The following image is an example that shows a part of the custom dashboard for SAP HANA metrics in Monitoring.

Screen capture shows the custom dashboard for SAP HANA metrics
in Monitoring