Tutorial: Scaling a Spring App on a Custom Metric

Page last updated:

This tutorial shows you how to scale a sample Spring app based on a custom metric in VMware Tanzu Application Service for VMs (TAS for VMs).

Overview

TAS for VMs can automatically scale apps based on custom metrics. The following table describes the main components involved in this workflow and how they correspond to steps in this tutorial.

Component Description Related Tutorial Steps
App The app must emit custom metrics that are created with the open-source tool, Prometheus. This tutorial includes a sample Spring app that does that. Review the Sample App and Push the Sample App
Metric Registrar The Metric Registrar is a component of TAS for VMs that allows app developers to export custom app metrics to the logging system. It has its own CLI plugin. Register a Custom Metrics Endpoint
App Autoscaler App Autoscaler is a service integrated with Apps Manager that automatically scales apps in your environment based on app metrics or a schedule. See the Scaling an App Using App Autoscaler topic for more information. Create and Autoscaling Rule and Trigger Scaling

Prerequisites

This tutorial requires the following:

  • A TAS for VMs environment with the Metric Registrar enabled. You can confirm this with your platform operator.
  • Access to Apps Manager in the TAS for VMs environment.
  • The ability to push an app to the TAS for VMs environment. For example, you need space developer permissions in at least one space.
  • The Cloud Foundry Command Line Interface (cf CLI). See Installing the cf CLI.
  • Access to a command-line for running commands such as cf CLI and git commands.

Review the Sample App

The sample app code is in the pivotal-cf/metric-registrar-examples GitHub repository. It is a Spring app with a simple UI that includes several buttons to call different endpoints. Some of these endpoints are instrumented to produce metrics.

You can see what the UI looks like in the Push the Sample App section, which includes a screenshot. The following sections provide some details about the code.

Dependencies

You can view the app dependencies in the build.gradle file:

dependencies {
    implementation('io.micrometer:micrometer-registry-prometheus')
    implementation('org.springframework.boot:spring-boot-starter-actuator')
    implementation('org.springframework.boot:spring-boot-starter-security')
    implementation('org.springframework.boot:spring-boot-starter-web')
    testImplementation('org.springframework.boot:spring-boot-starter-test')
    testImplementation('org.springframework.security:spring-security-test')
}

The dependencies include the Micrometer Prometheus library, which does the following:

  • Creates a metrics endpoint at /actuator/prometheus in a format supported by the Metric Registrar.
  • Allows you to instrument the app by creating new metrics. See Instrumentation below.

The Spring Security dependency exposes the endpoints so they can be reached by Metric Registrar.

Instrumentation

This section describes how the app is instrumented. Instrumentation refers to how metrics have been added for a particular function.

See the ExampleController.java file from the sample app code:

  • The ExampleController class includes a MeterRegistry object, which is passed and set in the constructor.

    private MeterRegistry registry;
private AtomicLong custom;

