SAP HANA Monitoring Agent User Guide

Google Cloud Platform (GCP) provides a custom monitoring agent that collects custom metrics from SAP HANA and sends them to Google Stackdriver Monitoring, GCP's built-in monitoring solution. With Stackdriver Monitoring, you can build out dashboards to visualize your SAP HANA metrics and set up alerts based on metric thresholds. For more information, see the Stackdriver Monitoring documentation.

Prerequisites

This guide assumes that you have deployed SAP HANA on GCP using the method described in the SAP HANA Deployment Guide.

Setting up Stackdriver Monitoring for your project

To use Google's monitoring agent for SAP HANA, you must set up a new Stackdriver account that is connected to your GCP project. The following steps create a new Stackdriver account that has a free 30-day trial of Stackdriver Premium service:

  1. In your browser, go to Stackdriver Monitoring:

    Go to Stackdriver Monitoring

  2. Click Add Stackdriver account.

  3. On the Create your free Stackdriver account page, click the Google Cloud Platform project field. A dropdown containing your GCP projects appears.
  4. Select your project from the dropdown and click Create Account.
  5. On the Add Google Cloud Platform projects to monitor page, click Continue.
  6. On the Monitor AWS accounts page, click Skip AWS Setup.
  7. On the Install the Stackdriver Agents page, click Continue.
  8. On the Get Reports by Email page, select No reports and then click Continue.
  9. After the message "Finished initial collection!" appears, click Launch monitoring to enter your Stackdriver account dashboard.
  10. Click Continue with the trial to finish setup.

You now have a Stackdriver account tied for your GCP project, and the monitoring agent can send metrics to Stackdriver.

Setting the required IAM roles

By default, the monitoring agent uses your Compute Engine virtual machine (VM) instance's default service account. This service account allows binaries running on the VM instance to write metrics to Stackdriver. If you choose to use a different service account, you must manually add the IAM role that provides these permissions to your service account.

To add the required IAM role to your service account:

  1. Go to the IAM & Admin page in the Cloud Platform Console.

    Go to the IAM & Admin page

  2. Select your project and click Continue.

  3. Identify the service account to which you want to add a role.

    • If the service account isn't already on the members list, it doesn't have any roles assigned to it. Click Add member and enter the email address of the service account.
    • If the service account is already on the members list, it has existing roles. Click the current role dropdown list for the service account that you want to edit.
  4. Select Monitoring > Monitoring Metric Writer from the list of available roles.

  5. Click Add or Save to apply the roles to the service account.

Installing the agent

Choosing a deployment location

The monitoring agent can be run directly on one or more nodes in your SAP HANA installation, or indirectly as a service on another VM instance. Choose your deployment location based on your use case.

Downloading and installing the agent

To download and install the agent:

  1. Establish an SSH connection with your SAP HANA VM instance.
  2. Download and run the installation script:

    curl https://storage.googleapis.com/gcm-ext/gcm_install.sh | bash -x
    

When you run the above command, the installation script performs the following operations:

  1. Creates the following directories:

    • /usr/local/lib/gcm, which will contain the agent binary.
    • /etc/gcm.d, which will contain the queries you want the agent to run.
    • /var/spool/gcm, which contains the metrics that have recently been gathered by the agent. The agent eventually sends these metrics to Stackdriver Monitoring.
  2. Downloads the latest release of the agent and saves it to /usr/local/lib/gcm/.

  3. Creates a symlink to the binary in /usr/local/bin/gcm.
  4. Creates a basic configuration template, /etc/default/gcm.
  5. Creates a daemon configuration file, /etc/systemd/system/gcm.service.
  6. Reloads the systemd service definitions.
  7. Enables the monitoring agent as a daemon.

Configuring the agent

After running the install script, configure the VM instances that the agent will monitor and, optionally, the queries that the agent will perform on your database.

Defining the configuration file

When you ran the installation script, it created a configuration template file at the following location:

/etc/default/gcm

The contents of that configuration file look like this:

---
config:
  timestamps_in_output: no
  debug_messages: yes
  skip_default_queries: yes
  queries_directory: /tmp/tmp.kUbZiUaGHa/queries
  spool_directory: /tmp/tmp.kUbZiUaGHa/staging
  enabled_instances:
    - [INSTANCE_NAME]
  instances:
    - name: [INSTANCE_NAME]
      host: [INSTANCE_IP]
      port: [PORT_NUMBER]
      user: [DB_USERNAME]
      password: [YOUR_PASSWORD]
    - name: [INSTANCE_NAME_2]
      host: [INSTANCE_IP_2]
      ...

You can configure the agent to query SAP HANA on one or more VM instances. For each VM instance you want to monitor:

  1. Add a new VM instance definition under instances. For each instance, define the name, host, port, user, and password.
  2. To enable the agent to collect metrics from that VM instance, add the VM instance name under enabled_instances.

In the above sample, the attributes of each instance should be defined as follows:

  • [INSTANCE_NAME]: The name of the Compute Engine VM instance you want to monitor.
  • [INSTANCE_IP]: The internal or external IP of the Compute Engine VM instance you want to monitor. Google recommends using internal IPs if possible, as they require less setup than external IPs and are private and secure by default.
  • [DB_USERNAME]: The SAP HANA database user you want to use.
  • [PORT_NUMBER]: The port number of your SAP HANA database. Usually, the port number is 39015 for SAP HANA Express or 30015 for SAP HANA Platform Edition.
  • [YOUR_PASSWORD]: The user password for your database user.

