Skip to content
This repository has been archived by the owner on Dec 1, 2021. It is now read-only.

modify doc for custom metric #536

Merged
merged 4 commits into from
Nov 8, 2019
Merged

modify doc for custom metric #536

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
86c459c
modify doc for custom metric
cdlliuy Nov 1, 2019
e35d888
update per comments
cdlliuy Nov 8, 2019
6f05b19
fix rst format issue
cdlliuy Nov 8, 2019
bdd2716
update per comments
cdlliuy Nov 8, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 158 additions & 6 deletions docs/Public_API.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Scaling History API
Route
'''''

GET /v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/scaling\_histories
GET /v1/apps/:guid/scaling\_histories

Parameters
''''''''''
Expand Down Expand Up @@ -133,7 +133,7 @@ Application Metric API
Route
'''''

GET /v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/metric_histories/memoryused
GET /v1/apps/:guid/metric_histories/memoryused

Parameters
''''''''''
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the Parameters definition:

  1. metric-type:
    • metric_type with '_' instead of '-' is used in GET /v1/apps/:guid/metric_histories/:metric_type
    • need we add custom metric in the description?
  2. order-direction: The scaling history will be order by timestamp asc or desc. -> The metric history will be order by timestamp asc or desc.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@zyjiaobj
1 "metric_type" is in path so it is different from query parameters, such as "start-time" or "order-direction".
2 "be order" or "be ordered"?

Copy link
Contributor

@zyjiaobj zyjiaobj Nov 6, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean "scaling history" should be changed to "metric history", as this is metric_histories api.
Also, "be ordered" should be better.

Expand Down Expand Up @@ -229,7 +229,7 @@ Body

]

*List aggregated metrics of an application**
**List aggregated metrics of an application**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AutoScaler collects the instances' metrics of an application, and aggregate the raw data into an accumulated value for evaluation. This API is used to return the aggregated metric result of an application.
Expand All @@ -243,7 +243,7 @@ AutoScaler collects the instances' metrics of an application, and aggregate the
Route
'''''

GET /v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/aggregated_metric_histories/memoryused
GET /v1/apps/:guid/aggregated_metric_histories/memoryused

Parameters
Copy link
Contributor

@zyjiaobj zyjiaobj Nov 6, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the Parameters definition:

  1. metric-type:
    • metric_type with '_' instead of '-' is used in GET /v1/apps/:guid/aggregated_metric_histories/:metric_type
    • need we add custom metric in the description?
  2. order-direction: The scaling history will be order by timestamp asc or desc. -> The metric history will be order by timestamp asc or desc.

''''''''''
Expand Down Expand Up @@ -335,7 +335,7 @@ Body
Policy API
----------

Set Policy
Create Policy
~~~~~~~~~~

PUT /v1/apps/:guid/policy
Expand Down Expand Up @@ -545,7 +545,7 @@ cURL
"https://[the-api-server-url]:[port]/v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/policy" \\
| -d @policy.json \\
| -X PUT \\
| -H "Content-Type: application/json"
| -H "Content-Type: application/json" \\
| -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidWFhLWlkLTI5MSIsImVtYWlsIjoiZW1haWwtMTk0QHNvbWVkb21haW4uY29tIiwic2NvcGUiOlsiY2xvdWRfY29udHJvbGxlci5hZG1pbiJdLCJhdWQiOlsiY2xvdWRfY29udHJvbGxlciJdLCJleHAiOjE0NDU1NTc5NTd9.p3cHAMwwVASl1RWxrQuOMLYRZRe4rTbaIH1RRux3Q5Y"

Response
Expand Down Expand Up @@ -989,6 +989,158 @@ Body

}


Custom metric API
-----------------

To scale with custom metric, your application need to emit its own metric to `App Autoscaler`'s metric server.

Given the metric submission is proceeded inside an application, an `App Autoscaler` specific credential is required to authorize the access.

If `App Autoscaler` is offered as a service, the credential and autoscaler metric server's URL are injected into VCAP_SERVICES by service binding directly.

If `App Autoscaler` Autoscaling is offered as a Cloud Foundry extension, the credential need to be generated explictly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove "Autoscaling"


**Create credential**
~~~~~~~~~~~~~~~~~~~~~

**PUT /v1/apps/:guid/credential**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Request**
^^^^^^^^^^^

