AppDynamics Application Performance Monitoring for Pivotal Platform Workflow

This topic describes how to push and bind an application to an AppDynamics tile.

Before You Start

  1. Create a Pivotal Network account if you do not have one.
  2. Install the Cloud Foundry Command Line Interface (cf CLI). See Installing the cf CLI.

Create an AppDynamics Service Instance

  1. Open a cf CLI or command-prompt window.

  2. Identify your Pivotal API endpoint and version. Enter the following command:

    $ cf api
    The following output appears:
    api endpoint: https://api.my.pivotal.io
    api version: 2.103.0
    

  3. Log in to the Pivotal endpoint:

    cf login

  4. Enter your email address and Pivotal password when prompted.

  5. Verify the appdynamics service is present in the cf environment.

    $ cf marketplace -s appdynamics
    service plan                   description                    free or paid
    pcf-appd                       pcf-appd                       free
    pcf-appd-troubleshooting-lab   pcf-appd-troubleshooting-lab   free
    

  6. Create a service instance of the appdynamics service and a plan of your choice.

    $ cf create-service appdynamics pcf-appd appd
    

  7. Follow the workflow for the corresponding language of the application mentioned below

AppDynamics Instrumentation Workflows

.NET Framework Applications (Multi-Buildpack)

DotNet Framework Applications are pushed using standard hwc_buildpack. These applications are instrumented using appdbuildpack in tandem with hwc_buildpack using the multi-buildpack approach.

  1. Edit the following sections of your application’s manifest.yml

  2. Include appdbuildpack in the buildpacks section.

  3. Set the application environment variable APPD_AGENT to dotnet

  4. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    ---
    applications:
    - name: cf-net
      memory: 2G
      buildpacks:
        - appdbuildpack
        - hwc_buildpack
      stack: windows2016
      env:
        APPD_AGENT: dotnet
      services:
        - appd
    
  5. Push the application using the cf push command.

    $ cf push 

Advanced Configuration

appdbuildpack provides APPD_AGENT_HTTP_URL and APPD_CONF_HTTP_URL environment variables to customize agent binary downloads and extend agents advanced configuration respectively. See AppDynamics Multi-Buildpack documentation for details.

.NET Core Linux Applications (Multi-Buildpack)

  1. Edit the following sections of your application’s manifest.yml

  2. Include appdbuildpack in the buildpacks section.

  3. Set the application environment variable APPD_AGENT to dotnet-linux

  4. Set the application environment variable APPD_AGENT_HTTP_URL to a custom http url where the AppDynamics .NET Agent for Linux is hosted. This is necessary because the agent is not currently available in NuGet. See AppDynamics Buildpack for more info.

  5. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    ----
    applications:
    - name: cf-net-linux
      memory: 2G
      buildpacks:
        - appdbuildpack
        - dotnet_core_buildpack
      env:
        APPD_AGENT: dotnet-linux
        APPD_AGENT_HTTP_URL: http://CUSTOM_REPO/AppDynamics-DotNetCore-linux-x64-VERSION.zip
      services:
        - appd
    
  6. Push the application using the cf push command.

    $ cf push 

Advanced Configuration

appdbuildpack provides APPD_AGENT_HTTP_URL and APPD_CONF_HTTP_URL environment variables to customize agent binary downloads and extend agents advanced configuration respectively. Refer AppDynamics Multi-Buildpack documentation for details.

.NET Core Windows Applications (Multi-Buildpack)

DotNet Core Applications for Windows are pushed using standard binary_buildpack. Such applications are instrumented using appdbuildpack in tandem with binary_buildpack using the multi-buildpack approach.

  1. Edit the following sections of your application’s manifest.yml

  2. Include appdbuildpack in the buildpacks section

  3. Set the application environment variable APPD_AGENT to dotnet-windows

  4. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    ---
    applications:
    - name: cf-net-windows
      random-route: true
      memory: 512M
      path: app.zip
      command: dotnetHelloWorld.exe
      stack: windows2016
      buildpacks:
        - appd_buildpack
        - binary_buildpack
      env:
        APPD_AGENT: dotnet-windows
        DOTNET_CLI_TELEMETRY_OPTOUT: 1
        DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
      services:
        - appd
    
  5. Push the application using the cf push command.

    $ cf push 

Advanced Configuration

appdbuildpack provides APPD_AGENT_HTTP_URL and APPD_CONF_HTTP_URL environment variables to customize agent binary downloads and extend agents advanced configuration respectively. Refer AppDynamics Multi-Buildpack documentation for details.

