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 2 commits
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
178 changes: 168 additions & 10 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 All @@ -143,13 +143,13 @@ Parameters
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| guid | The GUID of the application | | true | |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| metric-type | The metric type | String, memoryused,memoryutil,responsetime, throughput | true | metric-type=memoryused |
| metric_type | The metric type | String, memoryused,memoryutil,responsetime, throughput or custom metric's name | true | metric_type=memoryused |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| start-time | The start time | int, the number of nanoseconds elapsed since January 1, 1970 UTC. | false, default 0 | start-time=1494989539138350432 |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| end-time | The end time | int, the number of nanoseconds elapsed since January 1, 1970 UTC. | false, default "now" | end-time=1494989549117047288 |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| order-direction | The order type. The scaling history will be order by timestamp asc or desc. | string,”asc” or "desc" | false. default desc | order-direction=asc |
| order-direction | The order type. The metric history will be ordered by timestamp asc or desc. | string,”asc” or "desc" | false. default desc | order-direction=asc |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| page | The page number to query | int | false, default 1 | page=1 |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
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 All @@ -253,13 +253,13 @@ Parameters
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| guid | The GUID of the application | | true | |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| metric-type | The metric type | String, memoryused,memoryutil,responsetime, throughput | true | metric-type=memoryused |
| metric_type | The metric type | String, memoryused,memoryutil,responsetime, throughput or custom metric's name | true | metric_type=memoryused |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| start-time | The start time | int, the number of nanoseconds elapsed since January 1, 1970 UTC. | false, default 0 | start-time=1494989539138350432 |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| end-time | The end time | int, the number of nanoseconds elapsed since January 1, 1970 UTC. | false, default "now" | end-time=1494989549117047288 |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| order-direction | The order type. The scaling history will be order by timestamp asc or desc. | string,”asc” or "desc" | false. default desc | order-direction=asc |
| order-direction | The order type. The metric history will be ordered by timestamp asc or desc. | string,”asc” or "desc" | false. default desc | order-direction=asc |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
| page | The page number to query | int | false, default 1 | page=1 |
+--------------------+-------------------------------------------------------------------------------+---------------------------------------------------------------------+-----------------------+----------------------------------+
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,164 @@ 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` is offered as a Cloud Foundry extension, the credential need to be generated explictly.

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

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

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.
zyjiaobj marked this conversation as resolved.
Show resolved Hide resolved

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

Route
'''''

PUT /v1/apps/:guid/credential

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.


"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
Loading