The Blas from Pas: Billing/Metering on Pivotal Cloud Foundry using the Usage Service API's

Pivotal Cloud Foundry (PCF) provides a REST API to provide billing/metering data for application and service usage. Although this usage can we viewed in the applications manager dashboard UI in this post below we will show how to use the REST based API using PCF 1.7.

Below we will show how to use the cf CLI to retrieve information about your app and service instances via the Cloud Controller and Usage service APIs.

Obtain Usage Information for an Organization

To obtain individual org usage information, use the following procedure. You must log in as an admin or as an Org Manager or Org Auditor for the org you want to view.

1. Target the end point of the cloud controller as follows

papicella@papicella:~/apps/ENV$ cf api https://api.system.yyyy.net --skip-ssl-validation
Setting api endpoint to https://api.system.yyyy.net...
OK

API endpoint: https://api.system.yyyy.net (API version: 2.54.0)
User: papicella@pivotal.io
Org: system
Space: pas

2. Login as shown below

papicella@papicella:~/apps/ENV$ cf login -u papicella@pivotal.io -o system -s pas
API endpoint: https://api.system.yyyy.net

Password>
Authenticating...
OK

Targeted org system

Targeted space pas

API endpoint: https://api.system.yyyy.net (API version: 2.54.0)
User: papicella@pivotal.io
Org: system
Space: pas

Now if your using CURL for example you can inject the GUID of your organization as part of the command as well as the "oauth-token". Here is an example on how that is done.

Endpoint format:

https://app-usage.YOUR-DOMAIN/organizations/{ORG_GUID}/app_usages?start=YYYY-MM-DD&end=YYYY-MM-DD

3. Issue REST call as shown below.

