Appdynamics for Azure App Service

AppDynamics App iQ Platform AppDynamics for Azure Version 4.4.3

Page 1 Deploy AppDynamics for Azure ...... 3 Install AppDynamics for Azure App Service ...... 4 Install the AppDynamics Azure Site Extension ...... 5 Install the AppDynamics Site Extension for Java ...... 8 Install the AppDynamics .NET Microservices Agent ...... 11 Install AppDynamics for Azure Service Fabric ...... 13 Install AppDynamics for Azure Cloud Services ...... 15 Upgrade AppDynamics.WindowsAzure NuGet Package ...... 17 4.4.3 Azure Enhancements and Resolved Issues ...... 18

Page 2 Deploy AppDynamics for Azure

AppDynamics integrates seamlessly with Microsoft Azure. AppDynamics offers visibility into .NET code execution and Microsoft Azure services out of the box, allowing you to troubleshoot performance bottlenecks and optimize the performance of your Microsoft Azure applications.

AppDynamics for Azure App Service

To install and deploy AppDynamics for Azure App Service:

For Ops teams: Install the AppDynamics Azure Site Extension. See Install the AppDynamics Azure Site Extension. For Dev teams: Install the AppDynamics.Agent.Azure.AppService.Windows NuGet package and configure the .NET agent in Azure App Service. See Install the AppDynamics .NET Microservices Agent and Install AppDynamics for Azure App Service.

AppDynamics for Azure Cloud Services and Azure Service Fabric

To install and deploy AppDynamics for Azure Service Fabric, see Install AppDynamics for Azure Service Fabric.

If you are instrumenting Cloud Services, see Install AppDynamics for Azure Cloud Services.

Upgrade the AppDynamics for Windows Azure NuGet Package

If you are currently using the AppDynamics.WindowsAzure NuGet Package, you will need to upgrade to a new NuGet package, depending on your Azure platform. See Upgrade AppDynamics.WindowsAzure NuGet Package.

There are two ways to install the .NET microservices agent into Azure App Service:

Use the AppDynamics Azure Site Extension: See Install the AppDynamics Azure Site Extension Use the AppDynamics for Windows Azure NuGet Package: See Install the AppDynamics .NET Microservices Agent

Azure Site Extension is used by Ops teams that may not have access to source files, or would not like to modify or recompile them, yet still want to monitor their Azure projects and solutions.

The NuGet Package is used by Dev teams to deploy the .NET agent so they can include the agent binaries, scripts, and configurations in their project and configure it using Visual Studio or other IDE.

You can use the Windows Azure Portal to add the AppDynamics Azure Site Extension to your Azure App Service web app. Azure Site Extension is used by Ops teams that may not have access to source files, or would not like to modify or recompile them, yet still want to monitor their Azure projects and solutions.

Prepare to Install

To install the AppDynamics for Windows Azure Site Extension, you need the following:

Connection information for your AppDynamics Controller. See also Agent and Controller Compatibility. A Windows Azure account. An Azure web app to monitor.

If you are upgrading from a previous version, see Upgrade the AppDynamics Azure Site Extension.

Add the AppDynamics Azure Site Extension

Add the AppDynamics Azure Site extension as you would any site extension for any Azure web app.

1. Log in to the Windows Azure Portal. 2. Browse to your web app.

If you want to configure the .NET Agent using environment variables, add the environment variables before you install the AppDynamics Azure Site Extension. See configure the agent using environment variables

3. From the DEVELOPMENT TOOLS list, click Extensions. 4. Click +Add to install the version of the AppDynamics Azure Site Extension you want to add to your web app. After you install the AppDynamics Azure Site Extension, it appears in the installed extensions list.

Configure the Controller Connection

You have the following options to configure the .NET Agent to connect to the AppDynamics Controller:

Configure the Controller connection using the Kudu console. Configure the Controller connection settings using environment variables.

For more detail, see Agent-to-Controller Connections.

Configure the Agent with the Kudu Console

When you add the AppDynamics Azure Site Extension to your web app, you can interactively configure the .NET Agent using the Kudu console.

1. Navigate to the AppDynamics Controller Configuration page in the Kudu Console: http://{web app}.scm.azurewebsites.net/appdynamics/ For example: https://myazureexample.scm.azurewebsites.net/appdynamics/ 2. On the AppDynamics Controller Configuration page, enter your Controller connection information. For example:

3. Click Validate to test the connection to the AppDynamics Controller and save your settings. 4. Restart your web app. After you apply some load to your web app, you can view it on flow maps in the AppDynamics Controller UI.

