LATEST VERSION: 1.9 - CHANGELOG
Pivotal Cloud Foundry v1.7

Monitoring Instance Usage

Page last updated:

This topic describes how to retrieve app and service instance usage information. You can access the data using Apps Manager, the Usage service API, or the Cloud Foundry API from the cf CLI.

Monitoring Instance Usage from Apps Manager

There are two ways to monitor app and service instance usage from Apps Manager. The Accounting Report provides a summarized report, and the Usage Report provides a more detailed view of the data.

View the Accounting Report

The Accounting Report displays instance usage information for all orgs in your Pivotal Cloud Foundry (PCF) deployment except the system org. The Accounting Report provides a high-level overview of your usage by displaying your monthly count of app instances.

To access the Accounting Report, you must be logged into the Apps Manager as an admin.

  1. Select Accounting Report from the left navigation of Apps Manager.

  2. View the average and maximum app instances in use per month under App Instance Statistics.

The maximum is the largest number of app instances in use at any one time. The Accounting Report calculates these values from the start, stop, and scale app usage events in Cloud Controller.

Accounting report

View the Usage Report

The Usage Report provides a more granular view of your usage by detailing app memory usage and service instance usage information for all spaces in a particular org, excluding the system org.

To access the Usage Report, you must be logged into the Apps Manager as an admin or have an Org Manager or Org Auditor role. For more information on managing roles, see the Managing User Accounts and Permissions Using the Apps Manager topic.

  1. From the dropdown on the left, select the org for which you want to view a usage report.

  2. Next the org QUOTA, click Usage Report.

    Usage report link

    The top of the Usage Report displays total app memory usage and service instance usage by all spaces in your org.

    Usage report

    Spaces Details breaks down your app memory usage and service instance usage by spaces.

    Service details

  3. Click the name of an app to view its Configuration History.

    App usage service

Monitoring App and Service Usage from the cf CLI

This section describes how to use the cf CLI to retrieve usage information about your app and service instances via the Cloud Controller and Usage service APIs.

Obtain System Usage Information

Before you can retrieve any app or service information, you must target the Cloud Controller and log in as admin, as follows:

  1. Target the endpoint of your Cloud Controller.

    $ cf api api.YOUR-DOMAIN
  2. Log in with your credentials.

    $ cf login -u admin
    API endpoint:  api.YOUR-DOMAIN
    Email: user@example.com
    Password:
    Authenticating...
    OK
    ...
    Targeted org  YOUR-ORG
    Targeted space  development
    API endpoint:    https://api.YOUR-DOMAIN (API version:  2.52.0)
    User:            user@example.com
    Org:             YOUR-ORG
    Space:           development
    
  3. Run curl for the /system_usage_report on the Usage service.

    $ curl "https://app-usage.YOUR-DOMAIN/system_usage_report" -k -v -H "authorization:`cf oauth-token`"
    

Obtain Usage Information about an Org

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. Run cf login -u USERNAME.

  2. Run curl for the /app_usages or /service_usages endpoints on the Usage service.

    $ curl "https://app-usage.YOUR-DOMAIN/organizations/`cf org YOUR-ORG --guid`/app_usages?start=YYYY-MM-DD&end=YYYY-MM-DD" -k -v -H "authorization: `cf oauth-token`"
    {
       "organization_guid": "8d83362f-587a-4148-806b-4407428887b5",
       "period_start": "2016-06-01T00:00:00Z",
       "period_end": "2016-06-13T23:59:59Z",
       "app_usages": [
          {
            app_guid: "00ecd7ce-1dd0-4b3f-63b9-744c9de42afc"
            app_name: "your-app"
            duration_in_seconds: 76730
            instance_count: 6
            memory_in_mb_per_instance: 64
            space_guid: "44435fd6-fbac-5049-bbfc-92d1603a5e98"
            space_name: "outer-space"
          }
        ]
     }
    

    Or run the following:

    $ curl "https://app-usage.YOUR-DOMAIN/organizations/`cf org YOUR-ORG --guid`/service_usages?start=YYYY-MM-DD&end=YYYY-MM-DD" -k -v -H "authorization: `cf oauth-token`"
    {
       "organization_guid": "8d83362f-587a-4148-806b-4407428887b5",
       "period_start": "2016-06-01T00:00:00Z",
       "period_end": "2016-06-13T23:59:59Z",
       "service_usages": [
          {
            deleted: false
            duration_in_seconds: 1377982.52
            service_guid: "02802293-b769-44cc-807f-eee331ba9b2b"
            service_instance_creation: "2016-01-20T18:48:16.000Z"
            service_instance_deletion: null
            service_instance_guid: "b25b4481-19aa-4504-82c9-f303e7e9ed6e"
            service_instance_name: "something-usage-db"
            service_instance_type: "managed_service_instance"
            service_name: "my-mysql-service"
            service_plan_guid: "70915a70-7311-4f3e-ab0d-4a7dfd3ef2d9"
            service_plan_name: "20gb"
            space_guid: "e6445eb3-fdac-4049-bafc-94d1703d5e78"
            space_name: "outer-space"
          }
      ]
    }
    

