Azure App Service - Windows Code

Overview

The Datadog extension for Azure App Service provides additional monitoring capabilities.

  • Full distributed APM tracing using automatic instrumentation.
  • Customized APM service and trace views showing relevant Azure App Service metrics and metadata.
  • Support for manual APM instrumentation to customize spans.
  • Trace_ID injection into application logs.
  • Support for submitting custom metrics using DogStatsD.
The extension supports Azure App Service Web Apps on Basic, Standard, and Premium plans. Flex or Consumption plans are not supported.

Interested in support for other App Service resource types or runtimes? Sign up to be notified when a Preview becomes available.

Supported runtimes

The Datadog .NET, Java, and Node.js APM extensions support the following runtimes in Windows Code web apps:

FrameworkSupported runtimes
.NETASPNET:V3.5, ASPNET:V4.8, dotnet:8, dotnet:9
JavaJAVA:8, JAVA:11, JAVA:17, JAVA:21, TOMCAT:9.0-java8, TOMCAT:9.0-java11, TOMCAT:9.0-java17, TOMCAT:9.0-java21, TOMCAT:10.1-java8, TOMCAT:10.1-java11, TOMCAT:10.1-java17, TOMCAT:10.1-java21, TOMCAT:11.0-java8, TOMCAT:11.0-java11, TOMCAT:11.0-java17, TOMCAT:11.0-java21
Node.jsNODE:20LTS, NODE:22LTS

Extension-specific notes

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.

Additionally, if you are using the Azure Native integration, you can use the Datadog resource in Azure to add the extension to your .NET apps. For instructions, see the App Service extension section of Datadog’s Azure Portal guide.

Support for Java Web Apps is in Preview for extension v2.4+.

There are no billing implications for tracing Java Web Apps during this period.

Installation

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.

  1. If you haven’t already, set up the Datadog-Azure integration.

  2. Verify that your Datadog-Azure integration is configured correctly by ensuring that you see the azure.app_services.count or azure.functions.count metrics in Datadog.

    This step is critical for metric/trace correlation, functional trace panel views, and improves the overall experience of using Datadog with Azure App Services.
  3. In your Azure Portal, navigate to the dashboard for the Azure app you wish to instrument with Datadog.

  4. Configure the following Application Settings:

    Required environment variables

    DD_API_KEY
    Value: Your Datadog API key.
    See Organization Settings > API Keys in Datadog.
    DD_SITE
    Value: Your Datadog site
    Your Datadog site. Defaults to datadoghq.com.

    Unified Service Tagging

    Datadog recommends tagging your application with the env, service, and version tags for unified service tagging.

    DD_SERVICE
    Value: Your application’s service name.
    DD_ENV
    Value: Your application’s environment name.
    There is no default value for this field.
    DD_VERSION
    Value: Your application’s version.
    There is no default value for this field.

    Additional environment variables

    DD_LOGS_INJECTION
    Value: true (recommended)
    Enables trace-log correlation by injecting trace IDs into your application logs.
    This allows you to correlate logs with traces in the Datadog UI.
  5. Click Save. This restarts your application.

  6. Stop your application by clicking Stop.

    You must stop your application to successfully install Datadog.
  7. In your Azure Portal, navigate to the Extensions page and select the Datadog APM extension.

    Example of Extensions page in Azure portal, showing .NET Datadog APM extension.
  8. Accept the legal terms, click OK, and wait for the installation to complete.

    This step requires that your application be in a stopped state.
  9. Start the main application, click Start:

    Azure start button
  10. Verify that the extension is installed and running by checking the Extensions page in your Azure Portal.

To avoid downtime, use deployment slots. You can create a workflow that uses the GitHub Action for Azure CLI. See the sample GitHub workflow.

Custom metrics

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. 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 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. If you have not already, install the Datadog App Service extension.

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");
  1. Add the DogStatsD client to your project.
  2. Initialize DogStatsD and write custom metrics in your application.
  3. Deploy your code to a supported Azure web app.
  4. If you have not already, install the Datadog App Service extension.

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");
  1. Initialize DogStatsD and write custom metrics in your application.
  2. Deploy your code to a supported Azure Web App.
  3. If you have not already, install Datadog’s Azure App Service Node.js extension.
You do not need to install a Node.js DogStatsD client, as it is included in the Node.js tracer (dd-trace) packaged in the Azure App Service extension.