Optionally, you can configure the agent using the following flags. These parameters flags must be set before the config item:

  • timestamps_in_output (boolean). If you're running the agent as a daemon under systemd, set this to no, as systemd provides timestamps. Default value is no.
  • debug_messages (boolean): If set, show debug messages. Default value is yes.
  • skip_default_queries (boolean): Skips the default set of queries. Does not affect user-defined queries. Default value is no.
  • queries_directory (string): The directory in which to look for user-defined queries. Default value is /etc/gcm.d.
  • spool_directory (string): The directory in which to collect spooled metrics. Default value is /var/spool/gcm.

Defining custom queries

By default, the agent gathers a default set of metrics from your SAP HANA database. For descriptions of these metrics, as well as the queries that generate the metrics, see SAP HANA Default Metrics.

You can add additional queries by creating one or more custom YAML files in the following directory:

/etc/gcm.d

The following is an example query file:

- root: by_component
  description: |
      Amount of memory (in MiB) used by service components
  query: |
    SELECT
             HOST AS "host",
             COMPONENT AS "component",
             SUM(USED_MEMORY_SIZE)/1024/1024 AS "mem_used_mb"
        FROM M_SERVICE_COMPONENT_MEMORY
    GROUP BY HOST, COMPONENT;
  columns:
    - type: LABEL
      value_type: STRING
      name: host
    - type: LABEL
      value_type: STRING
      name: component
    - type: GAUGE
      description: Amount of memory (in MiB) used by the service component
      value_type: DOUBLE
      name: mem_used_mb

Each YAML file comprises one or more items that represent the results of a given SQL query into your SAP HANA database's metrics. Each item has the following attributes:

  • root: A descriptive namespace for a given group of metrics.
  • query: The SQL query.
  • columns: The data type, value type, and column name for each field in the query.

    • type: Describes how the data is reported to Stackdriver. You can set type to LABEL, which indicates that that the type is a column head, or toGAUGE, one of the metric types defined in the Stackdriver API's MetricKind enum. Currently, GAUGE is the only metric type supported by the agent.
    • value_type: The value type of the metric. The value of this parameter can be any of the value types defined in the Stackdriver API's ValueType enum.
    • name: The name of the column.

For a full list of the system views that SAP HANA makes available for querying, see the SAP HANA SQL and System Views Reference.

Performing basic operations

This section describes how to perform basic operations with the SAP HANA monitoring agent. For a full list of configurable options, run gcm --help.

Managing the monitoring agent daemon

When you ran the installation script, the installer created a systemd unit file for the agent, allowing you to manage the agent using standard systemctl commands. The following commands start, stop, and poll the status of the agent, respectively:

sudo systemctl start gcm
sudo systemctl stop gcm
sudo systemctl status gcm

To read the logs generated by systemctl, query the contents of the systemd journal by using the following command:

sudo journalctl -u gcm

To see the last few lines that were logged, you can add the -f flag, which functions like a pipe to tail -f:

sudo journalctl -u gcm -f

Suppressing default queries

By default, the agent runs its default queries in addition to any custom queries you've defined. You can disable this default set of queries by setting the skip_default_queries flag to yes in your config file, or by setting the --no-defaults flag when running the tool manually. For more information, see Defining the configuration file.

Manually collecting and sending metrics

To verify that the agent works as expected, you can manually run commands to run your queries, collect the resulting metrics, and then send them to Stackdriver Monitoring. To run your queries and collect the resulting metrics exactly once, run the following command:

sudo gcm gather

To send the metrics collected by the agent when you ran your queries, run the following command:

sudo gcm send

Viewing your metrics in Stackdriver Monitoring

To display the metrics collected by Stackdriver Monitoring in your own charts and dashboards:

  1. In the left-hand menu of Stackdriver Monitoring Console, select Dashboards > Create Dashboard.

    Go to the Create Dashboard page

  2. Click Add Chart.

  3. In the Resource Type menu, select Custom Metrics.
  4. In the Metric menu, select by_component/mem_used_mb. Leave the other fields with their default values. You see the chart data in the Preview section of the panel.
  5. Click Save.

You now have a simple dashboard displaying live metrics from your SAP HANA VM instance or instances.

Troubleshooting

Default queries are failing

Make sure that your SAP HANA database user has access to the following SAP HANA system views:

  • M_CS_ALL_COLUMNS
  • M_CS_TABLES
  • M_EXPENSIVE_STATEMENTS
  • M_HOST_RESOURCE_UTILIZATION
  • M_SERVICE_COMPONENT_MEMORY
  • M_SERVICE_MEMORY

Metrics are not being sent to Stackdriver Monitoring

Make sure that your GCP service account has permission to write metrics to Stackdriver Monitoring. For details, see Setting the required IAM roles.

Support

For issues with the monitoring agent, or other feedback or concerns, please contact gcp-integrations-support@google.com.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...