Microsoft Azure App Service Extension

Requirements

1. If you haven’t already, set up the Microsoft Azure integration first.

2. The extension supports the following resource types:

   • Azure App Service Web Apps
   • Function Apps hosted on Basic, Standard, and Premium plans.
   Function Apps on consumption plans and out-of-process (isolated) functions are not supported. Interested in support for other App Service resource types or runtimes? Sign up to be notified when a beta becomes available.

3. The Datadog .NET APM extension supports the following .NET runtimes in both x64 and x86 architectures when running on Windows OS (AAS does not yet support extensions on Linux). For more details about automatically instrumented libraries, see the Tracer documentation.

   • .NET Framework 4.6.1 and later
   • .NET Core 2.1
   • .NET Core 2.2 (Microsoft support ended 2019-12-23)
   • .NET Core 3.0 (Microsoft support ended 2020-03-03)
   • .NET Core 3.1
   • .NET 5
   • .NET 6

4. Datadog recommends doing regular updates to the latest version of the extension to ensure optimal performance, stability, and availability of features. Note that both the initial install and subsequent updates require your web app to be fully stopped in order to install/update successfully.

Note: Datadog’s automatic instrumentation relies on the .NET CLR Profiling API. This API allows only one subscriber (for example, Datadog’s .NET Tracer with Profiler enabled). To ensure maximum visibility, run only one APM solution within your application environment.

Starting with v2.3.0, the .NET extension no longer relies on semantic versioning. The extension uses the following scheme: x.y.zAA where x.y.z is the .Net Tracer version and AA is dedicated only to the extension. Any leading zeroes in zAA is trimmed by NuGet packaging so the version becomes x.y.A.

For example:

• Extension 2.3.0 uses the Tracer v2.3.0
• Extension 2.3.1 uses the Tracer v2.3.0
• Extension 2.3.2 uses the Tracer v2.3.0
• Extension 2.3.100 uses the Tracer v2.3.1
• Extension 2.3.101 uses the Tracer v2.3.1
• Extension 2.3.200 uses the Tracer v2.3.2

Installation

1. Configure the Azure integration to monitor your web app or function. Verify it is configured correctly by ensuring that you see the corresponding azure.app_service.count or azure.functions.count metric in Datadog. Note: This step is critical for metric/trace correlation, functional trace panel views, and improves the overall experience of using Datadog with Azure App Services.

2. Open the Azure Portal and navigate to the dashboard for the Azure app you wish to instrument with Datadog.

3. Go to the Application settings tab of the Configuration page.

4. Add your Datadog API key as an application setting called DD_API_KEY and a value of your Datadog API Key.

5. Configure optional application settings:

   • Set the DD_SITE to (defaults to datadoghq.com).
   • Set DD_ENV to group your traces and custom statistics.
   • Set DD_SERVICE to specify a service name (defaults to your app name).
   • Set DD_LOGS_INJECTION:true for correlation with application logs from your app.
   • See a full list of optional configuration variables.

6. Click Save (this restarts your application).

7. [REQUIRED] Stop your application by clicking Stop.

8. Go to the Azure extensions page and select the Datadog APM extension.

9. Accept the legal terms, click OK, and wait for the installation to complete. Note: the app must be in a stopped state for this step to complete successfully.

10. Start the main application, click Start:

Application logging

You can send logs from your application in Azure App Service to Datadog in one of the following ways:

1. Agentless logging with automatic instrumentation
2. Agentless logging with the Serilog sink

Both methods allow trace ID injection, making it possible to connect logs and traces in Datadog. To enable trace ID injection with the extension, add the application setting DD_LOGS_INJECTION:true.

Note: Since this occurs inside your application, any Azure Platform logs you submit with diagnostic settings do not include the trace ID.

Custom metrics with DogStatsD

The Azure App Service extension includes an instance of DogStatsD (Datadog’s metrics aggregation service). This enables you to submit custom metrics, service checks, and events directly to Datadog from Azure Web Apps and Functions with the extension.

Writing custom metrics and checks in Azure App Service is similar to the process for doing so with an application on a host running the Datadog Agent. To submit custom metrics to Datadog from Azure App Service using the extension:

1. Add the DogStatsD NuGet package to your Visual Studio project.
2. Initialize DogStatsD and write custom metrics in your application.
3. Deploy your code to Azure App Service.
4. Install the Datadog App Service extension.

Note: Unlike the standard DogStatsD config process, there is no need to set ports or a server name when initializing the DogStatsD configuration. There are ambient environment variables in Azure App Service that determine how the metrics are sent (requires v6.0.0+ of the DogStatsD client).

