Using PCF Application Watchdog

This topic describes how to use and interpret data from Pivotal Cloud Foundry (PCF) Application Watchdog.

Before performing the procedures in this topic, you must have installed PCF Application Watchdog.

Install the Plugin and Target the PCF Application Watchdog Server

The following sections describe how to install the PCF Application Watchdog plugin and target the Application Watchdog server.

Step 1: Install the PCF Application Watchdog Plugin

To install the PCF Application Watchdog plugin, perform the following steps:

  1. Download the plugin for your platform from Pivotal Network.

  2. Extract the plugin archive, which contains the appdog-cli file.

  3. Run the following command to install the plugin:

    $ cf install-plugin PATH/TO/appdog-cli

Step 2: Target the Application Watchdog Server

After installing the PCF Application Watchdog plugin, run the following command to target the Application Watchdog server:

$ cf appdog target https://appdog-server.YOUR-SYSTEM-DOMAIN

Step 3: Log In to the Application Watchdog Server

After targeting the Application Watchdog server, run the following command to log-in to the Application Watchdog server:

$ cf appdog login

You will be prompted to visit an authorization page, where you will be presented with a token that must be provided to the PCF Application Watchdog plugin. You may be asked to log in with your Cloud Foundry user credentials if you are not already logged in to Apps Manager.

Step 4: Verify the Application Watchdog Server

To verify that the Application Watchdog server is working, run the following command:

$ cf appdog status

Use PCF Application Watchdog

Refer to the following sections for instructions on how to use PCF Application Watchdog:

Run the Help Command

To output a summary of all Application Watchdog commands, run cf appdog help. To output usage information for a particular command, run cf appdog help COMMAND. See the following example.

$ cf appdog help using
NAME:
   cf appdog using - Provides a list of all apps using a given dependency

USAGE:
   cf appdog using [command options] <dependency> [[<,>,!=]<version>] 
     [ --org <myorg> --space <myspace>] 

   Note: To use '<', '>', or '!=' operators, use single quotes. Ex: cf ad using jre '>1.8.0'

OPTIONS:
   --org value, -o value    Organization
   --space value, -s value  Space
   --buildpacks             Only apps with buildpack-added dependencies

View Status of App Scans

Application Watchdog scans an app several minutes after deployment and rescans the app after each deployment. Application Watchdog also updates latest dependency information daily.

To see a summary of all apps scanned by Application Watchdog, run the cf appdog status command. The following example shows four successfully scanned apps.

$ cf appdog status
Connecting to appdog server https://appdog-server.local.pcfdev.io...
app name        org          space          last scan update           scan status
apps-manager    system       system         2016-08-09T18:13:12.000Z   failed (language not supported)
notifications   pcfdev-org   pcfdev-space   2016-08-09T18:13:13.000Z   failed (language not supported)
appdog-server   pcfdev-org   pcfdev-space   2016-08-09T18:14:04.000Z   scanned successfully
appdog-worker   pcfdev-org   pcfdev-space   2016-08-09T18:14:07.000Z   scanned successfully
test-app1       test-org     test-space     2016-08-09T18:21:28.000Z   scanned successfully
test-app2       test-org     test-space     2016-08-09T18:23:57.000Z   scanned successfully

View Scan Reports

To see a report on a specific app, run cf appdog report --org ORG --space SPACE APP-NAME, replacing APP-NAME with the name of an app and ORG and SPACE with the name of the org and space where the app runs. See the following example.

$ cf appdog report --org test-org --space test-space test-app1
Connecting to appdog server https://appdog-server.local.pcfdev.io...
The latest scan status for this app was: scanned

Detected Buildpack Name / Version: java-buildpack=v3.10-offline-https://github.com/cloudfoundry/java-buildpack.git#193d6b7 java-main open-jdk-like-jre=1.8.0_111 open-jdk-like-memory-calculator=2.0.2_RELEASE spring-auto-reconfiguration=1.10.0_RELEASE

Application Dependencies

[...]
library name                                              library version   latest version available   license
org.springframework:spring-aop                            4.2.5.RELEASE     4.3.3.RELEASE              The Apache Software License, Version 2.0
org.springframework:spring-beans                          4.2.5.RELEASE     4.3.3.RELEASE              The Apache Software License, Version 2.0
org.springframework:spring-context                        4.2.5.RELEASE     4.3.3.RELEASE              The Apache Software License, Version 2.0
org.springframework:spring-core                           4.2.5.RELEASE     4.3.3.RELEASE              The Apache Software License, Version 2.0
[...]

Buildpack Injected Dependencies
library name                  library version   latest version available   license
openjdk-jre                   1.8.0_111                                    GNU GPL+linking exception
spring_auto_reconfiguration   1.10.0_RELEASE

This example shows that test-app1 is a Java app running OpenJDK 1.8.0_111, and deployed with the Cloud Foundry Java Buildpack version 3.1.

The output also shows that the app has some outdated dependencies, such as spring-aop.

Find Apps by Characteristic

The following sections describe how to find an app based on specific characteristics.

Find Apps with Outdated Dependencies