Python Applications (Multi-Buildpack)

Python Applications are pushed using the standard python_buildpack. Such applications are instrumented using appdbuildpack in tandem with python_buildpack using the multi-buildpack approach.

  1. Edit the following sections of your application’s manifest.yml

  2. Include appdbuildpack in the buildpacks section of application manifest.

  3. Set the application environment variable APPD_AGENT to python

  4. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    ---
    applications:
    - name: cf-python
      memory: 500M
      buildpacks:
        - appdbuildpack
        - python_buildpack
      env:
        APPD_AGENT: python
      services:
        - appd
    
  5. Push the application

    $ cf push 

Advanced Configuration

appdbuildpack provides APPD_AGENT_HTTP_URL and APPD_CONF_HTTP_URL environment variables to customize agent binary downloads and extend agents advanced configuration respectively. Refer AppDynamics Multi-Buildpack documentation for details.

GoLang Applications (Multi-Buildpack)

Go Applications are pushed using the standard go_buildpack. AppDynamics provides an SDK to instrument such applications. The configuration needed to start the go agent via the SDK APIs is exported as environment variables when the applications are pushed with appdbuildpack and go_buildpack using the multi-buildpack approach.

  1. Edit the following sections of your application’s manifest.yml

  2. Include appdbuildpack in the buildpacks section of application manifest.

  3. Set the application environment variable APPD_AGENT to golang

  4. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    ---
    applications:
    - name: cf-go
      memory: 500M
      buildpacks:
        - appdbuildpack
        - go_buildpack
      env:
        APPD_AGENT: golang
      services:
        - appd
    
  5. Copy paste the snippet below to initialize the go agent.

      package main
      import (
          ...
          appd "appdynamics"
      )
    
        ...
          cfg := appd.Config{}
          cfg.AppName = os.Getenv("APPD_APPLICATION_NAME")
          cfg.TierName = os.Getenv("APPD_TIER_NAME")
          cfg.NodeName = os.Getenv("APPD_NODE_NAME")
    
          /* AppDynamics Controller Confiuration */
          cfg.Controller.Host = os.Getenv("APPD_CONTROLLER_HOST")
          port, err := strconv.ParseInt(os.Getenv("APPD_CONTROLLER_HOST"), 10, 16)
          if err != nil {
            return err
          }
          cfg.Controller.Port = uint16(port)
          cfg.Controller.Account = os.Getenv("APPD_ACCOUNT_NAME")
          cfg.Controller.AccessKey = os.Getenv("APPD_ACCOUNT_ACCESS_KEY")
          cfg.InitTimeoutMs = 1000
    
          err = appd.InitSDK(&cfg)
          if err != nil {
              fmt.Println(err)
          }
          ...
    
  6. The necessary configuration to start AppDynamics Golang agent is exposed via environment variables APPD_APPLICATION_NAME, APPD_TIER_NAME, APPD_NODE_NAME, APPD_CONTROLLER_HOST, APPD_CONTROLLER_HOST, APPD_ACCOUNT_NAME, APPD_ACCOUNT_ACCESS_KEY

  7. Push the application

    $ cf push 

Advanced Configuration

The appdbuildpack provides APPD_AGENT_HTTP_URL and APPD_CONF_HTTP_URL environment variables to customize agent binary downloads, and extend agents advanced configuration respectively. See AppDynamics Multi-Buildpack documentation for details.

Java Applications

Java applications are instrumented by AppDynamics using the standard java_buildpack.

  1. Edit the following sections of your application’s manifest.yml

  2. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    ---
    applications:
    - name: cf-java-app
      memory: 1G
      random-route: true
      path: build/libs/cf-java-sample-1.0.jar
      buildpacks:
        - java_buildpack
      services:
        - appd
    
  3. Push the application

    $ cf push 

Advanced Configuration

Because AppDynamics instrumentation of pcf java applications does not use appdbuildpack, the configuration is managed by java_buildpack directly.

Refer to the standard java_buildpack documentation

Node.js Applications

Node.js applications are instrumented by AppDynamics using standard nodejs_buildpack directly.

