enable-profiler

name	enable-profiler
category	setup
description	Guide users through enabling the Application Insights Profiler for .NET on their platform. Use this when asked to enable the profiler, set up profiling, or when profiler data is missing.

Enable Application Insights Profiler

When asked to enable the Application Insights Profiler for .NET, or when another skill (e.g., perf-optimization) determines that no profiler data exists, follow these steps:

1. Check investigation notes and gather inputs — Follow the Standard Skill Preamble to check for existing investigation context and gather inputs.

2. Identify the Application Insights resource — If the investigation notes didn't have the resource or the user wants a different one, follow the steps in the Standard Skill Preamble. After the resource is confirmed, write or update investigation-notes.md with the confirmed values. If only a resource ID is available, resolve the app ID using resolve-app-id.md.

3. Check if the profiler is already active — Run the script in check-profiler-status.md to query for both ServiceProfilerIndex (session-level) and ServiceProfilerSample (request-level) events.

   • If both event types are found → the profiler is already enabled and capturing request data — confirm the data belongs to the target app before concluding (see the caveat below), then inform the user and stop.
   • If only ServiceProfilerIndex events exist (no ServiceProfilerSample) → the profiler IS running but is not capturing request-level samples. Apply the shared-resource caveat below first — if the index events belong to a different cloud_RoleName, treat the profiler as NOT enabled for this app and proceed to step 4. If the events do belong to the target app, this is typically a traffic or trigger issue, not an enablement issue. Inform the user the profiler is enabled, and suggest checking traffic volume and trigger thresholds rather than re-enabling.
   • If neither event type is found → the profiler is not enabled. Proceed to step 4.

   ⚠️ Shared-resource caveat — avoid false positives. A single Application Insights resource can receive telemetry from multiple apps / cloud roles. If the App ID was inferred (e.g., read from a connection string in local.settings.json or appsettings.json) rather than explicitly confirmed by the user, profiler events on that resource may belong to a different app. Before concluding "already enabled", break the events down by cloud_RoleName (the status script does this) and confirm with the user that the role producing profiler data is the app you are enabling. If it is a different role — or the target role shows zero profiler events — treat the profiler as NOT enabled for this app and proceed to step 4.

4. Check local source code for existing profiler configuration — Before asking the user environment questions, inspect the source code in the working directory to determine whether the profiler is already configured in code and whether the connection string matches the target resource.

   4a. Check for profiler NuGet packages and code:

   • Search *.csproj files for profiler NuGet references:
     • Microsoft.ApplicationInsights.Profiler.AspNetCore (classic SDK / EventPipe)
     • Azure.Monitor.OpenTelemetry.Profiler (OpenTelemetry / EventPipe)
   • Search Program.cs or Startup.cs for profiler registration calls:
     • AddServiceProfiler (classic SDK)
     • AddAzureMonitorProfiler (OpenTelemetry)

   4b. If profiler code IS present — run connection string match check: The profiler is configured in code but producing no events on the target resource. A common cause is a connection string mismatch — the app may be sending data to a different App Insights resource. Run check-connection-string-match.md to compare the app's configured connection string against the target resource.

   • If a mismatch is detected → present it to the user as a possible explanation (see the troubleshooting guidance in check-connection-string-match.md). Note that connection strings are often overridden at deployment time, so a source-code mismatch does not necessarily mean the app is sending data elsewhere. Ask the user to confirm which scenario applies before deciding next steps. Do not proceed with enablement steps until the mismatch is resolved or confirmed as a non-issue.
   • If connection strings match → the profiler is configured and pointing to the correct resource, but not producing data for another reason. Continue to step 5.
   • If no connection strings are found locally → the app's connection string may be set via environment variables, App Service configuration, or CI/CD at deployment time. Cannot verify from source code alone. Continue to step 5 and consider asking the user how the connection string is configured.

   4c. Infer environment from source code: When source code is available, attempt to infer the answers to the environment questions below before asking them. This avoids redundant questions when the answers are already visible:

   • Runtime: Check in — values like , , , indicate .NET (modern); , indicate .NET Framework.

