Deprecating TelemetryConfiguration.Active singleton

[lmolkova]

With ApplicationInsights SDK 2.11-beta1 we are deprecating TelemetryConfiguration.Active on .NET core apps, see #1148.

ApplicationInsights exposes TelemetryConfiguration.Active singleton to enable auto-configuration scenarios in the absence of a dependency injection framework.

It is used on ASP.NET Classic apps (in Microsoft.ApplicationInsights.Web SDK). The configuration is read from the ApplicationInsights.config file by auto-collectors when an application starts.
User can access configuration that is used by auto-collectors and is able to customize it.

It is not the case for ASP.NET Core application where Dependency Injection is part of the framework - ApplicationInsights configuration is done and could be accessed and customized through DI container. The details and examples could be found here; https://docs.microsoft.com/en-us/azure/azure-monitor/app/asp-net-core

Active singleton creates issues typical for static singletons - lifetime it tight to process, testing is complicated. This is especially problematic in ASP.NET core apps, Azure WebJobs, and generic host apps, where one process may host multiple applications. So there ApplicationInsights SDK configures an instance of TelemetryConfiguration per host. It frequently results in confusion around which instance of configuration to use: one in the DI container or Active.

• If you use ApplicationInsights SDK for ASP.NET Core apps - follow this document for guidance on how to configure AppInsights: https://docs.microsoft.com/en-us/azure/azure-monitor/app/asp-net-core

• If you use AzureFunctions v2+ or Azure WebJobs v3+ - follow this document: https://docs.microsoft.com/en-us/azure/azure-functions/functions-monitoring#version-2x-3

• If you have other kind of application where you configure TelemetryConfiguration yourself - do not use TelemetryConfiguration.Active singleton.
  You should create configuration instance and may carry it explicitly in your code, leverage DI from Microsoft.Extensions.DependencyInjection or any other available DI framework or even create your own global static variable to store TelemetryConfiguration instance you create.

[macrogreg]

@lmolkova In the context of this change, what is the recommended replacement for the popular pattern of creating an instance of TelemetryClient via the parameter-less ctor at multiple places, instead of carrying around an instance?
Will TelemetryClient() use something other than TelemetryConfiguration.Active?
If so - what? If not - what is the recommendation? I was that doing

var client = TelemetryClient();
client.TrackStuff(..);

at multiple places is a very common usage pattern.

Thanks!

[lmolkova]

[EDITED]
In console apps, where ApplicationInsights SDK or AppInsights ILogger provider are used, get TelemetryConfiguration instance from the DI container and create TelemetryClient whenever you want.

Check out how you can customize configuration for ILogger provider and ASP.NET Core SDK

When building container yourself, you decide how to customize the configuration and register it in the container. The baseline: you can just register TelemetryConfiguration instance and still use dependency injection to resolve it. Pay attention to nuances like

• when registering an instance without a factory, an instance is not disposed with the host, so always use factories to register disposable instances
• use services.Configure<TelemetryConfiguration>, but be careful with correlation and add OperationCorrelationTelemetryInitializer to ensure correlation still works:

  services.Configure<TelemetryConfiguration>(
     (o) => {
       o.InstrumentationKey = "123";
       o.TelemetryInitializers.Add(new OperationCorrelationTelemetryInitializer());
     });

If you don't want to use DI, and have pure console app, create config once and pass it around however you want.

When creating configuration instance yourself, use TelemetryConfiguration.CreateDefault() and not the parameterless constructor (to enable correlation):

var config = TelemetryConfiguration.CreateDefault();
var client = new TelemetryClient(config);

Keep one TelemetryConfiguration per app lifetime (a few is also fine), but you may create as many clients as you want.
Do not forget to dispose TelemetryConfiguration when gracefully shutting down the application.

[pharring]

I think we advise using IOptions<TelemetryConfiguration> instead of a raw TelemetryConfiguration instance. At least that's what you get with the ILogger extension.

If building the DI container yourself, of course you're free to do whatever you want, but I think we prefer services.Configure<TelemetryConfiguration>(...) over services.AddSingleton<TelemetryConfiguration>(...).

[lmolkova]

yes, thanks for the clarification, @pharring, update comment above

[bjornharrtell]

I've used TelemetryConfiguration.Active to programmatically configure the configuration used with Microsoft.ApplicationInsights.NLogTarget. From the above information, it's not clear to me what the rewrite strategy should be in the case of Microsoft.ApplicationInsights.NLogTarget.