To identify all outdated dependencies in an org or space or app, use the cf appdog updates command. For example, the following command lists all outdated dependencies in test-org and test-space:

$ cf appdog updates --org test-org --space test-space
Connecting to appdog server https://appdog-server.local.pcfdev.io...


Updates for:

   Dependency Name                                           Org        Space        App_Name    Current         Latest
   ch.qos.logback:logback-classic                            test-org   test-space   test-app2   1.1.5           1.1.7
   ch.qos.logback:logback-core                               test-org   test-space   test-app2   1.1.5           1.1.7
   org.springframework.boot:spring-boot-starter-web          test-org   test-space   test-app2   1.3.3.RELEASE   1.4.0.RELEASE
   org.yaml:snakeyaml                                        test-org   test-space   test-app2   1.16            1.17
   rack                                                      test-org   test-space   test-app1   1.5.2           2.0.1
   rack-protection                                           test-org   test-space   test-app1   1.5.2           1.5.3
   sinatra                                                   test-org   test-space   test-app1   1.4.4           1.4.7
   tilt                                                      test-org   test-space   test-app1   1.4.1           2.0.5


* denotes the dependency was added by a buildpack

To find outdated dependencies for a single app, run the following command:

$ cf appdog updates --org MY-ORG --space MY-SPACE APP-NAME

Replace APP-NAME with the name of the app and MY-ORG and MY-SPACE with the name of the org and space where the app runs.

Running cf appdog updates without arguments returns a list of outdated dependences for all apps in your deployment.

Find Apps Using a Specific Library

To find apps using a specific dependency, run the cf appdog using command. For example, cf appdog using tomcat returns the following:

$ cf appdog using tomcat
Connecting to appdog server https://appdog-server.local.pcfdev.io...
tomcat is used in: 1 org(s) and 1 space(s):

App         Org        Space
test-app2   test-org   test-space
* denotes the dependency was added by a buildpack

Optionally, specify a dependency version, or range of versions, with a second argument as shown in the following commands:

  • cf appdog using spring 4.2.7
  • cf ad using jdk '>1.8.0'

Note: You must include quotes for < or > so that the shell does not interpret redirections.

To limit your search to a specific org or space us the --org and --space options.

The Java Buildpack may provide some dependencies, indicated by an asterisk. For example, the buildpack usually injects Java Runtime:

$ cf appdog using openjdk-jre
openjdk-jre is used in: 1 org(s) and 1 space(s):

App            Org        Space        URL
test-app2(*)   test-org   test-space   test-app2.local.pcfdev.io
* denotes the dependency was added by a buildpack

Find Apps with Dependencies Using a Specific License

To list apps with dependencies using a specific license, run cf appdog license LICENSE. For example, to list apps with MIT licensed dependencies, run the following command:

$ cf appdog license MIT
MIT was found in:

App Name        Org          Space          License
appdog-server   pcfdev-org   pcfdev-space   MIT
appdog-worker   pcfdev-org   pcfdev-space   MIT
test-app1       test-org     test-space     MIT
test-app2       test-org     test-space     MIT

You can also limit your search to a given org or space with --org and --space.

List App Dependencies

The following sections describe how to list app dependencies.

List Dependencies of an App

To list dependencies of a given app, you can use the command cf appdog dependencies APP-NAME. For example, to list dependencies of the appdog-server, run the following command:

$ cf appdog dependencies --org pcfdev-org --space pcfdev-space appdog-server
Application Dependencies       Current Version
actionmailer                   4.2.6
actionpack                     4.2.6
actionview                     4.2.6
activejob                      4.2.6
activemodel                    4.2.6
activerecord                   4.2.6
activesupport                  4.2.6
[...]
xml-simple                     1.1.5

To specify the org and space of the app, use the --org and --space options. If you do not specify an org and space, the command returns information for the currently targeted org and space.

List Information about a Dependency for a Specific App

To list information about a dependency for a specific app, run cf appdog dependency-info APP-NAME DEPENDENCY-NAME. For example, to list information about org.springframework:spring-beans for spring-music, run the following command:

$ cf appdog dependency-info --org pcfdev-org --space pcfdev-space spring-music org.springframework:spring-beans
Name                               Version         Latest Version   License
org.springframework:spring-beans   4.2.6.RELEASE   4.3.2.RELEASE    The Apache Software License, Version 2.0

To specify the org and space of the app, use the --org and --space options. If you do not specify an org and space, the command returns information for the currently targeted org and space.

Output Commands in CSV Format

To view the output of a command in CSV format for purposes such as importing your data to spreadsheets, use the --format csv flag. See the following example.

$ cf appdog report appdog-server --format csv
library name,library version,latest version available,license
actionmailer,4.2.7.1,5.0.0.1,MIT
actionpack,4.2.7.1,5.0.0.1,MIT
actionview,4.2.7.1,5.0.0.1,MIT
activejob,4.2.7.1,5.0.0.1,MIT
activemodel,4.2.7.1,5.0.0.1,MIT
activerecord,4.2.7.1,5.0.0.1,MIT
[...]
xml-simple,1.1.5,1.1.5,ruby
Create a pull request or raise an issue on the source for this page in GitHub