Configure the Agent Using Environment Variables

Configuring the .NET Agent using environment variables allows for unattended configuration. To configure agents in this manner, add the environment variables before you install the AppDynamics Azure Site Extension, as follows:

1. Navigate to SETTINGS > Application Settings for your web app. 2. Add the .NET Agent environment variables under App settings: appdynamics.controller.hostName: the address for the AppDynamics Controller appdynamics.controller.port: the Controller port appdynamics.agent.accountName: the account name you use to log on to the Controller appdynamics.agent.accountAccessKey: the account key you use to log on the Controller appdynamics.agent.applicationName: the business application name in the Controller appdynamics.controller.ssl.enabled: set to "True" to enable SSL connection to the Controller. Otherwise set to "False". For example:

3. Restart your web app. After you apply some load to your web app, you can view it on flow maps in the AppDynamics Controller UI.

Upgrade the AppDynamics Azure Site Extension

When you click on the Extensions tab for your web app, the Microsoft Azure Portal displays the currently installed version of the AppDynamics Azure Site Extension. The Update Available column of the installed extensions list indicates if there is a more recent minor release of the .NET Agent available. If so, you can click to update the extension from the list.

Upgrade a Major Version of the .NET Agent

AppDynamics maintains major release versions of the .NET Agent as separate site extensions. Therefore you need to uninstall the installed version of the AppDynamics Azure Site Extension before you upgrade to a new major release:

1. Log in to the Windows Azure Portal. 2. Stop your web app. 3. Click on the AppDynamics Azure Site Extension from the list of installed extensions and click Delete to uninstall it. 4. Install the new version of the AppDynamics Azure Site Extension as normal.

If you are upgrading from version 4.2 of the .NET agent and you used environment variable configuration, you must update your web app environment variables. See configure the agent using environment variables. Note that the APPD_UNATTENDED variable is no longer required.

Prepare to Install

To install the AppDynamics for Windows Azure Site Extension, you need the following:

Connection information for your AppDynamics Controller. See also Agent and Controller Compatibility. A Windows Azure account. An Azure web app to monitor.

If you are upgrading from a previous version, see Upgrade the AppDynamics Azure Site Extension.

Add the AppDynamics Azure Site Extension

Add the AppDynamics Azure Site extension as you would any site extension for any Azure web app.

1. Log in to the Windows Azure Portal. 2. Browse to your web app. If you want to configure the Java agent using environment variables, add the environment variables before you install the AppDynamics Azure Site Extension. See configure the agent using environment variables. 3. From the DEVELOPMENT TOOLS list, click Extensions. 4. Click +Add to install the version of the AppDynamics Java Agent you want to add to your web app. After you install the AppDynamics Azure Site Extension, it appears in the installed extensions list.

Configure the Controller Connection

You have the following options to configure the Java Agent to connect to the AppDynamics Controller:

Configure the Controller connection using the Kudu console. Configure the Controller connection settings using environment variables.

For more detail, see Agent-to-Controller Connections.

Configure the Agent with the Kudu Console

When you add the AppDynamics Azure Site Extension to your web app, you can interactively configure the Java agent using the Kudu console.

1. Navigate to the AppDynamics Controller Configuration page in the Kudu Console: http://{web app}.scm.azurewebsitesJava/appdynamics/ For example: https://myazureexample.scm.azurewebsitesJava/appdynamics/ 2. On the AppDynamics Controller Configuration page, enter your Controller connection information. For example:

Configure the Agent Using Environment Variables

Configuring the Java agent using environment variables allows for unattended configuration. To configure agents in this manner, add the environment variables before you install the AppDynamics Azure Site Extension, as follows:

1. Navigate to SETTINGS > Application Settings for your web app. 2. Add the Java agent environment variables under App settings: appdynamics.controller.hostName: the address for the AppDynamics Controller appdynamics.controller.port: the Controller port appdynamics.agent.accountName: the account name you use to log on to the Controller appdynamics.agent.accountAccessKey: the account key you use to log on the Controller appdynamics.agent.applicationName: the business application name in the Controller appdynamics.controller.ssl.enabled: set to "True" to enable SSL connection to the Controller. Otherwise set to "False". For example:

3. Restart your web app. After you apply some load to your web app, you can view it on flow maps in the AppDynamics Controller UI.

Upgrade the AppDynamics Azure Site Extension

When you click on the Extensions tab for your web app, the Microsoft Azure Portal displays the currently installed version of the AppDynamics Azure Site Extension. The Update Available column of the installed extensions list indicates if there is a more recent minor release of the Java Agent available. If so, you can click to update the extension from the list.

