Skip to content

Enable with manual OpenTelemetry setup

Jump to bottom
Saar Shen edited this page Aug 13, 2026 · 1 revision

Enable the profiler with a manual OpenTelemetry setup

You do not have to use the Azure Monitor OpenTelemetry distro (UseAzureMonitor()) to run the profiler. If you configure OpenTelemetry yourself — for example because you switch exporters per environment, register your own ActivitySources, or customize sampling — you can still enable the profiler with a single call.

This is the scenario from issue #20.

Prerequisites

In addition to the Get Started prerequisites, you only need the profiler package:

dotnet add package Azure.Monitor.OpenTelemetry.Profiler --prerelease

You do not need Azure.Monitor.OpenTelemetry.AspNetCore. The profiler depends on Azure.Monitor.OpenTelemetry.Exporter only, so it composes with a hand-rolled OpenTelemetry pipeline.

Walkthrough

Call AddAzureMonitorProfiler() on the builder returned by AddOpenTelemetry(), after your own tracing configuration:

using Azure.Monitor.OpenTelemetry.Profiler;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("my-service"))
    .WithTracing(tracerProviderBuilder =>
    {
        tracerProviderBuilder
            .AddAspNetCoreInstrumentation()
            .AddSource("MyCompany.MyProduct");

        if (useAzureMonitor)
        {
            tracerProviderBuilder.AddAzureMonitorTraceExporter();
        }
        else
        {
            // For example, the Aspire Dashboard during local development.
            tracerProviderBuilder.AddOtlpExporter();
        }
    })
    .AddAzureMonitorProfiler();   // Enable the profiler

Enabling the profiler conditionally

AddAzureMonitorProfiler() is a plain registration call, so you can gate it on the same flag that selects your exporter. Both an IOpenTelemetryBuilder and an IServiceCollection overload exist:

var otelBuilder = builder.Services.AddOpenTelemetry()
    .ConfigureResource(...)
    .WithTracing(...);

if (useAzureMonitor)
{
    otelBuilder.AddAzureMonitorProfiler();
}

// Equivalent, when you only have the IServiceCollection at hand:
// if (useAzureMonitor) builder.Services.AddAzureMonitorProfiler();

Calling it more than once is safe — registration is skipped if the profiler services are already present.

What the profiler still needs

Skipping UseAzureMonitor() does not leave anything unconfigured for the profiler, but two inputs are worth knowing about.

Connection string

The profiler always needs an Application Insights connection string. It resolves one in this order, taking the first non-empty value:

  1. The ServiceProfiler:ConnectionString configuration section (for example from appsettings.json or environment variables — see the Configuration Guide).
  2. AzureMonitorExporterOptions.ConnectionString — this is populated for you if you call AddAzureMonitorTraceExporter(), with or without the distro.
  3. The APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.

If none of these is set, the profiler disables itself and logs an actionable error at startup rather than failing your application.

Note: the Azure Monitor exporter itself also requires a connection string and will throw during startup if one is missing. That failure comes from the exporter, not the profiler.

Cloud role name and role instance

The profiler reads the cloud role name, role instance, and application version from the OpenTelemetry Resource (service.name, service.instance.id, and service.version), so the standard ConfigureResource(r => r.AddService(...)) call — or the OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES environment variables — is all you need. See Setup the Role name for details and fallbacks.

Note on UseProfiler()

Older guidance (including comments on issue #20) suggested a TracerProviderBuilder.UseProfiler() extension method. That method no longer exists. Use AddAzureMonitorProfiler() on IOpenTelemetryBuilder or IServiceCollection as shown above.

See also

Clone this wiki locally