Integrate OneAgent on App Service for Linux and containers

Integrate Dynatrace on built-in image

Azure App Service for Linux allows you to customize its base container at runtime using a startup script or script command that must be executed in a bash shell or Azure Cloud Shell. The script can be configured in multiple ways:

Set startup script command/file at creation time using Azure CLI

shellcopydownload
az webapp create -n <my-app> -g <my-resourcegroup> -p <my-appservice-plan> --runtime <runtime-tag> --startup-file <startup-script/command>

Set script command/file at creation time for an existing App Service

shellcopydownload
az webapp config set -n <my-app> -g <my-resourcegroup> --startup-file <startup-script/command>

Set script command/file using ARM template

Use the appCommandLine property of your ARM template to set the startup script/command.

jsoncopydownload
{
  "acrUseManagedIdentityCreds": false,
  "acrUserManagedIdentityId": null,
  "alwaysOn": false,
  "apiDefinition": null,
  "apiManagementConfig": null,
  "appCommandLine": "<startup-script/command>",
  "appSettings": null,
  "autoHealEnabled": false,
  "autoHealRules": null,
  "autoSwapSlotName": null,
...

Set startup script command/file in the Azure portal

Script or command?

Startup scripts require that you package the script along with your application. If you don't want to have this dependency, use startup commands.

The script/command is executed within the container init script, which is implemented differently on each technology stack.

For details on startup commands, see the Azure App Service for Linux documentation on What are the expected values for the Startup File section when I configure the runtime stack?

Integrate Dynatrace using a startup script/command

To integrate Dynatrace, select one of the options below.

• Alpine-based images:

  bashcopydownload
  wget -O /tmp/installer.sh -s \"$DT_ENDPOINT/api/v1/deployment/installer/agent/unix/paas-sh/latest?Api-Token=$DT_API_TOKEN&flavor=$DT_FLAVOR&include=$DT_INCLUDE\" && sh /tmp/installer.sh /home && LD_PRELOAD='/home/dynatrace/oneagent/agent/lib64/liboneagentproc.so' $START_APP

• Other images:

  bashcopydownload
  curl -o /tmp/installer.sh -s \"$DT_ENDPOINT/api/v1/deployment/installer/agent/unix/paas-sh/latest?Api-Token=$DT_API_TOKEN&flavor=$DT_FLAVOR&include=$DT_INCLUDE\" && sh /tmp/installer.sh /home && LD_PRELOAD='/home/dynatrace/oneagent/agent/lib64/liboneagentproc.so' $START_APP

Set/replace the following parameters of the script:

Note: If you use a shell other than bash, make sure to adapt the script appropriately to the shell's character escape requirements.

Example: Integrate into a node.js application using Azure CLI within a bash shell

Configure the startup command

Restart the web app twice

Configure the startup command

bashcopydownload
RESOURCE_GROUP="my-appservice-test"
APPSVC="my-linux-webapp"
DT_API_URL="https://XXXXXX.live.dynatrace.com"
DT_API_TOKEN="XXXXXX"
DT_FLAVOR="musl"
DT_INCLUDE="nodejs"
START_APP_CMD="pm2 start index.js --no-daemon"
STARTUP_CMD="curl -o /tmp/installer.sh -s \"$DT_API_URL/api/v1/deployment/installer/agent/unix/paas-sh/latest?Api-Token=$DT_API_TOKEN&flavor=$DT_FLAVOR&include=$DT_INCLUDE\" && sh /tmp/installer.sh /home && LD_PRELOAD='/home/dynatrace/oneagent/agent/lib64/liboneagentproc.so' $START_APP_CMD"

az webapp config set --resource-group $RESOURCE_GROUP --name $APPSVC --startup-file "$STARTUP_CMD"

Restart the web app twice

After you configure the startup command, restart the web app two times:

• Restart once to initialize OneAgent installation
• Restart again to start OneAgent instrumenting your application

Integrate Dynatrace on custom image

To integrate OneAgent with the application image, you have two options:

• Integrate the OneAgent image layer provided by Dynatrace
• Download OneAgent artifacts at image build-time from Dynatrace REST API

Option 1: Integrate using Dynatrace offered OneAgent image layer

This option requires that you have Docker v17.05+ installed on your computer.

1. Sign in to Docker with your Dynatrace environment ID as the username and your PaaS token as the password.

   bashcopydownload
   docker login -u <environmentID> <ADDRESS>

2. Add the following lines to your application image Dockerfile, after the last FROM command:

   bashcopydownload
   COPY --from=<ADDRESS>/linux/oneagent-codemodules:<TECHNOLOGY> / /
   ENV LD_PRELOAD /opt/dynatrace/oneagent/agent/lib64/liboneagentproc.so

   Replace the following placeholders in the template

   Parameter	Description
   <ADDRESS>	Your Dynatrace registry endpoint. Use either your environment cluster endpoint or an ActiveGate address.
   <TECHNOLOGY>	Configure required code modules, depending on the used technology stack. all includes all available technologies, but it increases the download package size. Alternatively, choose an identifier appropriate to your application stack, such as java, dotnet, nodejs, or php. For details, see the API documentation.

   What if my Docker image is based on Alpine Linux?

   Dynatrace OneAgent supports Alpine Linux–based environments. To use an Alpine Linux compatible OneAgent, use image name oneagent-codemodules-musl (as shown in the adapted template below) instead of oneagent-codemodules.

   bashcopydownload
   COPY --from=<ADDRESS>/linux/oneagent-codemodules-musl:<TECHNOLOGY> / /
   ENV LD_PRELOAD /opt/dynatrace/oneagent/agent/lib64/liboneagentproc.so

3. Build your application image.

   Build the Docker image from your Dockerfile to use it in your Kubernetes environment.

   bashcopydownload
   docker build -t yourapp .

4. Restart the web app two times:

   • Restart once to initialize the OneAgent install script
   • Restart again to start OneAgent on the host

Option 2: Integrate using installer script from Dynatrace REST API

1. Add the following two lines to your Dockerfile.

   • for non Alpine based:

     bashcopydownload
     RUN curl -o /tmp/installer.sh -s <DT_ENDPOINT>/api/v1/deployment/installer/agent/unix/paas-sh/latest?Api-Token=<DT_API_TOKEN>&flavor=<DT_FLAVOR>&include=<DT_INCLUDE> && sh /tmp/installer.sh /home
     
     ENV LD_PRELOAD /home/dynatrace/oneagent/agent/lib64/liboneagentproc.so

   • for Alpine based:

     bashcopydownload
     RUN wget -O /tmp/installer.sh -s <DT_ENDPOINT>/api/v1/deployment/installer/agent/unix/paas-sh/latest?Api-Token=<DT_API_TOKEN>&flavor=<DT_FLAVOR>&include=<DT_INCLUDE> && sh /tmp/installer.sh /home
     
     ENV LD_PRELOAD /home/dynatrace/oneagent/agent/lib64/liboneagentproc.so

   Replace the following parameters in the above template:

   Parameter	Description
   <DT_ENDPOINT>	Your Dynatrace API endpoint. Use either your environment cluster endpoint or an ActiveGate address.
   <DT_API_TOKEN>	API Token to access the Dynatrace REST API. Create an API Token with the InstallerDownload scope.
   <DT_FLAVOR>	Configure the required architecture. default for standard, glibc-based Linux images musl for Alpine Linux–based images
   <DT_INCLUDE>	Configure required code modules, depending on the used technology stack. all includes all available technologies, but it increases the download package size. Alternatively, choose an identifier appropriate to your application stack, such as java, dotnet, nodejs, or php. For details, see the API documentation.

2. Build your application image.

   Build the Docker image from your Dockerfile to use it in your Kubernetes environment.

   bashcopydownload
   docker build -t yourapp .

3. Restart the web app two times:

   • Restart once to initialize the OneAgent install script
   • Restart again to start OneAgent on the host

When an update is available, restart your application to update OneAgent.

Each time you want to leverage a new version of Dynatrace OneAgent, you need to rebuild your local OneAgent code modules and application image. Any newly started pods from this application image will be monitored with the latest version of OneAgent.

If you've specified a default OneAgent installation version for new hosts and applications using OneAgent update settings, your web apps will be automatically monitored by the defined default version of OneAgent.

To uninstall OneAgent

1. In Azure Portal, go to your web app > Configuration > General settings.
2. Remove your startup command (leave Startup Command empty).
3. Select Save.

To uninstall OneAgent, remove references from above described Dynatrace integration from your application image and redeploy the application.