Deploy OneAgent on IBM Cloud Foundry for application-only monitoring

IBM Cloud Foundry provides a Platform as a Service (PaaS) solution that's based on open source Cloud Foundry technology.

Applications deployed on IBM Cloud Foundry (formerly Bluemix) are usually run through technology-specific and IBM-related buildpacks that provide framework and runtime support for applications running on the platform. For example, to run Java applications on IBM Cloud Foundry, typically the IBM WebSphere Liberty buildpack is used rather than the normal Java buildpack.

The following guidelines apply to integration with the supported Cloud Foundry buildpacks.

Before you begin

You'll need to

acquire DESK environment credentials
review Supported applications and versions
get the Cloud Foundry CLI

Generate PaaS token

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

How to get your PaaS token

Environment ID

Login with your DESK account.
Select Deploy DESK from the navigation menu.
Click the Set up PaaS integration button. Your environment ID appears in the Environment ID text box.
Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.

API Token

The API token is used in combination with your environment ID to download OneAgent. Go to Deploy DESK > Set up PaaS integration to access the InstallerDownload token. For security reasons, it's recommended that you create a discrete token for each environment.

To generate a new token

Click the Generate new token button.
Type in a meaningful name for your token. A meaningful token name might be the name of the platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing tokens, go to Settings -> Integration -> Platform as a Service.
Click Generate to create the token. The newly created 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.

Create a DESK service in your IBM Cloud Foundry environment

Cloud Foundry (and therefore also IBM Cloud Foundry) allows you to connect applications with 3rd party tools and other external resources (for example, databases) by means of services. On Cloud Foundry, service instances hold the credentials that are required to connect to such resources. You'll use this same approach to connect your apps with OneAgent.This is why you need to define a service instance by either creating a so-called "user-provided service" or by using a service broker application. To create a DESK service in your Cloud Foundry environment, select one of the following options:

Option 1: Create a user-provided service

Create a single service instance for DESK with the name desk as a substring, like in the example below. You will then be prompted for your environment ID and API token. The API token corresponds to the token mentioned above.

DESK SaaS DESK Managed

cf cups desk-service -p "environmentid, apitoken"

cf cups desk-service -p "environmentid, apitoken, apiurl"

The apiurl parameter specifies the API endpoint of your DESK Server and needs to be set to https://<YourDESKServerURL>/e/<environmentID>/api.

Option 2: Create a service instance via service broker

If you want to maintain DESK credentials in a central location, use a service broker. For complete details, visit GitHub. You must configure and run the broker as an application, add the service broker to Cloud Foundry, enable service access to users, and finally, create the service instance.

Bind DESK service to your application

You can either bind the created DESK service to your application in your manifest.yml file prior to starting your app or you can bind the service to your app and restage the app afterwards.

If you're pushing a Java application, the result may resemble the following example. If you're deploying to IBM Cloud Foundry, be sure to accept IBM licenses by setting the proper environment variables. For details, please refer to the buildpack readme.

---
applications:
- name: demo-helloworld
  path: target/JavaHelloWorldApp.war
  buildpack: https://github.com/cloudfoundry/ibm-websphere-liberty-buildpack.git
  memory: 512M
  instances: 1
  host: hello-world-${random-word}
  disk_quota: 1024M
services:
  - desk-service
env:
  IBM_LIBERTY_LICENSE: <liberty-license-key>
  IBM_JVM_LICENSE: <jvm-license-key>

Configure the default OneAgent log stream for Cloud Foundry (optional)

By default, OneAgent logs are written to the Cloud Foundry standard error stream. With OneAgent version 1.125 or later, you can configure the default OneAgent log stream for applications deployed in your IBM Cloud Foundry environment. All you have to do is set the environment variable DT_LOGSTREAM to either stdout or stderr.

For example:

cf set-env APP_NAME DT_LOGSTREAM stdout

Configure a proxy address (optional)

In case your environment uses a proxy, you need to set the DT_PROXY environment variable to pass the proxy credentials to OneAgent, as shown below.

cf set-env DT_PROXY <proxy address>