diff --git a/docs/migration/guide_aspnet.md b/docs/migration/guide_aspnet.md new file mode 100644 index 0000000000..cd0ccc700d --- /dev/null +++ b/docs/migration/guide_aspnet.md @@ -0,0 +1,102 @@ +# Guide for Asp.Net applications + +## Intro + +The following guide details how to migrate from Application Insights SDK to OpenTelemetry based solution for an ASP.NET web application. + +## Prerequisites + +- An ASP.NET web application already instrumented with Application Insights +- A actively supported version of .NET (link) + +## Steps to Migrate + +### Step 1: Remove Application Insights SDK + +When you first added ApplicationInsights to your project, the SDK would have added a config file and made some edits to the web.config. +If using Nuget tools to remove the Application Insights, some of this will be cleaned up. +If you're manually removing the package reference from your csproj, you'll need to manually cleanup these artifacts. + +- Remove any Microsoft.ApplicationInsights.* packages from you csproj and packages.config. +- Delete the ApplicationInsights.config file. +- Clean up your application's Web.Config file. + + The following sections would have been automatically added to your web.config when you first added ApplicationInsights to your project. References to the `TelemetryCorrelationHttpModule` and the `ApplicationInsightsWebTracking` should be removed. + + ```xml + + + + + + + + + + + + + + + + + ``` + +### Step 1: Install the OpenTelemetry SDK and Enable at Application Startup + +The OpenTelemery SDK must be configured at application startup. This is typically done in the `Global.asax.cs`. +OpenTelemetry has a concept of three signals; Traces (Requests and Dependencies), Metrics, and Logs. +Each of these signals will need to be configured as part of your application startup. + +#### Global.asax.cs + +TODO: NEED A SAMPLE THAT INCLUDES LOGGING. + +```csharp +using OpenTelemetry; +using OpenTelemetry.Metrics; +using OpenTelemetry.Trace; + +public class MvcApplication : System.Web.HttpApplication +{ + private TracerProvider? tracerProvider; + private MeterProvider? meterProvider; + + protected void Application_Start() + { + this.tracerProvider = Sdk.CreateTracerProviderBuilder() + .Build(); + + this.meterProvider = Sdk.CreateMeterProviderBuilder() + .Build(); + } + + protected void Application_End() + { + this.tracerProvider?.Dispose(); + this.meterProvider?.Dispose(); + } +} +``` + +For more examples, see the following guides: +- OpenTelemetry SDK's getting started guide: https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry +- ASP.NET example project: https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/examples/AspNet/Global.asax.cs + +### Step 1: Configure Instrumentation Libraries. + +Instrumentation libraries can be added to your project to auto collect telemetry about specific components or dependencies. + +- To collect telemetry for incoming requests, you should add the [OpenTelemetry.Instrumentation.AspNet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet) library to your application. +This includes adding a new reference to your Web.config and adding the Instrumentation to your OpenTelemetry SDK configuration. +A getting started guide is available here: https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet + +- To collect telemetry for outbound http dependencies, you should add the [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) library to your application. +A getting started guide is available here: https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Instrumentation.Http + +### Step 1: Configure the Azure Monitor Exporter + +To send your telemetry to Application Insights, the Azure Monitor Exporter must be added to the configuration of all three signals. + +See this doc for our getting started guide: +https://learn.microsoft.com/en-us/azure/azure-monitor/app/opentelemetry-enable?tabs=net