Skip to content

How to enable profiler codelessly

Jump to bottom
Saar Shen edited this page Jul 16, 2026 · 1 revision

Enable the profiler codelessly using the site extension (Windows App Service)

The Azure Monitor Profiler site extension lets you enable the profiler on a Windows App Service without changing your application's source code, adding a NuGet package, or recompiling. Once installed, the profiler attaches automatically when your app starts, captures traces, and uploads them to Application Insights.

Beta. This is a public beta of codeless profiler enablement. See Known limitations below.

How it works (in brief)

The site extension stages a small payload alongside your app and injects a few .NET environment variables into the worker process. On startup, the profiler:

  1. Detects which telemetry stack your app uses (OpenTelemetry or classic Application Insights) by scanning your app's own *.deps.json.
  2. Enables the matching profiler automatically.
  3. Uploads captured traces to the Application Insights resource named by your app's connection string.

Enablement is fail-safe: if anything is misconfigured or incompatible, the profiler disables itself and your application keeps running — it will not crash your app.

Prerequisites

  • A Windows App Service running a .NET / ASP.NET Core app (.NET 8, 9, or 10).

  • The app has an Application Insights connection string set. In the Azure portal: App Service → Settings → Environment variables → App settings, add or confirm:

    APPLICATIONINSIGHTS_CONNECTION_STRING = <your connection string>

  • Your app uses a supported telemetry stack:

    • OpenTelemetry (Azure.Monitor.OpenTelemetry.AspNetCore, or Microsoft.ApplicationInsights.AspNetCore 3.x, or manual OpenTelemetry), or
    • Classic Application Insights SDK ≥ 2.23.0 and < 3.0.0.

If your app already references a profiler NuGet (Azure.Monitor.OpenTelemetry.Profiler or Microsoft.ApplicationInsights.Profiler.AspNetCore), the site extension backs off automatically to avoid enabling the profiler twice.

Install the site extension

  1. In the Azure portal, open your App Service.
  2. In the left menu, select Extensions.
  3. Select + Add.
  4. Choose Azure Monitor OpenTelemetry Profiler from the list.
  5. Accept the legal terms and select OK to install.
  6. When the install completes, restart the app so the worker process picks up the injected environment variables.

That's it — the profiler now activates codelessly every time the app starts.

Verify it's working

  • Application Insights: After the app has taken some traffic, open your Application Insights resource and go to Investigate → Performance → Profiler (or the Profiler blade). Captured traces appear here within a few minutes.

  • Startup log (optional): Enable startup logging (see How to diagnose codeless startup) and look for lines such as:

    [Azure.Monitor.OpenTelemetry.Profiler.StartupHook] Detected telemetry stack: OpenTelemetry
[Azure.Monitor.OpenTelemetry.Profiler.HostingStartup] info: Enabling the Azure Monitor OpenTelemetry profiler.

Troubleshooting

If traces don't appear, or you want to confirm the profiler activated, enable startup logging and check the log. See How to diagnose codeless startup for the full steps.

Upgrade and uninstall

  • Upgrade: Install the newer version from the Extensions blade, then restart the app. The payload is staged in a version-stamped folder, so upgrades don't collide with files still in use by a running worker.
  • Uninstall: Remove the extension from the Extensions blade and restart the app. The injected environment variables are cleaned up so the profiler no longer activates.

Known limitations

  • .NET apps only. On non-.NET stacks (Node.js, Python, Java, PHP) the extension is a safe no-op — nothing is enabled and nothing breaks.
  • Windows App Service only for the site extension. For Linux App Service (blessed .NET stack), use the enable script instead of a site extension.
  • Runtime support: .NET 8, 9, and 10.
  • Minimum app dependency versions: for OpenTelemetry apps, OpenTelemetry must be ≥ 1.8.1 and Azure.Core ≥ 1.46.1. For classic apps, the Application Insights SDK must be ≥ 2.23.0 and < 3.0.0. Apps below these floors are unsupported; the profiler disables itself rather than risking the app.
  • A valid connection string is required. With a missing or invalid APPLICATIONINSIGHTS_CONNECTION_STRING, the profiler disables itself (logged), but your app keeps running.

Related

Clone this wiki locally