Note: Appdynamics Extension Buildpack v4.6.x on, support of node agent with nodejs_buildpack would be dropped. It will be replaced with Appdynamics own buildpack and can be used with multi-buildpack approach.

  1. Bind the application to the appdynamics service instance, by including appd in the services section of the application manifest.

    applications:
    - name: cf-node
      memory: 500M
      services:
        - appd
    
  2. Optionally provide the environment variables for configuring the agent. Below is the list of supported environment variables

    ENV VARIABLE DESCRIPTION
    APPDYNAMICS_AGENT_APPLICATION_NAME Application Name to be reported to AppDynamic’s Controller
    APPDYNAMICS_AGENT_TIER_NAME Tier Name for the Application to be reported to AppDynamic’s Controller
    APPDYNAMICS_AGENT_NODE_NAME Node Name for the Application to be reported to AppDynamic’s Controller
    APPD_AGENT_DEBUG Set to true to enable debug level logging for the agent. The default is false.
    APPD_AGENT_LIBAGENT Controls the proxyless version of the agent. The default is true. Set to false if you want to use the proxy version of the Node.js agent.
    APPD_LOG_CONFIG The location, level, and other settings related to agent logging. See Node.js Agent Logging
  3. Push the application

    $ cf push 

Extending Default Configuration

Extending Application, Tier, Node names

To override the default AppDynamics application/tier/node names, set the following environment variables.

$ cf set-env APP ENV-NAME ENV-VALUE 

AGENT APPLICATION ENV VARIABLE TIER ENV VARIABLE NODE ENV VARIABLE
Golang APPD_APP_NAME APPD_TIER_NAME APPD_NODE_NAME
Java APPDYNAMICS_AGENT_APPLICATION_NAME APPDYNAMICS_AGENT_TIER_NAME APPDYNAMICS_AGENT_NODE_NAME
.NET APPDYNAMICS_AGENT_APPLICATION_NAME APPDYNAMICS_AGENT_TIER_NAME APPDYNAMICS_AGENT_NODE_NAME
NodeJS APPDYNAMICS_AGENT_APPLICATION_NAME APPDYNAMICS_AGENT_TIER_NAME APPDYNAMICS_AGENT_NODE_NAME
PHP APPD_APP_NAME APPD_TIER_NAME APPD_NODE_NAME
Python APPD_APP_NAME APPD_TIER_NAME APPD_NODE_NAME

Extending Proxy configuration

If you are using a proxy server, the consumer application should specify the http_proxy or https_proxy as an environment variable for the application running on Pivotal Platform to communicate with the proxy server. Do the following:

  1. Set the environment variable for the application and the Controller.

    • For an HTTP proxy:
      cf set-env  http_proxy http://user@password:myproxy....:8080/
    • For an HTTPS proxy:
      cf set-env  https_proxy https://user@password:myproxy....:8080/
  2. Restage the application:

    cf restage 

  3. Log in to the Controller web UI, navigate to the Metric Browser, and verify that the application is being detected and monitored.

Using AppDynamics User Provided Service

In addition to the procedure above using the service broker tile, operators can also use user provided service with the name appdynamics to instrument applications on AppDynamics.

  1. Use the cf cups command below with the JSON fields specified.

  2. The name of the user provided service must be appdynamics and its JSON credentials must have account-access-key, account-name, host-name, port and ssl-enabled fields.

    $ cf cups appdynamics -p '{"account-access-key":"acce$$key", "account-name":"customer1", "host-name":"demo.appdynamics.com", "port":"8090", "ssl-enabled":false}' 

Deploying the Machine Agent on Pivotal Platform

This topic helps you deploy the Machine Agent on the Pivotal Platform(Pivotal Platform) platform.

Before You Start

  • Acquire admin or space developer access on Cloud Foundry to deploy, run, and manage applications. For more information on access rights see the Cloud Foundry Documentation.
  • Download the Machine Agent.