Upgrade a Major Version of the Java Agent

AppDynamics maintains major release versions of the Java Agent as separate site extensions. Therefore you need to uninstall the installed version of the AppDynamics Azure Site Extension before you upgrade to a new major release:

Install the NuGet package AppDynamics.Agent.Azure.AppService.Windows to add the .NET microservices agent directly to projects you plan to deploy to Windows Azure. This package works for Azure App Service (formerly Azure Websites): Web Apps and API Apps.

Prepare to Install the NuGet Package

To install the AppDynamics for Windows Azure NuGet package you need the following:

Connection information for your AppDynamics Controller version 4.4 Visual Studio 2012 or later A Visual Studio solution to monitor Windows Azure SDK Windows Azure account

These instructions assume you are familiar with NuGet package management in Visual Studio and with the Microsoft Azure Portal. You can also try the step-through tutorial on how to instrument an App Service on the community knowledgebase.

Add the .NET Microservices Agent to Your Azure Solution

Use the NuGet package manager to browse the nuget.org package source and install the AppDynamics.Agent.Azure.AppService.Wi ndows package to your Azure solution in Visual Studio.

For details about managing NuGet packages, see the documentation for your version of Visual Studio.

The AppDynamics.Agent.Azure.AppService.Windows package installation prompts you as follows:

1. The installer may ask you to verify your changes. If so, click OK. 2. Click I accept to agree to the terms of the license. 3. In the Solution Explorer, click the AppDynamicsConfig.json file.

4. Enter the connection information for your AppDynamics Controller in the area on the left.

For information about the AppDynamicsConfig.json file, see AppDynamicsConfig.json File.

Configure the Controller Connection

You have the following options to configure the .NET Agent to connect to the AppDynamics Controller:

During development: As shown in the previous screenshot, you can enter your environment variables in the AppDynamicsConfig.json file, and save it in source control. During build: Define your msbuild parameters or environment variables that are passed to the AppDynamicsConfig.json file at

Copyright © AppDynamics 2012-2017 Page 11 build time. AppDynamicsConfig.json does exist at build time. So, if you're defining your msbuild parameters/env variables at build time, you will need to ignore it in source control so that the new AppDynamicsConfig.json file will be created. During runtime: Enter your environment variables in Azure.

By default, the .NET microservices agent names Azure tiers as site name. The .NET microservices agent names Azure nodes by machine name appended with the website hostname.

Copyright © AppDynamics 2012-2017 Page 12 Install AppDynamics for Azure Service Fabric The following instructions explain how to deploy the .NET microservices agent for AppDynamics for Azure Service Fabric.

Before you Install

From nuget.org, download the NuGet package AppDynamics.Agent.Distrib.Micro.Windows from https://www.nuget.org/packages/Ap pDynamics.Agent.Distrib.Micro.Windows/, then extract it to a folder. Then, use the following instructions to deploy the agent package.

The following steps must be done manually, using Visual Studio or other integrated development environment (IDE).

Deploy the Package

1. From your editor, open ServiceManifest.xml in each folder in the published application root. 2. Add the following environment variables in each CodePackage:

... 3. Unpack AppDynamics.Agent.dll, AppDynamics.Profiler_x64.dll, AppDynamicsAgentLog.config, AppDynamicsConfig.js on from \content\AppDynamics to the code package folder that contains the executable you want to run. 4. Rename AppDynamicsConfig.json to .AppDynamicsConfig.json 5. Update .AppDynamicsConfig.json with your configuration information:

{ "controller": { "host":"", "port":0, "account":"", "password":"" }, "application": { "name":"" } }

Do not specify node, it will be assigned automatically; specifying tier is optional, it could be assigned automatically.

For information about the AppDynamicsConfig.json file, see AppDynamicsConfig.json File.

Next steps are optional, and should be used only if you need per service-instance control of the controller/application/tier.

1. Add the following environment variables to each CodePackage: 2. Modify ApplicationManifest.xml. In each ServiceManifestImport and CodePackage folder add:

Copyright © AppDynamics 2012-2017 Page 13 2. In ServiceManifestImport: In Parameters: For each service: 3. If you need to provide the AppDynamics configuration during application package deployment, you can now do it using the -Ap plicationParameter switch of the New-ServiceFabricApplication cmdlet.

Copyright © AppDynamics 2012-2017 Page 14 Install AppDynamics for Azure Cloud Services You can use Microsoft Visual Studio with the NuGet package AppDynamics.Agent.Azure.CloudServices to add the .NET Agent directly to Azure Cloud Services projects: Web Roles and Worker Roles. Prepare to Install the NuGet Package

