Note: this is part 2 of a series on the Azure Monitor Profiler. Part 1 covered what the Profiler is and where to find the results - this post covers actually turning it on.
There are two ways to enable the profiler: through app settings on App Service, or by wiring it into your code directly. Which one you need depends on where your app runs and how much control you want over the setup.
Option 1: codeless enablement on App Service
If your app runs on App Service (Windows) and your Application Insights resource is in the same subscription, this is the easiest path - no code changes, no redeploy.
From the portal:
- In your App Service instance, select Monitoring > Application Insights
- Select Turn on Application Insights, then Enable
- Scroll down to the .NET or .NET Core tab
- Set Collection level to Recommended
- Under Profiler and Code Optimizations, select On
- Apply, then confirm with Yes
Or skip the portal entirely and set the app settings directly:
az webapp config appsettings set \ --resource-group myRG \ --name myWebApp \ --settings \ APPLICATIONINSIGHTS_CONNECTION_STRING="<your-connection-string>" \ APPINSIGHTS_PROFILERFEATURE_VERSION=1.0.0 \ DiagnosticServices_EXTENSION_VERSION=~3
Remark: if your Application Insights resource lives in a different subscription than your App Service, the portal wizard above won't be available to you, and you'll need to fall back to setting these app settings manually. Same three settings, just no guided flow.
Once the settings are in, the profiler runs as a continuous WebJob on the app. If you want to confirm it's actually running rather than waiting for traces to show up:
- Go to WebJobs in the left menu
- Check the status of
ApplicationInsightsProfiler3- it should read Running. If it isn't, the WebJob logs are the first place to look.
Option 2: package-based setup in code
Not on App Service, or you want the Profiler configured as part of your app startup rather than as portal/infra config?
Install it as a package instead, using the Azure Monitor OpenTelemetry Distro, which is the current recommended path over the classic Application Insights SDK:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
dotnet add package Azure.Monitor.OpenTelemetry.Profiler --prereleaseThen enable it alongside your existing OpenTelemetry setup:
using Azure.Monitor.OpenTelemetry.AspNetCore;
using Azure.Monitor.OpenTelemetry.Profiler;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
.UseAzureMonitor() // Enable the Azure Monitor OpenTelemetry Distro
.AddAzureMonitorProfiler(); // Add the Profiler
var app = builder.Build();
app.MapControllers();
app.Run();UseAzureMonitor() reads the connection string from the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable by default, or you can set it explicitly with UseAzureMonitor(o => o.ConnectionString = "...").
Remark: the Azure.Monitor.OpenTelemetry.Profiler package is still in prerelease, hence the --prerelease flag on the install. If you're already on the classic Microsoft.ApplicationInsights.AspNetCore SDK, note that its current major version is itself an OpenTelemetry-based wrapper under the hood - so if you're not ready to move to the Distro yet, AddServiceProfiler() from Microsoft.ApplicationInsights.Profiler.AspNetCore still works against it without adding the Distro package. The two aren't meant to be combined.
This gets you the same Profiler agent as option 1, just wired up via the OpenTelemetry-based SDK instead of the classic one - the difference is you're now explicit about it in code, which matters if you're running in containers, on Linux, or just prefer configuration-as-code over portal toggles.
Configuring the profiler once it's installed
AddAzureMonitorProfiler() with no arguments gets you the defaults, and the defaults are reasonable for getting started. But once you're running this in a real environment, you'll likely want to tune it - and there are three ways to do that, all pointing at the same underlying settings.
1. appsettings.json
All Profiler settings live under a ServiceProfiler section:
{
"ServiceProfiler": {
"Duration": "00:00:30",
"InitialDelay": "00:00:03"
}
}2. Environment variables
Same settings, using __ (double underscore) to separate the section from the key - useful for container deployments where you're injecting config through the environment rather than a file:
export ServiceProfiler__Duration="00:00:30"3. Directly in code
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
.UseAzureMonitor()
.AddAzureMonitorProfiler(options =>
{
options.Duration = TimeSpan.FromSeconds(30);
options.InitialDelay = TimeSpan.FromSeconds(3);
});All three are equivalent - standard ASP.NET Core configuration binding applies, so pick whichever fits how you already manage config in your project.
Remark: don't confuse the ServiceProfiler section with the ApplicationInsights section. Your instrumentation key or connection string still goes under ApplicationInsights - ServiceProfiler is exclusively for tuning the Profiler agent itself.
The options worth knowing about:
| Setting | Default | What it does |
Duration |
30 seconds | How long a profiling session runs |
InitialDelay |
0 | Delay before the first session starts after app startup |
BufferSizeInMB |
250 | Circular buffer size for trace data - a 2-minute session usually produces under 200MB, so raise this if you extend Duration |
CPUTriggerThreshold |
80.0 | CPU usage percentage that triggers a session if sustained for 30+ seconds |
MemoryTriggerThreshold |
80.0 | Same idea, for memory usage |
IsDisabled |
false | Kill switch - flip this per-environment instead of removing the package, e.g. to keep the Profiler out of Development |
UploadMode |
OnSuccess | Never, OnSuccess, or Always - mainly useful for debugging the Profiler itself, not something you'd normally touch |
PreserveTraceFile |
false | Keep the local trace file after upload instead of deleting it |
ConfigurationUpdateFrequency |
5 seconds | How often the agent polls the server for trigger/on-demand config changes |
The two I'd actually reach for in practice are CPUTriggerThreshold / MemoryTriggerThreshold and IsDisabled. The trigger thresholds let the Profiler kick in automatically when something's actually under pressure, rather than relying purely on the random sampling window - which matters if your problem is intermittent. And IsDisabled bound to an environment variable is the cleanest way to keep the Profiler off in local development without maintaining a separate code path.
Remark: One constraint worth knowing before you start: codeless enablement on App Service currently only supports Windows. If you're on Linux App Service or containers, the package-based route in option 2 is your path.
What’s next?
Now that we have the profiling up-and-running, it’s time to interpret the results. But we'll leave that for the next post where I explain how to read a flame graph without guessing. We'll take one of the traces this setup produces and actually making sense of it.
Stay tuned!