To send metrics use this code:

// Configure your DogStatsd client and configure any tags
if (!DogStatsd.Configure(new StatsdConfig() { ConstantTags = new[] { "app:sample.mvc.aspnetcore" } }))
{
    // `Configure` returns false if the necessary environment variables are not present.
    // These environment variables are present in Azure App Service, but
    // need to be set in order to test your custom metrics: DD_API_KEY:{api_key}, DD_AGENT_HOST:localhost
    // Ignore or log the error as it suits you
    Console.WriteLine("Cannot initialize DogstatsD.");
}

// Send a metric
DogStatsd.Increment("sample.startup");

Note: To send only custom metrics (while disabling tracing) set the following variables in your application’s config:

• Set DD_TRACE_ENABLED to false.
• Set DD_AAS_ENABLE_CUSTOM_METRICS to true. Learn more about custom metrics.

Requirements

1. If you haven’t already, set up the Microsoft Azure integration first.

2. The extension supports Azure App Service Web Apps. Function Apps are not supported.

   Support for Java Web Apps is in beta for extension v2.4+. There are no billing implications for tracing Java Web Apps during this period.
   
   Interested in support for other App Service resource types or runtimes? Sign up to be notified when a beta becomes available.

3. The Datadog Java APM extension supports all Java runtimes on Windows OS. Azure App Service does not support extensions on Linux. For more details about automatically instrumented libraries, see the Tracer documentation.

4. Datadog recommends doing regular updates to the latest version of the extension to ensure optimal performance, stability, and availability of features. Note that both the initial install and subsequent updates require your web app to be fully stopped in order to install/update successfully.

Installation

1. Configure the Azure integration to monitor your web app or function. Verify it is configured correctly by ensuring that you see the corresponding azure.app_service.count or azure.functions.count metric in Datadog. Note: This step is critical for metric/trace correlation, functional trace panel views, and avoiding various broken user experiences on the Datadog site.

2. Open the Azure Portal and navigate to the dashboard for the Azure Web App you wish to instrument with Datadog.

3. Go to the Application settings tab of the Configuration page.

4. Add your Datadog API key as an application setting called DD_API_KEY and a value of your Datadog API Key.

5. Configure optional application settings:

   • Set the DD_SITE to (defaults to datadoghq.com).
   • Set DD_ENV to group your traces and custom statistics.
   • Set DD_SERVICE to specify a service name (defaults to your web app name).
   • See a full list of optional configuration variables.

6. Click Save (this restarts your application).

7. [REQUIRED] Stop your application by clicking Stop.

8. Go to the Azure extensions page and select the Datadog APM extension.

9. Accept the legal terms, click OK, and wait for the installation to complete. Note: the web app must be in a stopped state for this step to complete successfully.

10. Start the main application, click Start:

Application logging from Azure Web Apps

Sending logs from your application in Azure App Service to Datadog requires streaming logs to Datadog directly from your app. Submitting logs with this method allows for trace ID injection, which makes it possible to connect logs and traces in Datadog.

Note: Trace ID injection occurs inside your application. Azure Resource logs are generated by Azure in the management plane, and therefore do not include the trace ID.

See instructions for Agentless logging with Java to configure application logging for Java in Azure App Service.

Custom metrics with DogStatsD

The Azure App Service extension includes an instance of DogStatsD (Datadog’s metrics aggregation service). This enables you to submit custom metrics, service checks, and events directly to Datadog from Azure Web Apps with the extension.

Writing custom metrics and checks in this environment is similar to the process for doing so with an application on a standard host running the Datadog Agent. To submit custom metrics to Datadog from Azure App Service using the extension:

1. Add the DogStatsD client to your project.
2. Initialize DogStatdD and write custom metrics in your application.
3. Deploy your code to a supported Azure web app.
4. Install the Datadog App Service extension.

Note: Unlike the standard DogStatsD config process, there is no need to set ports or a server name when initializing the DogStatsD configuration. There are ambient environment variables in Azure App Service that determine how the metrics are sent (requires v6.0.0+ of the DogStatsD client).

To send metrics use this code:

// Configure your DogStatsd client and configure any tags
StatsDClient client = new NonBlockingStatsDClientBuilder()
                            .constantTags(“app:sample.service”)
                            .build();
// Send a metric
client.Increment("sample.startup");

Learn more about custom metrics.