To install the AppDynamics for Windows Azure NuGet package you need the following:

Connection information for your Agent-to-Controller Connections version 4.4 Visual Studio 2012 or later A Visual Studio solution to monitor The user account running Visual Studio must have the following permissions to the solution: Read and Write permissions to each project directory Read and Write permissions to each Visual Studio .NET C# Project (*.csproj) file Read and Write permissions to the Service Definition (ServiceDefinition.csdef) file Windows Azure SDK Windows Azure account

If you are upgrading to a new version of the AppDynamics for Windows Azure NuGet Package, see Upgrade AppDynamics.WindowsAzure NuGet Package.

Add the .NET Agent to Your Azure Solution

Use the NuGet package manager to browse the nuget.org package source and install the AppDynamics.Agent.Azure.CloudServices package to your Azure solution in Visual Studio.

For detail about managing NuGet packages, see the documentation for your version of Visual Studio.

The AppDynamics.Agent.Azure.CloudServices package installation prompts you as follows:

The installer may ask you to verify your changes. If so, click OK. Click I accept to agree to the terms of the license.

The package manager installs the .NET agent into your project.

The configuration file installs to /App_Data/AppDynamics/Config/config.xml. Enter the connection information for your AppDynamics Controller in the config.xml file. For details about Controller connection settings, see Agent-to-Control ler Connections.

If you want to customize the tier name, edit config.xml under /App_Data/AppDynamics/Config.xml. For more information and examples, see "Name IIS Tiers Manually" on Name .NET Tiers.

After you finish any configuration changes, publish your solution to Windows Azure. For Cloud Services solutions, you can put load on your published project and log on to the AppDynamics Controller and begin monitoring your solution.

Update .NET Agent Configuration for Cloud Services

If you have already published your solution, you can update the .NET Agent configuration for the currently installed version without upgrading the agent.

1. Edit the config.xml file to make configuration changes. 2. Edit the startup.cmd file under /AppDynamics. 3. By default, the APPD_AGENT_CONFIGUPDATE variable is set to true. If you want to modify the configuration on your Azure Cloud Services machine, and you want to prevent the AppDynamics script from overwriting it, set APPD_AGENT_CONFIGUPDATE to false.

If you are currently using the AppDynamics.WindowsAzure NuGet package to monitor your Azure solutions, you must upgrade to one of the newest packages on nuget.org, depending on your platform and the applications that you want to monitor. For a list of packages, see .NET Microservices Agent.

To upgrade your Azure NuGet package:

1. In Visual Studio or other IDE, uninstall the AppDynamics.WindowsAzure NuGet package.

For Azure App Service only: After you uninstall the NuGet package, you must delete the AppDynamics folder from the Azure portal and your Visual Studio solution. You may need to stop your application first before deleting this folder. During uninstallation, the webconfig modification that is responsible for filtering user requests against the AppDynamics folder is removed, but this does not remove the AppDynamics folder. You must manually delete this folder. You must also remove the AppDynamics-specific information from apphostconfig.xdt.

2. Install one of the new NuGet packages. See .NET Microservices Agent for a list of packages.

Enhancements:

Microsoft Orleans is supported across both the .NET agent and the .NET microservices agents. .NET Core on Windows is supported on the .NET microservices agent.

The following NuGet packages are now available. If you have used a previous version of an AppDynamics NuGet package, you will need to upgrade to the new version. See Upgrade AppDynamics.WindowsAzure NuGet Package.

AppDynamics.Agent.Distrib.Micro.Windows AppDynamics NuGet package for .NET. This package should not be installed directly and is intended for download and file distribution. This package is used for Azure Service Fabric deployments. See Install AppDynamics for Azure Service Fabric for instructions.

AppDynamics.Agent.Windows AppDynamics .NET Core microservices agent for Windows. Recommended for standalone installations. See Install the .NET Core Microservices Agent for Windows for deployment instructions. NOTE: This package does not support .NET Framework, only .NET Core for Windows.

AppDynamics.Agent.Azure.CloudServices AppDynamics .NET agent for Azure Cloud Services. See Install AppDynamics for Azure Cloud Services.

AppDynamics.Agent.Azure.AppService.Windows AppDynamics .NET microservices agent for Azure App Service. This package is intended for applications deployed to Azure App Service (Azure Web Apps and Azure API Apps). See Install the AppDynamics .NET Microservices Agent and Ins tall AppDynamics for Azure App Service for instructions.