Route
'''''

PUT /v1/apps/:guid/credential

Body
''''

Otptional. A credential with random username/password will be generated by this API by default. Also it is supported to define credential with a specific pair of username and password with below JSON payload.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo?


{
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part of json content is not well-formatted in preview.


"username": "username",
"password": "password"
}

Headers
'''''''
Authorization: bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidWFhLWlkLTQwOCIsImVtYWlsIjoiZW1haWwtMzAzQHNvbWVkb21haW4uY29tIiwic2NvcGUiOlsiY2xvdWRfY29udHJvbGxlci5hZG1pbiJdLCJhdWQiOlsiY2xvdWRfY29udHJvbGxlciJdLCJleHAiOjE0NDU1NTc5NzF9.RMJZvSzCSxpj4jjZBmzbO7eoSfTAcIWVSHqFu5\_Iu\_o

cURL
''''
| curl "https://[the-api-server-url]:[port]/v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/credential" \\
| -X PUT \\
| -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidWFhLWlkLTQwOCIsImVtYWlsIjoiZW1haWwtMzAzQHNvbWVkb21haW4uY29tIiwic2NvcGUiOlsiY2xvdWRfY29udHJvbGxlci5hZG1pbiJdLCJhdWQiOlsiY2xvdWRfY29udHJvbGxlciJdLCJleHAiOjE0NDU1NTc5NzF9.RMJZvSzCSxpj4jjZBmzbO7eoSfTAcIWVSHqFu5\_Iu\_o"


Response
^^^^^^^^

Status
''''''

200 OK

Body
''''

{
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part of json content is not well-formatted in preview.

"app_id": "<APP_ID>",
"username": "MY_USERNAME",
"password": "MY_PASSWORD",
"url": "<AUTOSCALER METRIC SERVER URL>"
}


**Delete credential**
~~~~~~~~~~~~~~~~~~~~~

**DELETE /v1/apps/:guid/credential**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Request**
^^^^^^^^^^^

Route
'''''

DELETE /v1/apps/:guid/credential

Headers
'''''''
Authorization: bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidWFhLWlkLTQwOCIsImVtYWlsIjoiZW1haWwtMzAzQHNvbWVkb21haW4uY29tIiwic2NvcGUiOlsiY2xvdWRfY29udHJvbGxlci5hZG1pbiJdLCJhdWQiOlsiY2xvdWRfY29udHJvbGxlciJdLCJleHAiOjE0NDU1NTc5NzF9.RMJZvSzCSxpj4jjZBmzbO7eoSfTAcIWVSHqFu5\_Iu\_o

cURL
''''
| curl "https://[the-api-server-url]:[port]/v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/credential" \\
| -X DELETE \\
| -H "Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoidWFhLWlkLTQwOCIsImVtYWlsIjoiZW1haWwtMzAzQHNvbWVkb21haW4uY29tIiwic2NvcGUiOlsiY2xvdWRfY29udHJvbGxlci5hZG1pbiJdLCJhdWQiOlsiY2xvdWRfY29udHJvbGxlciJdLCJleHAiOjE0NDU1NTc5NzF9.RMJZvSzCSxpj4jjZBmzbO7eoSfTAcIWVSHqFu5\_Iu\_o"


Response
^^^^^^^^

Status
''''''

200 OK


**Submit custom metric to Autoscaler metric server**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**PUT /v1/apps/:guid/metrics**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Request**
^^^^^^^^^^^

Route
'''''

PUT /v1/apps/:guid/metrics

Body
''''

A JSON payload is required to emit your own metrics with the metric value and the correspondng instance index.

{
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part of json content is not well-formatted in preview.

"instance_index": <INSTANCE INDEX>,
"metrics": [
{
"name": "<CUSTOM METRIC NAME>",
"value": <CUSTOM METRIC VALUE>
}
]
}

Headers
'''''''
Basic authorization of autoscaler credential is required when submitting your own metrics to Autoscaler metric server.

