Set up Dynatrace on Heroku

Heroku is a cloud Platform as a Service (PaaS) that enables you to build and run applications in the cloud. Applications deployed to Heroku are usually run through one or more buildpacks that provide framework and runtime support.

Capabilities

The Heroku buildpack for Dynatrace OneAgent is language independent and can be used with any Dynatrace supported language, including Node.js-based applications. If you’ve used the Dynatrace NPM module for PaaS module, you can remove it from your dependencies as the buildpack discovers and instruments your Node.js applications automatically.

You also no longer need to rely on releases of the Dynatrace OneAgent dependencies for NPM. The Heroku buildpack for Dynatrace OneAgent automatically fetches the latest version of Dynatrace OneAgent so that you can receive potential fixes as quickly and easily as possible. If you’ve specified a default OneAgent installation version for new hosts and applications in your OneAgent update settings, the Heroku buildpack for Dynatrace OneAgent will download the defined default version of Dynatrace OneAgent.

The following guidelines explain how to enable Dynatrace monitoring for your Heroku applications by adding a Dynatrace Heroku buildpack to the Heroku configuration of your application.

The Dynatrace Heroku buildpack enables you to monitor all supported languages on Linux systems.

Prerequisites

Installation

These guidelines explain how to integrate Dynatrace OneAgent into your Heroku dynos and begin monitoring your Heroku applications.

Get the Heroku CLI

To configure Heroku applications to use the Dynatrace Heroku buildpack, you can either use the Heroku CLI or you can configure your applications using the Heroku dashboard.

Add the Dynatrace Heroku buildpack

To integrate Dynatrace OneAgent into your existing application, you need to add the Dynatrace Heroku buildpack to your application buildpacks and set your Dynatrace environment ID and PaaS token using the commands below.

# Add the Dynatrace buildpack
heroku buildpacks:add https://github.com/Dynatrace/heroku-buildpack-dynatrace.git#<version>


# Set required credentials to your Dynatrace environment
heroku config:set DT_TENANT=<environmentID>
heroku config:set DT_API_TOKEN=<token>


# Deploy to Heroku
git push heroku master

Once you push these changes, the buildpack installs Dynatrace OneAgent to automatically monitor your application.

Additional configuration

The Dynatrace Heroku buildpack supports the following configurations:

Environment variable
Description
DT_TENANT
Your Dynatrace environment ID
Note: For details on how to determine your environment ID, see environment ID.
DT_API_TOKEN
The PaaS token for integrating your Dynatrace environment with Heroku.
DT_API_URL
- For Dynatrace SaaS, where OneAgent can connect to the internet: https://<your-environment-ID>.live.dynatrace.com/api
- For Dynatrace Managed: https://<your-managed-cluster-domain>/e/<your-environment-ID>/api
- For environment ActiveGates (SaaS or Managed), use the following to download the OneAgent, as well as to communicate OneAgent traffic through the ActiveGate: https://<your-ActiveGate-IP-or-FQDN>:9999/e/<your-environment-ID>/api
Note: For details on how to determine your environment ID, see environment ID.
DT_DOWNLOAD_URL
optional A direct download URL for Dynatrace OneAgent. If this environment variable is set, the buildpack will download OneAgent from this location
SSL_MODE
optional Set to all if you want to accept all self-signed SSL. certificates
DT_TAGS
not recommended The tags you want to add to the monitored. applications
DT_CUSTOM_PROP
not recommended Apply if you want to split by the component and/or environment.
SKIP_ERRORS
optional If set to 1, application deployment won't fail on OneAgent installer download errors

We recommend creating environment variables specific to process detection. Environment variables that serve other scopes, such as DT_TAGS or DT_CUSTOM_PROP, might cause incorrect or unintentional splits because all values of environment variables are evaluated for process-group detection.

The Heroku buildpack for Dynatrace OneAgent requires no changes to your application source code:

You no longer need to install a dependency on @dynatrace/oneagent in the project directory of your Node.js application. Also, you’re no longer required to add the following statement as the first statement of your Node.js application:

try {
    require('@dynatrace/oneagent')();
} catch(err) {
    console.log(err.toString());
}

Because of these advantages, the Heroku buildpack for Dynatrace OneAgent supersedes the Dynatrace NPM module for PaaS and requires OneAgent version 1.141+.

If you’re eager to start using the Heroku buildpack for Dynatrace OneAgent instead of the Dynatrace NPM module for PaaS, we’ve got you covered. All you have to do is remove the dependency on @dynatrace/oneagent in your package.json file:

$ npm uninstall --save @dynatrace/oneagent

Further, you can also remove the require statement mentioned above from your Heroku application.

You can use a different Dynatrace environment for Heroku applications that are enriched with OneAgent.

For OneAgent version 1.139+, if you have an existing Heroku application where you have already added the OneAgent code modules for a specific Dynatrace environment, you can have the OneAgent report to another Dynatrace environment.

To do this you need to make a call to the REST endpoint of your second Dynatrace environment. Don't forget to adapt the respective placeholders <environmentID> and <token>.

curl "https://<environmentID>.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo?Api-Token=<token>"

In return, you get a JSON object that covers the required information that needs to be passed as an environment variable to the application container. Make sure you set the environment variables of your Heroku application as described below:

  • DT_TENANT: equals tenantUUID
  • DT_TENANTTOKEN: equals tenantToken
  • DT_CONNECTION_POINT: semi-colon separated list of communicationEndpoints

Configure network zones optional

You can configure network zones via an environment variable:

heroku config:set DT_NETWORK_ZONE=<your.network.zone>

See network zones for more information.

Update OneAgent

When a new version of OneAgent becomes available, you need to trigger a rerun of the buildpack in Heroku. The Dynatrace buildpack will automatically fetch the latest version of OneAgent.

If you've specified a default OneAgent install version for new hosts and applications in your OneAgent updates settings, the Heroku buildpack will automatically fetch the defined default version of OneAgent.

Related topics