public ExampleController(MeterRegistry registry) {
   this.registry = registry;
   this.custom = new AtomicLong(0L);
}

  • It also includes a custom variable that is initialized in the constructor. In the customMetric handler, this variable gets passed to the registry and incremented or decremented. 

    public ResponseEntity<String> customMetric(@RequestParam(value="inc", defaultValue="") String increment) {
    AtomicLong customGauge = registry.gauge("custom", this.custom);
    if (!"".equals(increment)) {
        customGauge.incrementAndGet();
    } else {
        customGauge.decrementAndGet();
    }

    Note: The App Autoscaler only scales on a gauge, or metric, that can go up and down. The standard metrics of CPU, disk, HTTP throughput, and HTTP latency are all gauges.

Push the Sample App

To push the sample app:

  1. Open a terminal window and clone the git repository that contains the sample app: 

    git clone git@github.com:pivotal-cf/metric-registrar-examples.git

  2. Navigate to the app directory:

    cd metric-registrar-examples/java-spring-security

  3. Build the app:

    ./gradlew build

  4. Push the app with a random route:

    cf push --random-route

  5. After the push command finishes, locate the app URL in the routes: section of the output. See the following example output: 

    Waiting for app to start...
    Uploaded droplet (60.5M)
    Uploading complete
    Cell 333e7fdf-806e-424d-b3a0-78967ecb6d28 stopping instance 6f345835-8beb-48a5-b578-921f5de442c6
    


    name:              tutorial-example
requested state:   started
routes:            tutorial-example-random-route.cfapps.io
last uploaded:     Wed 28 Aug 11:02:33 PDT 2019

  6. In a browser, navigate to the app URL. The app UI looks like what you see in the image below. The text following the image describes the details of the UI.
    It has the following buttons:

    • Increment Custom gauge and Decrement custom gauge:
      These buttons cause the custom metric to increase or decrease by a value of 1. You use these buttons later when you Trigger Scaling.
    • See the metrics:
      This button opens /actuator/prometheus in your browser. You can use it to view values for custom and all the metrics produced by Micrometer. This page is important because Metric Registrar uses it to collect metrics.
    • Increment Simple counter and Call an endpoint with high latency:
      You can ignore these buttons, as they are not used in this tutorial. To learn more about what they do, see the app code.

Register a Custom Metrics Endpoint

When you want to your app to emit custom metrics, you register the app as a metric source with the Metric Registrar.

To register a custom metrics endpoint for the app:

  1. Install the Metric Registrar CLI:

    cf install-plugin -r CF-Community "metric-registrar"

  2. Register the metrics endpoint of the app. Because the app dependencies include the Micrometer Prometheus library, there is automatically a metrics endpoint at /actuator/prometheus. Run the command below and replace APP-NAME with the name of your app.

    cf register-metrics-endpoint APP-NAME /actuator/prometheus

  3. Install the Log Cache CLI. Log Cache is a feature in TAS for VMs that lets you filter and query app logs. For more information, see Example Uses of the Log Cache CLI Plugin.

    cf install-plugin -r CF-Community "log-cache"

  4. View the app metrics as the are emitted using the command below. The --follow flag appends output as metrics are emitted. 

    cf tail APP-NAME --envelope-class metrics --follow

    The output looks similar to the following example. The custom metric displays in the output.

    Retrieving logs for app tutorial-example in org sandbox / space development as example@user...

2019-08-28T09:17:56.28-0700 [tutorial-example/1] GAUGE cpu:0.289158 percentage disk:135716864.000000 bytes disk_quota:1073741824.000000 bytes memory:399979315.000000 bytes memory_quota:2147483648.000000 bytes
2019-08-28T09:17:56.50-0700 [tutorial-example/0] GAUGE custom:1.000000

    Note: If you do not see output similar to the above, Metric Registrar may not be enabled in your Ops Manager installation. Contact your platform operator to confirm.

Create an Autoscaling Rule

The App Autoscaler component is integrated with Apps Manager. This is where you can create rules.

To create an autoscaling rule for the app and custom metric:

  1. Navigate to the app in Apps Manager.

  2. Click Enable Autoscaling.

    The app page for an app named java-metric-registrar-demo shows the Enable Autoscaling button being clicked.

  3. Click Manage Autoscaling.

  4. Modify the Instance Limits.
    App Autoscaler keeps instance counts within a range defined by minimum and maximum values, or instance limits.

    1. For Minimum, enter 1.
    2. For Maximum, enter 5.

    3. Click Apply Changes.

      The Manage Autoscaling form includes an Instance Limits section. This section includes two textboxes, one for Minimum and one for Maximum. To the right of these textboxes is the Apply Changes button. 1 is entered for Minimum and 5 is entered for Maximum

  5. Create an autoscaling rule.
    App Autoscaler increases or decreases instance counts based on how a current metric compares with configured Scale up and Scale down thresholds.

    1. In the Scaling Rules section, click EDIT.
    2. Click ADD RULE.
    3. For Rule Type, select Custom.
    4. For Scale down if less than, enter 2. This and the following value are examples for the purposes of demonstrating the feature in this tutorial.
    5. For Scale up if more than, enter 5.
    6. For Metric, enter custom. This is the name of the metric specified in the app code.

    7. Click Save.

      The Edit Scaling Rules form includes a dropdown menu labeled Rule Type, a textbox labeled Scale down if less than, a textbox labeled scale up if more than, and a textbox labeled Metric. They are configured according the corresponding instructions. The form also includes buttons labeled Add Rule, Cancel, and Save.

Trigger Scaling

Now that you have pushed an app that emits a custom metric and configured autoscaling rules, you can trigger a scaling action. App Autoscaler scales the app when the custom metric goes above or below the threshold specified in the scaling rule.

To trigger scaling:

  1. Navigate to the web UI of the app. Use the same URL from Push the Sample App.

  2. Click Increment Custom gauge enough times to bring the custom metric over the threshold of 5 that you set in the scaling rule. You can check the value of the custom metric using the See Metrics button.

  3. Monitor the app page in Apps Manager for about two minutes. App Autoscaler will begin to scale the app. It adds one instance at a time until it reaches the Maximum instance limit of 5.

Next Steps

Now that you have completed this tutorial, try emitting custom metrics and creating scaling rules with your own app. Review the resources listed in the Overview section to learn more. Once you have instrumented your app to emit custom metrics, you can follow the steps outlined in this tutorial to scale based on those metrics.