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

Monitoring App and Service Instance Usage

Page last updated:

This topic describes how to use the Cloud Foundry Command Line Interface (cf CLI) to retrieve usage information about your app and service instances through the Cloud Controller and Usage service APIs.

You can also access usage information by using Apps Manager. For more information, see the Monitoring Instance Usage with Apps Manager topic.

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