Retrieve Apps Information

  1. The apps endpoint retrieves information about all of your apps.

    $ cf curl /v2/apps
    {
     "total_results": 2,
     "total_pages": 1,
     "prev_url": null,
     "next_url": null,
     "resources": [
        {
            "metadata": {
               "guid": "acf2ce33-ee92-54TY-9adb-55a596a8dcba",
               "url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba",
               "created_at": "2016-02-06T17:40:31Z",
               "updated_at": "2016-02-06T18:09:17Z"
            },
            "entity": {
               "name": "YOUR-APP",
     [...]
               "space_url": "/v2/spaces/a0205ae0-a691-4667-92bc-0d0dd712b6d3",
               "stack_url": "/v2/stacks/86205f38-84fc-4bc2-b2b8-af7f55669f04",
               "routes_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/routes",
               "events_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/events",
               "service_bindings_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/service_bindings",
                "route_mappings_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/route_mappings"
               }
            },
        {
            "metadata": {
               "guid": "79bb58cc-3737-43be-ac70-39a2843b5178",
               "url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178",
               "created_at": "2016-02-15T23:25:47Z",
               "updated_at": "2016-03-12T21:54:59Z"
            },
            "entity": {
               "name": "ANOTHER-APP",
    [...]
               "space_url": "/v2/spaces/a0205ae0-a691-4667-92bc-0d0dd712b6d3",
               "stack_url": "/v2/stacks/86205f38-84fc-4bc2-b2b8-af7f55669f04",
               "routes_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/routes",
               "events_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/events",
               "service_bindings_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/service_bindings",
               "route_mappings_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/route_mappings"
             }
          }
       ]
    }
    

    The output of this command provides the URL endpoints for each app, within the metadata: url section. You can use these app-specific endpoints to retrieve more information about that app. In the example above, the endpoints for the two apps are /v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba and /v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178.

  2. The summary endpoint under each app-specific URL retrieves the instances and any bound services for that app.

    $ cf curl /v2/apps/acf2ce75-ee92-4bb6-9adb-55a596a8dcba/summary
    {
       "guid": "acf2ce75-ee92-4bb6-9adb-55a596a8dcba",
       "name": "YOUR-APP",
       "routes": [
       {
          "guid": "7421b6af-75cb-4334-a862-bc5e1ababfe6",
          "host": "YOUR-APP",
          "path": "",
          "domain": {
             "guid": "fb6bd89f-2ed9-49d4-9ad1-97951a573135",
             "name": "YOUR-DOMAIN.io"
         }
      }
    ],
      "running_instances": 5,
      "services": [
         {
            "guid": "b9cdr456-3c61-4f8a-a307-9b4ty836fb2e",
            "name": "YOUR-APP-db",
            "bound_app_count": 1,
            "last_operation": {
               "type": "create",
               "state": "succeeded",
               "description": "",
               "updated_at": null,
               "created_at": "2016-02-05T04:58:46Z"
         },
            "dashboard_url": "https://cloudfoundry.appdirect.com/api/custom/cloudfoundry/v2/sso/start?serviceUuid=b5cASDF-3c61-4f8a-a307-9bf85j45fb2e",
            "service_plan": {
               "guid": "fbcec3af-3e8d-4ee7-adfe-3f12a137ed66",
               "name": "turtle",
               "service": {
                  "guid": "34dbc753-34ed-4cf1-9a87-a255dfca5339b",
                  "label": "elephantsql",
                  "provider": null,
                  "version": null
    [...]
    
  3. To view the app_usages report that covers app usage within an org during a period of time, see Obtain Usage Information about an Org.

Retrieve Services Information

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

$ cf curl /v2/service_instances?
{
   "total_results": 4,
   "total_pages": 1,
   "prev_url": null,
   "next_url": null,
   "resources": [
      {
       "metadata": {
           "guid": "b9cdr456-3c61-4f8a-a307-9b4ty836fb2e",
           "url": "/v2/service_instances/b9cdr456-3c61-4f8a-a307-9b4ty836fb2e",
           "created_at": "2016-02-05T04:58:46Z",
           "updated_at": null
       },
       "entity": {
           "name": "YOUR-BOUND-DB-INSTANCE",
           "credentials": {},
           "service_plan_guid": "fbcec3af-3e8d-4ee7-adfe-3f12a137ed66",
           "space_guid": "a0205ae0-a691-4667-92bc-0d0dd712b6d3",
           "gateway_data": null,
           "dashboard_url": "https://cloudfoundry.appdirect.com/api/custom/cloudfoundry/v2/sso/start?serviceUuid=b9cdr456-3c61-4f8a-a307-9b4ty836fb2e",
           "type": "managed_service_instance",
           "last_operation": {
               "type": "create",
               "state": "succeeded",
               "description": "",
               "updated_at": null,
               "created_at": "2016-02-05T04:58:46Z"
            },
            "tags": [],
            "space_url": "/v2/spaces/a0205ae0-a691-4667-92bc-0d0dd712b6d3",
            "service_plan_url": "/v2/service_plans/fbcec3af-3e8d-4ee7-adfe-3f12a137ed66",
            "service_bindings_url": "/v2/service_instances/b9cdr456-3c61-4f8a-a307-9b4ty836fb2e/service_bindings",
            "service_keys_url": "/v2/service_instances/b9cdr456-3c61-4f8a-a307-9b4ty836fb2e/service_keys",
            "routes_url": "/v2/service_instances/b9cdr456-3c61-4f8a-a307-9b4ty836fb2e/routes"
         }
      },
      {
      "metadata": {
           "guid": "78be3399-bdc7-4fbf-a1a4-6858a50d0ff3",
           "url": "/v2/service_instances/78be3399-bdc7-4fbf-a1a4-6858a50d0ff3",
           "created_at": "2016-02-15T23:45:30Z",
           "updated_at": null
       },
       "entity": {
           "name": "YOUR-UNBOUND-DB-INSTANCE",
           "credentials": {},
           "service_plan_guid": "fbcec3af-3e8d-4ee7-adfe-3f12a137ed66",
           "space_guid": "a0205ae0-a691-4667-92bc-0d0dd712b6d3",
           "gateway_data": null,
           "dashboard_url": "https://cloudfoundry.appdirect.com/api/custom/cloudfoundry/v2/sso/start?serviceUuid=78be3399-bdc7-4fbf-a1a4-6858a50d0ff3",
           "type": "managed_service_instance",
           "last_operation": {
              "type": "create",
              "state": "succeeded",
              "description": "",
              "updated_at": null,
              "created_at": "2016-02-15T23:45:30Z"
              },
           "tags": [],
           "space_url": "/v2/spaces/a0205ae0-a691-4667-92bc-0d0dd712b6d3",
           "service_plan_url": "/v2/service_plans/fbcec3af-3e8d-4ee7-adfe-3f12a137ed66",
           "service_bindings_url": "/v2/service_instances/78be3399-bdc7-4fbf-a1a4-6858a50d0ff3/service_bindings",
           "service_keys_url": "/v2/service_instances/78be3399-bdc7-4fbf-a1a4-6858a50d0ff3/service_keys",
           "routes_url": "/v2/service_instances/78be3399-bdc7-4fbf-a1a4-6858a50d0ff3/routes"
           }
        },
      ]
   }
Was this helpful?
What can we do to improve?
View the source for this page in GitHub