To send metrics, use this code:

const tracer = require('dd-trace');
tracer.init();

tracer.dogstatsd.increment('example_metric.increment', 1, { environment: 'dev' });
tracer.dogstatsd.decrement('example_metric.decrement', 1, { environment: 'dev' });
Datadog's Node.js tracer, dd-trace, is packaged in the Azure App Services extension. It is automatically appended to the NODE_PATH.

You do not need to add dd-trace as a dependency in package.json. Explicitly adding dd-trace as a dependency may override the version provided by the extension. For local testing, reference the release notes to find the appropriate version of the Node.js tracer for your version of the Azure App Service extension.

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.

Logging

Application logging

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

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.

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.

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.


Environment variables for logging

Configure these environment variables in your Azure App Service Application Settings for optimal log collection:

VariableDescriptionExample
DD_SERVICEYour application’s service namemy-web-app
DD_ENVYour application’s environmentproduction, staging, development
DD_LOGS_INJECTIONEnable trace-log correlationtrue

Logging best practices

  • Enable trace correlation: Set DD_LOGS_INJECTION=true to correlate logs with traces
  • Set proper service names: Use DD_SERVICE to ensure logs appear with the correct service name
  • Use structured logging: Implement structured logging in your application for better log parsing

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.

Code Example: Microsoft Native Logging

An example of how to set up logging in a .NET application using Microsoft.Extensions.Logging:

using Microsoft.Extensions.Logging;

public class WeatherForecastController : ControllerBase
{
    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public IActionResult Get()
    {
        _logger.LogInformation("Processing weather forecast request");
        
        // Your business logic here
        var forecast = GetWeatherForecast();
        
        _logger.LogInformation("Weather forecast retrieved for user: {UserId}", userId);
        
        return Ok(forecast);
    }
}

Program.cs configuration

using Microsoft.Extensions.Logging;

var builder = WebApplication.CreateBuilder(args);

// Configure logging
builder.Logging.ClearProviders();
builder.Logging.AddConsole();
builder.Logging.AddDebug();

// Add structured logging with JSON format
builder.Logging.AddJsonConsole(options =>
{
    options.JsonWriterOptions = new JsonWriterOptions
    {
        Indented = true
    };
});

var app = builder.Build();
// ... rest of your application configuration

appsettings.json configuration

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    },
    "Console": {
      "FormatterName": "json",
      "FormatterOptions": {
        "IncludeScopes": true,
        "TimestampFormat": "yyyy-MM-dd HH:mm:ss "
      }
    }
  }
}

This setup automatically includes trace correlation when DD_LOGS_INJECTION=true is set in your Azure App Service Application Settings.

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

To configure application logging for Node.js in Azure App Service, see Agentless logging with Node.js.

Programmatic management

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

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.

Support for Java Web Apps is in Preview for extension v2.4+. Programmatic management is not available for Java Web Apps.

Interested in support for other App Service resource types or runtimes? Sign up to be notified when a Preview becomes available.

Deployment

To update your Datadog instrumentation with zero downtime, use deployment slots. You can create a workflow that uses GitHub Action for Azure CLI.

See the sample GitHub workflow.

Troubleshooting

If your apps are identified as being misconfigured in the Serverless View and/or you are missing corresponding metrics for your traces

It is likely that you do not have the Azure integration configured to monitor your application. Proper configuration improves your ability to correlate metrics, traces, and logs in the Datadog platform. Without the Azure integration configured, you are missing critical context for your traces. To fix this:

  1. Go to the Azure integration tile.

  2. Ensure you have installed the Azure integration for the Azure subscription where your application is running.

  3. Ensure that any App Service plan filtering rules you have applied include the App Service plan where the app is running. If an App Service plan is not included, all apps and functions hosted on it are also not included. Tags on the app itself are not used for filtering by Datadog.

If APM traces are not appearing in Datadog

  1. Verify you’ve set DD_SITE and DD_API_KEY correctly.

  2. Do a full stop and start of your application.

  3. If not resolved, try uninstalling the extension and re-installing (this also ensures you are running the latest version).

Note: To expedite the process of investigating application errors with the support team, set DD_TRACE_DEBUG:true and add the content of the Datadog logs directory (%AzureAppServiceHomeDirectory%\LogFiles\datadog) to your email.

Still need help? Contact Datadog support.

Further Reading