Configure App Autoscaler to use custom scaling metrics

You can configure App Autoscaler to use Custom App Metrics when scaling apps in your VMware TAS for VMs deployment.

For information about how to emit Custom App Metrics, see Using Metric Registrar.

Custom scaling metrics overview

While Autoscaler can use several default metrics as scaling metrics for apps, your app might require specific autoscaling requirements that Autoscaler cannot meet by using the default scaling metrics to scale the app. In this case, you might create Custom App Metrics for Autoscaler to use to scale the app.

Before configuring Autoscaler to use a custom scaling metric, you must register the metrics endpoint of the app with the Metric Registrar. For more information, see Using Metric Registrar.

You can configure Autoscaler to use a custom scaling metric for an app in the following ways:

Through the Cloud Foundry Command-Line Interface (cf CLI). For more information, see Configuring a custom scaling metric for an app through the cf CLI.
Through Apps Manager. For more information, see Configure a custom scaling metric for an app through Apps Manager.

To monitor when Autoscaler scales an app based on changes in a custom scaling metric, see Reviewing autoscaling events for changes in a custom scaling metric.

For information about use cases that might complicate or prevent you from configuring a custom scaling metric for an app, see Special Considerations for using a custom scaling metric.

VMware recommends that you load test your app to verify that the autoscaling rules you configured are effective. For more information, see Load-testing your app in Using Autoscaler in Production.

Configure a custom scaling metric for an app through the cf CLI

The procedures in this section describe how to configure Autoscaler to use a custom scaling metric for an app through the cf CLI.

You can configure Autoscaler to use a custom scaling metric for an app in the following ways:

Using a manifest file. For more information, see Configure an autoscaling rule using a manifest file.
Using CLI commands. For more information, see Configure an autoscaling rule using CLI commands.

For the procedures in this section, you must use the App Autoscaler CLI plug-in. To download and install the App Autoscaler CLI plug-in, see Install the app Autoscaler CLI plug-in in Using the App Autoscaler CLI.

Configure an autoscaling rule by using a manifest rule

You can configure autoscaling rules declaratively through a manifest file. This manifest file only configures Autoscaler, and does not interfere with any other existing app manifest files in your TAS for VMs deployment.

To configure an autoscaling rule that defines a custom scaling metric using a manifest file:

In a terminal window, target the space in which the app you want to scale is deployed by running:
```
cf target -o ORG-NAME -s SPACE-NAME
```
Where:
- ORG-NAME is the name of the org containing the space in which the app you want to scale is deployed.
- SPACE-NAME is the name of the space in which the app you want to scale is deployed.
If the space in which the app you want to scale is deployed does not already have an Autoscaler service instance of Autoscaler deployed in it, create an Autoscaler service instance by running:
```
cf create-service app-autoscaler PLAN-NAME SERVICE-NAME
```
Where:
- PLAN-NAME is the name of the service plan you want to use for the Autoscaler service instance.
- SERVICE-INSTANCE-NAME is the name you want to give the Autoscaler service instance. For example, autoscaler.
If there is already an Autoscaler service instance in the space in which the app you want to scale is deployed, skip this step.
Bind the Autoscaler service instance you created in the previous step to the app you want to scale by running:
```
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
```
Where:
- APP-NAME is the name of the app you want to scale.
- SERVICE-INSTANCE-NAME is the name of the Autoscaler service instance in the previous step.
To create a manifest file for Autoscaler that configures an autoscaling rule with a custom scaling metric, create a YAML file that includes the following configuration parameters:
```
---
instance_limits:
  min: LOWER-SCALING-LIMIT
  max: UPPER-SCALING-LIMIT
rules:
- rule_type: custom
  metric: METRIC-NAME
  threshold:
    min: MINIMUM-METRIC-THRESHOLD
    max: MAXIMUM-METRIC-THRESHOLD
scheduled_limit_changes: []
```
Where:
- LOWER-SCALING-LIMIT is the minimum number of instances you want Autoscaler to create for the app.
- UPPER-SCALING-LIMIT is the maximum number of instances you want Autoscaler to create for the app.
- METRIC-NAME is the name of the custom scaling metric. This name must match the name of the metric that the app exposes.
- MINIMUM-METRIC-THRESHOLD is the minimum custom scaling metric threshold. If the average value of the custom scaling metric falls below this number, Autoscaler scales the number of app instances down.
- MAXIMUM-METRIC-THRESHOLD is the maximum custom scaling metric threshold. If the average custom scaling metric rises above this number, Autoscaler scales the number of app instances up.
The following example shows an Autoscaler manifest file configuring Autoscaler to use example_metric as its custom scaling metric, with a minimum custom scaling metric threshold of 20 and a maximum custom scaling metric threshold of 50:
```
---
instance_limits:
  min: 10
  max: 100
rules:
- rule_type: custom
  metric: example_metric
  threshold:
    min: 20
    max: 50
scheduled_limit_changes: []
```
Apply the Autoscaler manifest for your app:
```
cf configure-autoscaling APP-NAME MANIFEST-FILENAME
```
Where:
- APP-NAME is the name of the app that you want Autoscaler to scale.
- MANIFEST-FILENAME is the filename of the Autoscaler manifest.
Apply the autoscaling rule you configured in the previous step to the app you want to scale by running:
```
cf configure-autoscaling APP-NAME MANIFEST-FILENAME
```
Where:
- APP-NAME is the name of the app.
- MANIFEST-FILENAME is the filename of the manifest file you created in the previous step. For example, autoscaler.yaml.