Set Up the Machine Agent

  1. Set up the AppDynamics GitHub repository.

    git clone https://github.com/Appdynamics/cloudfoundry-apps
    cd cloudfoundry-apps/cf-machine-agent
    
  2. Ensure that the Machine Agent is downloaded from the AppDynamics Download Center into the current directory.

    MachineAgent-4.5.11.2163.zip
    cd MachineAgent-4.5.11.2163
    (master)$ ls
    bin         local-scripts       monitorsLibs
    conf        machineagent.jar    readme.txt
    extensions  machineagent.jar.asc    readme.txt.asc
    lib         monitors        scripts
    
  3. Copy the Machine Agent extensions, if any, to the cloudfoundry-apps/cf-machine-agent extensions directory. Note that extensions must be of .zip format, containing extension_folder/{.jar, *.monitor.xml}

    (master)$ cp ~/Downloads/Pivotal PlatformExtension-1.0.0.zip extensions/
    
  4. Edit the JAVA_OPTS section in the manifest.yml to add the Controller information. For example, the manifest.yml is similar to the following after filling in the details:

    ---
    applications:
    - name: appdynamics-machine-agent
      memory: 1G
      health-check-type: process
      no-route: true
      buildpack: java_buildpack_offline
      path: MachineAgent.zip
      env:
        JAVA_OPTS: '-Dappdynamics.agent.accountAccessKey=accessKey -Dappdynamics.agent.accountName=customer1 -Dappdynamics.controller.hostName=saas-controller.e2e.appd.com -Dappdynamics.controller.port=8090 -Dappdynamics.agent.applicationName=app -Dappdynamics.agent.tierName=tier -Dappdynamics.agent.nodeName=node -Dappdynamics.controller.ssl.enabled=false'
    

    Check the additions as follows:

    (master)$ git diff
    
    -    JAVA_OPTS: '-Dappdynamics.agent.accountAccessKey={} -Dappdynamics.agent.accountName={} -Dappdynamics.controller.hostName={} -Dappdynamics.controller.port={} -Dappdynamics.agent.applicationName={} -Dappdynamics.agent.tierName={} -Dappdynamics.agent.nodeName={} -Dappdynamics.controller.ssl.enabled={true|false}'
    +    JAVA_OPTS: '-Dappdynamics.agent.accountAccessKey=accessKey -Dappdynamics.agent.accountName=customer1 -Dappdynamics.controller.hostName=saas-controller.e2e.appd.com -Dappdynamics.controller.port=8090 -Dappdynamics.agent.applicationName=app -Dappdynamics.agent.tierName=tier -Dappdynamics.agent.nodeName=node -Dappdynamics.controller.ssl.enabled=false'
    
  5. Run package.sh

    This script packages the extension zip files into the Machine Agent monitor directory, cleans the Machine Agent, and adjusts the permissions of files per requirements from Pivotal Platform.

    (master)$ ./package.sh
    Creating workdir tmp
    Moving MachineAgent to tmp dir
    Unzipping MachineAgent
    Unzipping Extensions from ../extensions to ./monitors Directory
    Cleaning MachineAgent - removing *.asc files
    Adjusting permissions as per requirement from CloudFoundry
    Packaging MachineAgent
    
  6. Deploy the Machine Agent application using cf push

    (master)$ cf push
    Pushing from manifest to org appdynamics-org / space appdynamics-space as admin...
    Using manifest file /Users/appD_user/appdy/cloudfoundry-apps/cf-machine-agent/manifest.yml
    Getting app info...
    Updating app with these attributes...
    name:                appdynamics-machine-agent
    path:                /Users/appD_user/appdy/cloudfoundry-apps/cf-machine-agent/MachineAgent.zip
    buildpack:           java_buildpack_offline
    command:             JAVA_OPTS="-agentpath:$PWD/.java-buildpack/open_jdk_jre/bin/jvmkill-1.16.0_RELEASE=printHeapHistogram=1 -Djava.io.tmpdir=$TMPDIR -Djava.ext.dirs=$PWD/.java-buildpack/container_security_provider:$PWD/.java-buildpack/open_jdk_jre/lib/ext -Djava.security.properties=$PWD/.java-buildpack/java_security/java.security $JAVA_OPTS" && CALCULATED_MEMORY=$($PWD/.java-buildpack/open_jdk_jre/bin/java-buildpack-memory-calculator-3.13.0_RELEASE -totMemory=$MEMORY_LIMIT -loadedClasses=30244 -poolType=metaspace -stackThreads=250 -vmOptions="$JAVA_OPTS") && echo JVM Memory Configuration: $CALCULATED_MEMORY && JAVA_OPTS="$JAVA_OPTS $CALCULATED_MEMORY" && MALLOC_ARENA_MAX=2 JAVA_OPTS=$JAVA_OPTS JAVA_HOME=$PWD/.java-buildpack/open_jdk_jre exec $PWD/bin/machine-agent
    disk quota:          1G
    health check type:   process
    instances:           1
    memory:              1G
    stack:               cflinuxfs2
    env:
      JAVA_OPTS
    
      Updating app appdynamics-machine-agent...
    

    In a few seconds, the Machine Agent starts in a container in the Pivotal Platform Elastic Runtime as an application named appdynamics-machine-agent.

  7. Check if the application is running.

    (master)$ cf apps
    Getting apps in org appdynamics-org / space appdynamics-space as admin...
    OK
    appdynamics-machine-agent   started           1/1         1G       1G