cURL
''''
| curl "https://[the-autoscaler-metric-server-url]:[port]/v1/apps/8d0cee08-23ad-4813-a779-ad8118ea0b91/metrics" \\
| -X PUT \\
| -d @metric.json \\
| -H "Content-Type: application/json" \\
| -H "Authorization: basic xxxx"

Response
^^^^^^^^

Status
''''''

200 OK

Error Response
-------------------

Expand Down
101 changes: 94 additions & 7 deletions docs/Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The [Cloud Foundry App Auto-Scaler][git] automatically adjust the instance numbe
The Cloud Foundry [Admin or Space Developers role][userrole] is needed to manage the autoscaling policy, query metric values and scaling events.

---
## Autoscaling policy
## Concepts of Autoscaling policy

Autoscaling policy is represented in JSON and consists of the following parts. Refer to the [policy specification][policy] for the detailed definition.

Expand Down Expand Up @@ -49,6 +49,11 @@ The following are the built-in metrics that you can use to scale your applicatio
* **throughput**

"throughput" is the total number of the processed requests in a given time period. The unit of "throughput" is "rps" (requests per second).

* **custom metric**

Custom emtric is supported since [app-autoscaler v3.0.0 release][app-autoscaler-v3.0.0]. You can define your own metric name and emit your own metric to `App Autoscaler` to trigger further dynamic scaling.



#### Threshold and Adjustment
Expand Down Expand Up @@ -98,12 +103,13 @@ For example, in the following schedule rule, `App AutoScaler` will set your appl
```

----
## Create Autoscaling policy
## Create Autoscaling Policy JSON File

The following gives some policy examples for you to start with. Refer to [Policy speficication][policy] for the detailed JSON format of the autoscaling policy.

* [Autoscaling policy with dynamic scaling rules][policy-dynamic]
* [Autoscaling policy with dynamic scaling rules and schedules][policy-all]
* [Autoscaling policy example for dynamic scaling rules][policy-dynamic]
* [Autoscaling policy example for custom metrics ][policy-dynamic-custom]
* [Autoscaling policy example for both dynamic scaling rules and schedules][policy-all]

----

Expand All @@ -112,7 +118,7 @@ The following gives some policy examples for you to start with. Refer to [Policy
`App-AutoScaler` can be offered as a Cloud Foundry service or an extension of your Cloud Foundry platform. Consult your Cloud Foundry provider for how it is offered.

### As a Cloud Foundry extension
When `App AutoScaler` is offered as Cloud Foudnry platform extension, you don't need to connect your application to autoscaler, go directly to next section on how to configure your policy.
When `App AutoScaler` is offered as Cloud Foudnry platform extension, you don't need to connect your application to autoscaler, go directly to next section to attach autoscaling policy to your application with CLI.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Cloud Foudnry", typo.


### As a Cloud Foundry service
When `App AutoScaler` is offered as a Cloud Foundry service via [open service broker api][osb] , you need to provision and bind `App AutoScaler` service through [Cloud Foundry CLI][cfcli] first.
Expand Down Expand Up @@ -150,7 +156,7 @@ This section gives how to use the command line interface to manage autoscaling p

### Attach policy

Create or update auto-scaling policy for your application with command
Create or update auto-scaling policy for your application with command.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

auto-scaling, autoscaling and Auto-scaling, do we need to unify the name?

```
cf aasp <app_name> <policy_file_name>
```
Expand Down Expand Up @@ -190,11 +196,91 @@ To query your application's scaling events, use command below

Refer to [AutoScaler CLI user guide][cli] for advanced options to specify the time range, the number of events to return and display order.

### Create autoscaling credential to submit custom metric

Create custom metric credential for an application. The credential will be displayed in JSON format.
```
cf create-autoscaling-credential <app_name>
```
Refer to [AutoScaler CLI user guide][cli] for more details.

### Delete autoscaling credential
Delete custom metric credential when unncessary.
```
cf delete-autoscaling-credential <app_name>
```

----
## Bring your own metric for Auto-scaling

With custom metric support, you can scale your application with your own metrics with below steps.

* Claim custom metric in your policy

First, you need to define a dynamic scaling rule with a customized metric name, refer to [Autoscaling policy example for custom metrics][policy-dynamic-custom].

* Create credential for your application

To scale with custom metric, your application need to emit its own metric to `App Autoscaler`'s metric server.
Given the metric submission is proceeded inside an application, an `App Autoscaler` specific credential is required to authorize the access.

If `App Autoscaler` is offered as a service, the credential and autoscaler metric server's URL are injected into VCAP_SERVICES by service binding directly.

If `App Autoscaler` Autoscaling is offered as a Cloud Foundry extension, the credential need to be generated explictly with command `cf create-autoscaling-credential` as below example:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove "Autoscaling"


```
>>>cf create-autoscaling-credential <app_name> --output <credential_json_file_path>
...
>>> cat <credential_json_file_path>
{
"app_id": "c99f4f6d-2d67-4eb6-897f-21be90e0dee5",
"username": "9bb48dd3-9246-4d7e-7827-b478e9bbedcd",
"password": "c1e47d80-e9a0-446a-782b-63fe9f974d4c",
"url": "https://autoscalermetrics.bosh-lite.com"
}
```

Then, you need to configure the credential to your application as an environment variable by `cf set-env` command
or through user-provided-service approach as below:

```
>>> cf create-user-provided-service <user-provided-service-name> -p <credential_json_file_path>
...
>>> cf bind-service <app_name> <user-provided-service-name>
...
TIP: Use 'cf restage <app-name>' to ensure your env variable changes take effect
```
With the user-provided-service aproach, you can consume the credential from VCAP_SERVICES environments.

* Emit your own metrics to autoscaler

You need to emit your own metric for scaling to the "URL" specified in credential JSON file with below API endpoint.

```
PUT /v1/apps/:guid/metrics
```

A JSON payload is required with above API to submit metric name, value and the correspondng instance index.
```
{
"instance_index": <INSTANCE INDEX>,
"metrics": [
{
"name": "<CUSTOM METRIC NAME>",
"value": <CUSTOM METRIC VALUE>
}
]
}
```

Please refer to [Emit metric API Spec][emit-metric-api] for more information.


[git]:https://github.com/cloudfoundry/app-autoscaler
[cli]: https://github.com/cloudfoundry/app-autoscaler-cli-plugin#install-plugin
[policy]: policy.md
[policy-dynamic]: dynamicpolicy.json
[policy-dynamic-custom]: customemetricpolicy.json
[policy-all]: fullpolicy.json
[api]: Public_API.rst
[osb]: https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md
Expand All @@ -204,4 +290,5 @@ Refer to [AutoScaler CLI user guide][cli] for advanced options to specify the t
[sunbind]:https://docs.cloudfoundry.org/devguide/services/managing-services.html#unbind
[sdeprovision]:https://docs.cloudfoundry.org/devguide/services/managing-services.html#delete
[userrole]:https://docs.cloudfoundry.org/concepts/roles.html#spaces

[app-autoscaler-v3.0.0]: https://bosh.io/releases/github.com/cloudfoundry-incubator/app-autoscaler-release?all=1#latest
[emit-metric-api]:https://github.com/cloudfoundry/app-autoscaler/blob/develop/docs/Public_API.rst#submit-custom-metric-to-autoscaler-metric-server
10 changes: 7 additions & 3 deletions docs/policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@

| Name | Type | Required|Description |
|:---------------------|--------------|---------|---------------------------------------------------------------------------------|
| metric_type | String | true |one of the following metric types:memoryused,memoryutil,responsetime, throughput, cpu|
| metric_type | String | true |one of system-default metric types `memoryused`,`memoryutil`,`responsetime`, `throughput`, `cpu` or user-defined custom metric type|
| threshold | int | true |the boundary when metric value exceeds is considered as a breach |
| operator | String | true |>, <, >=, <= |
| adjustment | String | true |the adjustment approach for instance count with each scaling. Support regex format `^[-+][1-9]+[0-9]*[%]?$`, i.e. +5 means adding 5 instances, -50% means shrinking to the half of current size. |
Expand Down Expand Up @@ -68,9 +68,13 @@
## Sample Policy

* [Autoscaling policy with dynamic scaling rules][policy-dynamic]
* [Autoscaling policy with dynamic scaling rules defined by custom metrics ][policy-dynamic-custom]
* [Autoscaling policy with dynamic scaling rules and schedules][policy-all]


[a]:https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html
[policy-dynamic]: /app-autoscaler/dynamicpolicy.json
[policy-all]: /app-autoscaler/fullpolicy.json
[policy-dynamic]: /docs/dynamicpolicy.json
[policy-dynamic-custom]: /docs/customemetricpolicy.json
[policy-all]: /docs/fullpolicy.json