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

Create a PaaS Token.
Review the list of supported applications and versions.
The OneAgent code module memory requirement is 200 MB of your slug size.

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.

bash
# 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	optional The tags you want to add to the monitored applications
SKIP_ERRORS	optional If set to `1`, application deployment won't fail on OneAgent installer download errors

How to use the Heroku buildpack for Dynatrace OneAgent in place of the Dynatrace NPM module for PaaS

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:

javascript
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:

bash
$ 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.

How to use a different Dynatrace environment for Heroku applications 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>.

bash
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:

bash
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.