How do I monitor Cloud Foundry cluster components and applications?

The following guidelines apply to the deployment of OneAgent to Cloud Foundry VMs, including Cloud Foundry components, Diego cells, and Windows Diego cells. The Dynatrace BOSH add-on is currently in a beta release phase.

Before you begin

What you'll need:

  • Dynatrace environment credentials
  • BOSH CLI
  • Cloud Foundry deployment with Garden-runC v1.0.0 or higher

Get your Dynatrace environment ID and PaaS token

The first step is to get your environment ID and the PaaS token for your Dynatrace environment.

  1. Login with your Dynatrace account.

  2. Select Deploy Dynatrace from the navigation menu.

  3. Click the Set up PaaS integration button.

  4. Your environment ID appears in the Environment ID text box. You'll need this ID to link your Dynatrace account with your PaaS environment. Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.

  5. To generate a PaaS token, click the Generate new token button. The PaaS token is essentially an API token that's used in combination with your environment ID to download Dynatrace OneAgent.

  6. Type in a meaningful name for your PaaS token. A meaningful token name might be the name of the PaaS platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing PaaS tokens, go to Settings -> Integration -> Platform as a Service.

  7. Click Generate to create the PaaS token. The newly created PaaS token will appear in the list below. Click Copy to copy the generated token to the clipboard. You can do this at any time by revisiting this page and clicking Show token next to the relevant PaaS token.

Upload and deploy the Dynatrace BOSH add-on

Ensure that your bosh CLI successfully connected to the BOSH director. For details, please refer to Cloud Foundry documentation or Pivotal documentation.

Get the link to the latest BOSH release on Github. You can also run the following command to get the URL of the latest release, provided that you have jq installed.

RELEASE=$(curl -s https://api.github.com/repos/dynatrace-innovationlab/bosh-oneagent-release/releases/latest | jq -r ".assets[] | select(.name) | .browser_download_url")

Upload the BOSH release of Dynatrace OneAgent to the BOSH Director:

bosh upload release $RELEASE

Update your runtime configuration to include the Dynatrace OneAgent for BOSH add-on

Create a Dynatrace OneAgent manifest runtime-config-dynatrace.yml. The Dynatrace OneAgent release that you uploaded in the previous step consists of two jobs. The dynatrace-oneagent job is applicable for Linux VMs. The dynatrace-oneagent-windows job is for Windows VMs. Since the runtime configuration needs to split jobs for Linux and Windows, you need to define two add-on sections in the manifest file. If you have questions, please review this sample runtime configuration.
Note: If you’ve installed other BOSH add-ons, you must merge the Dynatrace manifest into your existing add-on manifest.

releases:
- {name: dynatrace-oneagent, version: 0.3.3}
  #specify version of latest release

addons:
- name: dynatrace-oneagent-addon
  jobs:
  - name: dynatrace-oneagent
    release: dynatrace-oneagent
  include:
    stemcell:
    - os: ubuntu-trusty
  exclude:
    jobs:
    - {name: smoke-tests, release: cf}
    - {name: push-apps-manager, release: push-apps-manager-release}
    - {name: deploy-notifications, release: notifications}
    - {name: deploy-notifications-ui, release: notifications-ui}
    - {name: push-pivotal-account, release: pivotal-account}
    - {name: deploy-autoscaling, release: cf-autoscaling}
    - {name: register-broker, release: cf-autoscaling}
    - {name: nfsbrokerpush, release: nfs-volume}
    - {name: bootstrap, release: cf-mysql}
    - {name: rejoin-unsafe, release: cf-mysql}
    - {name: broker-registrar, release: cf-mysql}
    - {name: deregister-and-purge-instances, release: cf-mysql}
    - {name: smoke-tests, release: cf-mysql}
    - {name: install-hwc-buildpack, release: hwc-buildpack}
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      apiurl: https://{your-managed-cluster.com}/e/{environmentid}/api # optional: base URL for API endpoint for Dynatrace Managed
      starthelper: 1 # optional: enable garden injection by addon

#optional: extra addon configuration for Windows cells
- name: dynatrace-oneagent-windows-addon
  jobs:
  - name: dynatrace-oneagent-windows
    release: dynatrace-oneagent
  include:
    stemcell:
    - os: windows2012R2
  properties:
    dynatrace:
      environmentid: <environmentid>
      apitoken: <token>
      apiurl: https://{your-managed-cluster.com}/e/{environmentid}/api # optional: base URL for API endpoint for Dynatrace Managed

Update the BOSH Director runtime configuration

bosh update runtime-config runtime-config-dynatrace.yml

The updated runtime configuration applies to all new BOSH deployments going forward.

Deploy changes and run OneAgent

Since existing BOSH deployments won’t be automatically updated with the jobs specified in the runtime configuration, you need to re-deploy those deployments so that BOSH rolls out OneAgent:

bosh deploy

Undeploying OneAgent with BOSH

Uninstalling the Dynatrace OneAgent for BOSH add-ons requires that you update the runtime configuration with an “empty” manifest and re-deploy all BOSH deployments that the add-ons have executed.
Here is an example empty runtime configuration:

releases:
- {name: dynatrace-oneagent, version: 0.3.3}
  #specify version of latest release

Update the runtime configuration without Dynatrace-related jobs.

bosh update runtime-config empty-runtime-config.yml

bosh deploy

Known issues and workarounds

p-invitations app from AppsManager doesn’t start

If you’ve enabled the errands for AppsManager in PCF deployments, starting the p-invitations app might lead to a failure due to the restrictive memory limits of p-invitations. We’re working with Pivotal to solve this issue. In the meantime, please follow the following workaround to disable monitoring for p-invitations:

  1. From the Dynatrace navigation menu, click Settings > Monitoring overview > Process groups.
  2. Search for all p-invitations process groups and disable monitoring of these process groups.
  3. Re-run the AppsManager errands. The AppsManager deployments should now complete successfully.

Rate limits for deployment API requests

If you’re running a free trial of Dynatrace SaaS, your BOSH jobs may run into API throttling of our clusters. Deployment of the dynatrace-oneagent ordynatrace-oneagent-windows jobs may error out with a HTTP 403 - Requests are blocked or HTTP 429 - Rate limit response code. Please use the following workaround to download the respective installer and make it available on an internal web-server for download.

  1. Download Dynatrace OneAgent from one of the of the following locations:
    For Linux https://{environmentid}.live.dynatrace.com/api/v1/deployment/installer/agent/unix/default/latest?Api-Token={apitoken}
    For Windows https://{environmentid}.live.dynatrace.com/api/v1/deployment/installer/agent/windows/default-unattended/latest?Api-Token={apitoken}

  2. Once you’ve made the installer available for BOSH, you need to adapt the runtime-configuration and set the downloadurl property of the add-on to the OneAgent installer on your internal web server. The downloadurl defines an alternative location for downloading OneAgent.