Datadog provides scripts to update or install the Azure App Service Extension using Powershell. Scripted extension management enables you to update extensions in bulk by resource group and designate the installation of specific versions of the site extension. You can also use scripts to programmatically add the extension in CI/CD pipelines, as well as discover and update extensions that are already installed.

Prerequisites

• The Azure CLI or Azure Cloud Shell.
• Azure App Service user-scope credentials. If you do not already have credentials, go to your Azure portal and access your Web App or Function App. Navigate to Deployment > Deployment Center to create or retrieve your user-scope credentials.

Installing the extension for the first time

The install script adds the latest version of the extension to an Azure Web App or Azure Function App. This occurs on a per-app basis, rather than at a resource group level.

1. Open the Azure CLI or Azure Cloud Shell.

2. Download the installation script using the following command:

   Invoke-WebRequest -Uri "https://raw.githubusercontent.com/DataDog/datadog-aas-extension/master/management-scripts/extension/install-latest-extension.ps1" -OutFile "install-latest-extension.ps1"
   

3. Run the following command, passing in required and optional arguments as needed.

   .\install-latest-extension.ps1 -Username <USERNAME> -Password <PASSWORD> -SubscriptionId <SUBSCRIPTION_ID> -ResourceGroup <RESOURCE_GROUP_NAME> -SiteName <SITE_NAME> -DDApiKey <DATADOG_API_KEY> -DDSite <DATADOG_SITE> -DDEnv <DATADOG_ENV> -DDService <DATADOG_SERVICE> -DDVersion <DATADOG_VERSION>
   

Note: The following arguments are required for the above command:

• <USERNAME>: Your Azure user scope username.
• <PASSWORD>: Your Azure user scope password.
• <SUBSCRIPTION_ID>: Your Azure subscription ID.
• <RESOURCE_GROUP_NAME>: Your Azure resource group name.
• <SITE_NAME>: The name of your app.
• <DATADOG_API_KEY>: Your Datadog API key.

Also, set DATADOG_SITE to your Datadog site. DATADOG_SITE defaults to datadoghq.com. Your site is: .

Updating the extension for a resource group

The update script applies to an entire resource group. This script updates every Web App or Function App that has the extension installed. App Service apps that do not have the Datadog extension installed are not affected.

1. Open the Azure CLI or Azure Cloud Shell.

2. Download the update script using the following command:

   $baseUri="https://raw.githubusercontent.com/DataDog/datadog-aas-extension/master/management-scripts/extension"; Invoke-WebRequest -Uri "$baseUri/update-all-site-extensions.ps1" -OutFile "update-all-site-extensions.ps1"; Invoke-WebRequest -Uri "$baseUri/install-latest-extension.ps1" -OutFile "install-latest-extension.ps1"
   

3. Run the following command. All arguments are required.

   .\update-all-site-extensions.ps1 -SubscriptionId <SUBSCRIPTION_ID> -ResourceGroup <RESOURCE_GROUP_NAME> -Username <USERNAME> -Password <PASSWORD>
   

Install a specific version of the extension

The Azure App Service UI does not support the ability to install a specific version of an extension. You may do this with the install or update script.

Install specific version on a single resource

To install a specific version on a single instance, follow the instructions for installing the extension for the first time and add the -ExtensionVersion parameter to the installation command.

.\install-latest-extension.ps1 -Username <USERNAME> -Password <PASSWORD> -SubscriptionId <SUBSCRIPTION_ID> -ResourceGroup <RESOURCE_GROUP_NAME> -SiteName <SITE_NAME> -DDApiKey <DATADOG_API_KEY> -ExtensionVersion <EXTENSION_VERSION>

Replace <EXTENSION_VERSION> with the version of the extension you wish to install. For instance, 1.4.0.

Install specific version on an entire resource group

To install a specific version for a resource group, follow the instructions for updating the extension for a resource group and add the -ExtensionVersion parameter to the installation command.

.\update-all-site-extensions.ps1 -SubscriptionId <SUBSCRIPTION_ID> -ResourceGroup <RESOURCE_GROUP_NAME> -Username <USERNAME> -Password <PASSWORD> -ExtensionVersion <EXTENSION_VERSION>

Replace <EXTENSION_VERSION> with the version of the extension you wish to install. For instance, 1.4.0.

ARM template

Many organizations use Azure Resource Management (ARM) templates to implement the practice of infrastructure-as-code. To build the App Service Extension into these templates, incorporate Datadog’s App Service Extension ARM template into your deployments to add the extension and configure it alongside your App Service resources.