5. Determine the user's environment — Ask the user any questions not already answered by source code inspection in step 4 (use multiple-choice where possible):

   Question 1 (if runtime not inferred): What .NET runtime does your application target?

   • .NET (modern) — .NET 6, .NET 8, or later
   • .NET Framework — .NET Framework 4.x

   Question 2 (if hosting not inferred): Where is your application hosted?

   • Azure App Service (Windows)
   • Azure App Service (Linux)
   • Containers (AKS, Container Apps, Container Instances)
   • Azure Functions (App Service plan)
   • Azure Virtual Machines or Virtual Machine Scale Sets
   • Azure Service Fabric
   • Other / not sure

   Question 2b (if Azure Functions selected and worker model not inferred): Which Azure Functions worker model are you using?

   • In-process (FUNCTIONS_WORKER_RUNTIME = dotnet)
   • Isolated worker (FUNCTIONS_WORKER_RUNTIME = dotnet-isolated)
   • Not sure

   This determines the profiler agent: in-process uses ETW (no code change), isolated worker uses EventPipe (code change required). If the user is unsure, check local.settings.json or the Azure portal Function App configuration for FUNCTIONS_WORKER_RUNTIME.

   Question 3 (if SDK not inferred, and .NET modern with EventPipe applicable): Which Application Insights SDK are you using?

   • Azure Monitor OpenTelemetry distribution (Azure.Monitor.OpenTelemetry.AspNetCore)
   • Classic Application Insights SDK (Microsoft.ApplicationInsights.AspNetCore)
   • Not sure / not set up yet

6. Select the profiler agent and provide enablement instructions — Based on the user's answers (or inferred values from step 4), determine the correct profiler agent and fetch the relevant enablement documentation.

   Selecting the profiler agent

   First, determine the correct agent using the selection guide. Fetch online first, fall back to local:

   • Try: web_fetch with URL https://github.com/Azure/azuremonitor-opentelemetry-profiler-net/blob/main/docs/ProfilerAgentSelectionGuide.md and max_length: 5000
   • If fetch fails: read profiler-agent-selection-guide.md

   Apply the decision tree:

   .NET Runtime	Hosting	Profiler Agent	Code Change Required?
   .NET Framework	Any Windows Azure service	ETW	No
   .NET (modern)	App Service (Windows)	ETW (simplest) or EventPipe	No for ETW; Yes for EventPipe
   .NET (modern)	App Service (Linux)	EventPipe	Yes
   .NET (modern)	Containers (AKS, Container Apps, ACI)	EventPipe	Yes
   .NET (modern)	Azure Functions — in-process (classic AI SDK), App Service plan	ETW	No
   .NET (modern)	Azure Functions — isolated worker and/or OpenTelemetry	EventPipe	Yes
   .NET (modern)	VMs / VMSS	ETW or EventPipe	No for ETW; Yes for EventPipe
   .NET (modern)	Service Fabric	ETW	No

   ⚠️ Do NOT use both ETW and EventPipe at the same time — the combined overhead is not recommended.

   Azure Functions note. The ETW (no-code) Functions profiler attaches to the classic in-process Application Insights pipeline. An Functions app — especially one configured for (, ) — does not use that pipeline, so ETW may not produce profiler data for the worker process. In this case, use the profiler in code: add and chain onto the Functions OTel builder (e.g. ). The profiler reads the connection string from , so no extra wiring is needed when that is already set.

7. Verify the profiler is producing data — After the user has enabled the profiler and generated some traffic, re-run the check-profiler-status.md script to confirm profiler events are appearing. The profiler typically takes 2–5 minutes to start producing traces after enablement.

   • If both ServiceProfilerIndex and ServiceProfilerSample events are found → apply the shared-resource caveat from step 3: confirm the events' cloud_RoleName belongs to the target app before declaring success. If confirmed, the profiler is capturing request-level data — full success.
   • If only ServiceProfilerIndex events appear → confirm cloud_RoleName matches the target app. If it does, the profiler is running sessions but not capturing individual requests. This is normal if traffic is low — suggest the user generate more traffic and wait for the next profiling window. If the events belong to a different role, treat as not yet producing data for this app.
   • If no events appear after the expected wait time, suggest troubleshooting:
   • Verify the connection string is correct
   • Check the application logs for profiler startup messages
   • Ensure there is traffic hitting the application
   • For EventPipe: enable debug logging by setting log level for Microsoft.ServiceProfiler and Microsoft.ApplicationInsights.Profiler to Debug

   Once both event types are confirmed, suggest the user re-run the perf-optimization skill to investigate performance issues with the now-available profiler data. For distributed systems with multiple services, also suggest running discover-related-resources.md to map all related App Insights resources before starting analysis — this ensures profiler data and telemetry from downstream components are included in the investigation.

Key facts

• The profiler adds 5–15% CPU/memory overhead when actively collecting traces (default: 30s every hour)
• Profiler data is automatically deleted after 15 days
• Only one profiler can be attached per web app
• Code Optimizations and hot path analysis both depend on profiler data — without it, these features return no results

References

• Profiler Agent Selection Guide
• Enablement Overview
• Check Profiler Status
• Investigation Notes
• resolve-app-id.md
• az CLI Query Pitfalls