papicella@papicella:~$ curl "https://app-usage.system.yyyy.net/organizations/`cf org system --guid`/app_usages?start=2016-06-01&end=2016-06-30" -k -v -H "authorization: `cf oauth-token`" | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 222.237.99.147...
* Connected to app-usage.system.yyyy.net (222.237.99.147) port 443 (#0)
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate: *.system.yyyy.net
0 0 0 0 0 0 0 0 --:--:-- 0:00:01 --:--:-- 0> GET /organizations/b75c9069-83b4-4130-a98e-a5eb4c5454c5/app_usages?start=2016-06-01&end=2016-06-30 HTTP/1.1
> Host: app-usage.system.yyyy.net
> User-Agent: curl/7.43.0
> Accept: */*
> authorization: bearer AwZi1lYjYGVyIMPPO-06eUG1FM12DY964Eh5AA_6Ga8P7IoB4Qr2OVx_vHh6o35IFKw .....
>
< HTTP/1.1 200 OK
< Cache-Control: max-age=0, private, must-revalidate
< Content-Type: application/json; charset=utf-8
< Etag: "16161b20edbc072ab63f8f8acf6ff251"
< Server: thin
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< X-Request-Id: 3ef758d1-3f8d-4942-b0bc-44666c2797e5
< X-Runtime: 0.167997
< X-Vcap-Request-Id: 01794681-8e29-4a07-463c-3660d0c3b349
< X-Xss-Protection: 1; mode=block
< Date: Thu, 14 Jul 2016 00:41:55 GMT
< Content-Length: 1766
<
{ [1766 bytes data]
100 1766 100 1766 0 0 755 0 0:00:02 0:00:02 --:--:-- 755
* Connection #0 to host app-usage.system.yyyy.net left intact
{
"app_usages": [
{
"app_guid": "17eee541-051a-44b5-83ae-bbbba5519af7",
"app_name": "springboot-telstrasms",
"duration_in_seconds": 0,
"instance_count": 1,
"memory_in_mb_per_instance": 512,
"space_guid": "7a0cfa11-d71d-4dd6-a706-b5eff622fb66",
"space_name": "pas"
},
{
"app_guid": "1f102a77-ce84-4cf4-93d1-e015abdf65b5",
"app_name": "company",
"duration_in_seconds": 1622,
"instance_count": 1,
"memory_in_mb_per_instance": 512,
"space_guid": "85d952b4-1acb-45fa-bd8b-d440de745a6f",
"space_name": "development"
},
{
"app_guid": "2d05970c-3f94-4329-a92a-5b81f95a9365",
"app_name": "jay-test",
"duration_in_seconds": 448,
"instance_count": 1,
"memory_in_mb_per_instance": 512,
"space_guid": "85d952b4-1acb-45fa-bd8b-d440de745a6f",
"space_name": "development"
},
{
"app_guid": "2d05970c-3f94-4329-a92a-5b81f95a9365",
"app_name": "jay-test",
"duration_in_seconds": 692,
"instance_count": 1,
"memory_in_mb_per_instance": 1024,
"space_guid": "85d952b4-1acb-45fa-bd8b-d440de745a6f",
"space_name": "development"
},
{
"app_guid": "4b771593-5032-41f9-84ff-1ecfec9a7f4d",
"app_name": "company",
"duration_in_seconds": 18430,
"instance_count": 1,
"memory_in_mb_per_instance": 512,
"space_guid": "85d952b4-1acb-45fa-bd8b-d440de745a6f",
"space_name": "development"
},
{
"app_guid": "a5435de0-1dd3-49ba-a551-94e921a5999b",
"app_name": "springboot-telstrasms",
"duration_in_seconds": 677,
"instance_count": 1,
"memory_in_mb_per_instance": 512,
"space_guid": "7a0cfa11-d71d-4dd6-a706-b5eff622fb66",
"space_name": "pas"
},
{
"app_guid": "f9c7f387-d008-4541-b093-92fb23e01aee",
"app_name": "company",
"duration_in_seconds": 0,
"instance_count": 1,
"memory_in_mb_per_instance": 512,
"space_guid": "85d952b4-1acb-45fa-bd8b-d440de745a6f",
"space_name": "development"
}
],
"organization_guid": "b75c9069-83b4-4130-a98e-a5eb4c5454c5",
"period_end": "2016-06-30T23:59:59Z",
"period_start": "2016-06-01T00:00:00Z"

}

4. To obtain usage information about services you would issue a REST call as follows

Use cf curl to retrieve service instance information. The service_instances? endpoint retrieves details about both bound and unbound service instances:

Endpoint format:

https://app-usage.YOUR-DOMAIN/organizations{ORG_GUID}/service_usages?start=YYYY-MM-DD&end=YYYY-MM-DD

papicella@papicella:~$ curl "https://app-usage.system.yyyy.net/organizations/b75c9069-83b4-4130-a98e-a5eb4c5454c5/service_usages?start=2016-06-01&end=2016-06-30" -k -v -H "authorization: `cf oauth-token`" | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 222.237.99.147...
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Connected to app-usage.system.yyyy.net (222.237.99.147) port 443 (#0)
0 0 0 0 0 0 0 0 --:--:-- 0:00:02 --:--:-- 0* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate: *.system.yyyy.net
> GET /organizations/b75c9069-83b4-4130-a98e-a5eb4c5454c5/service_usages?start=2016-06-01&end=2016-06-30 HTTP/1.1
> Host: app-usage.system.yyyy.net
> User-Agent: curl/7.43.0
> Accept: */*
> authorization: bearer eyJhbGciOiJSUzI1NiJ9.....
>
0 0 0 0 0 0 0 0 --:--:-- 0:00:03 --:--:-- 0< HTTP/1.1 200 OK
< Cache-Control: max-age=0, private, must-revalidate
< Content-Type: application/json; charset=utf-8
< Etag: "909824b589cbed6c3d19c2f36bec985e"
< Server: thin
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< X-Request-Id: 2255821e-116c-4651-b483-1939f0f1f866
< X-Runtime: 0.137921
< X-Vcap-Request-Id: 3991c5f9-11c2-4c0e-5f2b-d1f94be87ef4
< X-Xss-Protection: 1; mode=block
< Date: Thu, 14 Jul 2016 00:53:47 GMT
< Transfer-Encoding: chunked
<
{ [3632 bytes data]
100 3978 0 3978 0 0 1283 0 --:--:-- 0:00:03 --:--:-- 1283
* Connection #0 to host app-usage.system.yyyy.net left intact
{
"organization_guid": "b75c9069-83b4-4130-a98e-a5eb4c5454c5",
"period_end": "2016-06-30T23:59:59Z",
"period_start": "2016-06-01T00:00:00Z",
"service_usages": [
{
"deleted": false,
"duration_in_seconds": 2592000.0,
"service_guid": "5c03686a-6748-4b76-bb6f-cbd116d5d87e",
"service_instance_creation": "2016-05-10T01:58:01.000Z",
"service_instance_deletion": null,
"service_instance_guid": "bd09176c-483c-4011-b329-fba717abfc27",
"service_instance_name": "spring-cloud-broker-db",
"service_instance_type": "managed_service_instance",
"service_name": "p-mysql",
"service_plan_guid": "b3525660-1a74-452f-9564-65a2556895bd",
"service_plan_name": "100mb-dev",
"space_guid": "8a9788b2-8405-4312-99fc-6854a2972616",
"space_name": "p-spring-cloud-services"
},
{
"deleted": false,
"duration_in_seconds": 2592000.0,
"service_guid": "b0a9fb4e-325b-402b-8a99-d53d7f7df80c",
"service_instance_creation": "2016-05-10T01:58:03.000Z",
"service_instance_deletion": null,
"service_instance_guid": "ad82aa5b-fd7c-4e7d-b56f-523f7b285c5d",
"service_instance_name": "spring-cloud-broker-rmq",
"service_instance_type": "managed_service_instance",
"service_name": "p-rabbitmq",
"service_plan_guid": "0cfd01c4-aea0-4ab0-9817-a312d91eee8d",
"service_plan_name": "standard",
"space_guid": "8a9788b2-8405-4312-99fc-6854a2972616",
"space_name": "p-spring-cloud-services"
},
{
"deleted": false,
"duration_in_seconds": 2592000.0,
"service_guid": "5c03686a-6748-4b76-bb6f-cbd116d5d87e",
"service_instance_creation": "2016-05-11T06:53:19.000Z",
"service_instance_deletion": null,
"service_instance_guid": "9c306f43-b17d-4a59-964d-828db5047e04",
"service_instance_name": "mydb",
"service_instance_type": "managed_service_instance",
"service_name": "p-mysql",
"service_plan_guid": "b3525660-1a74-452f-9564-65a2556895bd",
"service_plan_name": "100mb-dev",
"space_guid": "7938ae22-6a1c-49bc-9cf4-08b9b6281e83",
"space_name": "autoscaling"
},
{
"deleted": false,
"duration_in_seconds": 2592000.0,
"service_guid": "23a0f05f-fed6-4873-b0f5-77457b721626",
"service_instance_creation": "2016-05-11T06:57:01.000Z",
"service_instance_deletion": null,
"service_instance_guid": "75a4f233-25a4-4fb2-b205-354716c6c081",
"service_instance_name": "auto",
"service_instance_type": "managed_service_instance",
"service_name": "app-autoscaler",
"service_plan_guid": "5e0285ad-92b5-4cda-95e7-36db4a16fa05",
"service_plan_name": "bronze",
"space_guid": "7938ae22-6a1c-49bc-9cf4-08b9b6281e83",
"space_name": "autoscaling"
},
{
"deleted": false,
"duration_in_seconds": 2592000.0,
"service_guid": "5c03686a-6748-4b76-bb6f-cbd116d5d87e",
"service_instance_creation": "2016-05-20T08:39:09.000Z",
"service_instance_deletion": null,
"service_instance_guid": "9b69e1d0-2f93-48d2-a0b0-fc009ebbfe1d",
"service_instance_name": "account-db",
"service_instance_type": "managed_service_instance",
"service_name": "p-mysql",
"service_plan_guid": "b3525660-1a74-452f-9564-65a2556895bd",
"service_plan_name": "100mb-dev",
"space_guid": "7938ae22-6a1c-49bc-9cf4-08b9b6281e83",
"space_name": "autoscaling"
},
{
"deleted": false,
"duration_in_seconds": 1947572.0,
"service_guid": "f603ea87-9b24-4114-9bdc-c4e8154b549c",
"service_instance_creation": "2016-06-08T11:00:28.000Z",
"service_instance_deletion": null,
"service_instance_guid": "3d75b148-ee78-4f91-aa49-a1b2aa511fd1",
"service_instance_name": "service-registry",
"service_instance_type": "managed_service_instance",
"service_name": "p-service-registry",
"service_plan_guid": "ee6a7f19-f4d2-44f8-b8a2-08246c5d9a5d",
"service_plan_name": "standard",
"space_guid": "85d952b4-1acb-45fa-bd8b-d440de745a6f",
"space_name": "development"
},
{
"deleted": false,
"duration_in_seconds": 67559.0,
"service_guid": "23da6824-3ee0-4d87-b031-6223e69327ed",
"service_instance_creation": "2016-06-30T05:14:01.000Z",
"service_instance_deletion": null,
"service_instance_guid": "fd8d2f19-6a8c-43ad-81c1-205e6a29d2b8",
"service_instance_name": "api-connectors-service",
"service_instance_type": "managed_service_instance",
"service_name": "apigee-edge",
"service_plan_guid": "36ae6841-9eb3-42b7-b40b-aa44ee72a14c",
"service_plan_name": "org",
"space_guid": "7a0cfa11-d71d-4dd6-a706-b5eff622fb66",
"space_name": "pas"
}
]
}

The following screen shots show how this is done using a REST client from a browser.