Configure an autoscaling rule using CLI commands

To configure an autoscaling rule that defines a custom scaling metric using CLI commands:

In a terminal window, target the space in which the app you want to scale is deployed by running:
```
cf target -o ORG-NAME -s SPACE-NAME
```
Where:
- ORG-NAME is the name of the org containing the space in which the app you want to scale is deployed.
- SPACE-NAME is the name of the space in which the app you want to scale is deployed.
If the space in which the app you want to scale is deployed does not already have a service instance of Autoscaler deployed in it, create an Autoscaler service instance by running:
```
cf create-service app-autoscaler PLAN-NAME SERVICE-INSTANCE-NAME
```
Where:
- PLAN-NAME is the name of the service plan you want to use for the Autoscaler service instance.
- SERVICE-INSTANCE-NAME is the name you want to give the Autoscaler service instance. For example, autoscaler.
If there is already an Autoscaler service instance in the space in which the app you want to scale is deployed, skip this step.
Bind the Autoscaler service instance you created in the previous step to the app you want to scale by running:
```
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
```
Where:
- APP-NAME is the name of the app you want to scale.
- SERVICE-INSTANCE-NAME is the name of the Autoscaler service instance in the previous step.
Configure upper and lower scaling limits for the app by running:
```
cf update-autoscaling-limits APP-NAME LOWER-SCALING-LIMIT UPPER-SCALING-LIMIT
```
Where:
- APP-NAME is the name of the app.
- LOWER-SCALING-LIMIT is the minimum number of instances you want Autoscaler to create for the app.
- UPPER-SCALING-LIMIT is the maximum number of instances you want Autoscaler to create for the app.
To set Autoscaler to begin making scaling decisions for the app by running:
```
cf enable-autoscaling APP-NAME
```
Where APP-NAME is the name of the app.
Create a custom autoscaling rule by running:
```
cf create-autoscaling-rule APP-NAME custom MINIMUM-METRIC-THRESHOLD MAXIMUM-METRIC-THRESHOLD --metric METRIC-NAME
```
Where:
- APP-NAME is the name of the app for which you want to create an autoscaling rule.
- MINIMUM-METRIC-THRESHOLD is the minimum custom scaling metric threshold. If the average value of the custom scaling metric falls below this number, Autoscaler scales the number of app instances down.
- MAXIMUM-METRIC-THRESHOLD is the maximum custom scaling metric threshold. If the average custom scaling metric rises above this number, Autoscaler scales the number of app instances up.
- METRIC-NAME is the name of the custom scaling metric. This name must match the name of the metric that the app exposes.
The following example command configures a custom autoscaling rule for the example-app app that uses example_metric as its custom scaling metric, with a minimum custom scaling metric threshold of 20 and a maximum custom scaling metric threshold of 50:
```
cf create-autoscaling-rule example-app custom 20 50 --metric example_metric
```

Configure a custom scaling metric for an app through Apps Manager

To configure Autoscaler to use a custom scaling metric for an app using Apps Manager:

Log in to Apps Manager. For more information, see Logging in to Apps Manager.
Select the org that contains the space in which the app you want to scale is deployed.
Select the space in which the app you want to scale is deployed.
Under Processes and Instances, click Autoscaling Activated. The Manage Autoscaling window appears.
Next to Scaling Rules, click Add Rule. The Add Rule window appears.
From the Rule Type options, select Custom. Then click Next.
1. For Scale down if less than, enter the minimum custom scaling metric threshold. If the average value of the custom scaling metric falls below this number, Autoscaler scales the number of app instances down.
2. For Scale up if more than, enter the maximum custom scaling metric threshold. If the average value of the custom scaling metric rises above this number, Autoscaler scales the number of app instances up.
3. For Metric, enter the name of the custom scaling metric. This name must match the name of the metric that the app exposes.
Click Save.

Reviewing autoscaling events for changes in custom scaling metrics

When Autoscaler scales the number of app instances up after the custom scaling metric for an app increases above the maximum queue depth threshold, Autoscaler records an autoscaling event.

You can monitor the autoscaling events that Autoscaler records for changes in the custom scaling metric for an app in the following ways:

Through the cf CLI. For more information, see Review autoscaling events for changes in custom scaling metrics through the cf CLI.
Through Apps Manager. For more information, see Review autoscaling events for changes in custom scaling metrics through Apps Manager.

Review autoscaling events for changes in custom scaling metrics through the cf CLI

To review the autoscaling events that Autoscaler records for changes in the custom scaling metric for an app through the cf CLI:

In a terminal window, run:
```
cf autoscaling-events APP-NAME
```
Where APP-NAME is the name of the app for which you want to review autoscaling events.

If Autoscaler has scaled the number of app instances up due to increases in the custom scaling metric for the app, the above command returns output that contains autoscaling events similar to the following example:
```
Time                   Description
2022-05-25T23:13:27Z   Scaled up from 10 to 11 instances. Current example_metric of 60.83 is above upper threshold of 50.00.
```

Review autoscaling events for changes in custom scaling metrics through Apps Manager

To review the autoscaling events that Autoscaler records for changes in the custom scaling metric for an app through Apps Manager:

Log in to Apps Manager. For more information, see Logging in to Apps Manager.
Select the org that contains the space in which the app you want to scale is deployed.
Select the space in which the app you want to scale is deployed.
Under Processes and Instances, click Autoscaling Activated.
Under Event History, click View More. A list of autoscaling events appears. If Autoscaler has scaled the number of app instances up due to increases in the custom scaling metric for the app, the list of autoscaling events includes events similar to the following example:
```
Scaled up from 10 to 11 instances. Current example_metric of 60.83 is above upper threshold of 50.00.
```

Special considerations for using custom scaling metrics

This section describes use cases that might complicate or prevent you from configuring a custom scaling metric for an app.

Metric visibility

Metric endpoints include potentially sensitive information about the state of an app. Before you configure a custom scaling metric, ensure that unauthorized end users cannot access these endpoints.

To prevent unauthorized end users from accessing an app, you can configure the metrics endpoint to process traffic through a separate port. When registering the endpoint using the Metric Registrar CLI, you can use the --internal-port flag to specify which port the endpoint uses.

Counter metrics

Autoscaler cannot use counter metrics as custom scaling metrics. If you register a metrics endpoint that includes counter metrics, the counter metrics are sent to Loggregator, but Autoscaler does not retrieve them from Log Cache.

Metric labels

Autoscaler does not differentiate between metrics based on labels. If the metrics endpoint features the same metric with different labels, such as HTTP Request Latency metrics with labels that describe the endpoint from which they came, Autoscaler does not recognize the labels.

High metric load

Configuring an app to emit a large number of custom scaling metrics might cause your TAS for VMs deployment to have difficulty processing those metrics. To create a large number of custom scaling metrics, consult the operator of your TAS for VMs deployment.

Log cache ejection

The Metric Registrar scrapes the metrics endpoint on an app and emits the custom scaling metrics it receives. By default, the interval between scrapes is 35 seconds. You can configure this scrape interval in the Metric Registrar pane of the TAS for VMs tile. To configure the scrape interval for the Metric Registrar, see Edit Default Scraping Interval in Configuring TAS for VMs.

Within Log Cache, each app has its own bucket, which contains both app metrics and logs. By default, Log Cache can hold a maximum of 100,000 envelopes per app. Because the platform generates several envelopes per request, and recent app logs are held in the same bucket, a busy app might not have sufficient Log Cache Custom App Metric history for Autoscaler to use in scaling decisions.

For more information, see Log Cache in Operating App Autoscaler.