Documentation fixes and restructuring (#3079)

* fixng inaccuracies & restructuring documentation

* minor

* toc fix

* remove changes from examples

* copilot comments

* comments

---------

Co-authored-by: Rajkumar Rangaraj <rajrang@microsoft.com>

Author: harsimar

BASE/README.md

@@ -106,11 +106,13 @@ This applies to all dimension combinations (1D, 2D, 3D, 4D).
 - ❌ `TelemetryConfiguration(string instrumentationKey)`
 - ❌ `TelemetryConfiguration(string instrumentationKey, ITelemetryChannel channel)`
 
+#### Methods
+- ❌ **`CreateFromConfiguration(string config)`** - Static method that created a TelemetryConfiguration from XML configuration string. Use `CreateDefault()` or the parameterless constructor and set properties directly.
+
 ### Properties with Changed Behavior
 - ✅ **`ConnectionString`** - Still exists but behavior differs
   - **2.x**: String property
   - **3.x**: Setting this calls OpenTelemetry configuration internally
-- ✅ **`DisableTelemetry`** - Still exists but does not disable flow of telemetry (will be fixed later)
 
 ### Methods with changed Behavior
 - CreateDefault() returns an internal static configuration instead of a new TelemetryConfiguration()
@@ -139,11 +141,8 @@ Most TelemetryContext modules have now been marked internal or removed. The prop
 ### Properties Retained
 
 The following remain **public**:
-- ✅ `Cloud` (RoleName, RoleInstance)
-    - Note: These are settable via resource attributes (service.name & service.instance.id) in OpenTelemetry; we are working on fixing functionality for setting the same via CloudContext.
 - ✅ `User` (Id, AuthenticatedUserId, UserAgent)
-- ✅ `Operation` (Name, SyntheticSource)
-    - Note: A future work item is to make sure SyntheticSource can be read from properly and emitted in the telemetry item.
+- ✅ `Operation` (Name)
 - ✅ `Location` (Ip)
 - ✅ `GlobalProperties`
 
@@ -197,6 +196,11 @@ The following extension methods remain with identical signatures:
 - ❌ **`ExceptionTrackingMiddleware`** - Middleware class removed
 - ❌ **`HostingDiagnosticListener`** - Diagnostic listener removed
 - ❌ **`HostingStartupOptions`** - Configuration class removed
+- ❌ **`Resources`** - Internal resource class removed from public API
+  - `Resources.Culture` (get/set)
+  - `Resources.JavaScriptAuthSnippet` (get)
+  - `Resources.JavaScriptSnippet` (get)
+  - `Resources.ResourceManager` (get)
 
 ### TelemetryInitializers Removed (All 7)
 - ❌ `AspNetCoreEnvironmentTelemetryInitializer`
@@ -218,13 +222,13 @@ The following extension methods remain with identical signatures:
 - ❌ **`RequestCollectionOptions`** - Removed (non-functional, use OpenTelemetry instrumentation options)
 - ❌ **`DependencyCollectionOptions`** - Removed (non-functional, use OpenTelemetry instrumentation options)
 - ❌ `EnableAdaptiveSampling`** - Removed, rate limited sampling is now the default.
+- ❌ **`EnableDebugLogger`** - Removed
 
 ### Properties Retained
 - ✅ **`ConnectionString`** - Primary configuration method
 - ✅ **`ApplicationVersion`**
 - ✅ **`AddAutoCollectedMetricExtractor`**
 - ✅ **`EnableQuickPulseMetricStream`** 
-- ✅ **`EnableDebugLogger`** - Retained but has no effect
 - ✅ **`EnableAuthenticationTrackingJavaScript`** - JavaScript auth tracking config
 - ✅ **`EnableDependencyTrackingTelemetryModule`** - Dependency tracking toggle
 - ✅ **`EnablePerformanceCounterCollectionModule`** - Performance counter toggle
@@ -234,6 +238,7 @@ The following extension methods remain with identical signatures:
 - ✅ **`Credential`** (Azure.Core.TokenCredential) - Enables Azure Active Directory (AAD) authentication
 - ✅ **`TracesPerSecond`** (double?) - Gets or sets the number of traces per second for rate-limited sampling (default sampling mode). Replaces `EnableAdaptiveSampling`.
 - ✅ **`SamplingRatio`** (float?) - Gets or sets the sampling ratio for traces (0.0 to 1.0). A value of 1.0 means all telemetry is sent. Replaces `EnableAdaptiveSampling`.
+- ✅ **`EnableTraceBasedLogsSampler`** (bool?) - Gets or sets whether trace-based log sampling is enabled (default: true). When enabled, logs are sampled based on the sampling decision of the associated trace.
 
 ### JavaScriptSnippet Constructor Change
 **2.x:**
@@ -286,20 +291,21 @@ The following extension methods remain with identical signatures:
 - ❌ **`EndpointAddress`** - No longer configurable (`ConnectionString` contains endpoints)
 - ❌ **`DependencyCollectionOptions`** - Removed (non-functional, use OpenTelemetry instrumentation options)
 - ❌ **`EnableAdaptiveSampling`** - Removed, rate limited sampling is now the default.
+- ❌ **`EnableDebugLogger`** - Removed
 
 ### Properties Retained
 - ✅ **`ConnectionString`** - Primary configuration method (maps to `AzureMonitorExporterOptions.ConnectionString`)
 - ✅ **`ApplicationVersion`** - Still configurable
 - ✅ **`EnableDependencyTrackingTelemetryModule`** - Still configurable
 - ✅ **`EnablePerformanceCounterCollectionModule`** - Still configurable
 - ✅ **`EnableQuickPulseMetricStream`** - Maps to `AzureMonitorExporterOptions.EnableLiveMetrics`
-- ✅ **`EnableDebugLogger`** - Still configurable though has no effect
 - ✅ **`AddAutoCollectedMetricExtractor`** - Still configurable
 
 ### New Properties Added in 3.x
 - ✅ **`Credential`** (Azure.Core.TokenCredential) - Enables Azure Active Directory (AAD) authentication
 - ✅ **`TracesPerSecond`** (double?) - Gets or sets the number of traces per second for rate-limited sampling (default sampling mode). Replaces `EnableAdaptiveSampling`.
 - ✅ **`SamplingRatio`** (float?) - Gets or sets the sampling ratio for traces (0.0 to 1.0). A value of 1.0 means all telemetry is sent. Replaces `EnableAdaptiveSampling`.
+- ✅ **`EnableTraceBasedLogsSampler`** (bool?) - Gets or sets whether trace-based log sampling is enabled (default: true). When enabled, logs are sampled based on the sampling decision of the associated trace.
 
 ## Migration Impact
 - Any code depending on `InstrumentationKey` must migrate to `ConnectionString`

BreakingChanges.md

@@ -1,35 +1,10 @@
 ![Build](https://mseng.visualstudio.com/DefaultCollection/_apis/public/build/definitions/96a62c4a-58c2-4dbb-94b6-5979ebc7f2af/2637/badge) 
 
 ## Nuget packages
-
-- For ILogger:
- [Microsoft.Extensions.Logging.ApplicationInsights](https://www.nuget.org/packages/Microsoft.Extensions.Logging.ApplicationInsights/)
-[![Nuget](https://img.shields.io/nuget/vpre/Microsoft.Extensions.Logging.ApplicationInsights.svg)](https://www.nuget.org/packages/Microsoft.Extensions.Logging.ApplicationInsights/)
 - For NLog:
  [Microsoft.ApplicationInsights.NLogTarget](http://www.nuget.org/packages/Microsoft.ApplicationInsights.NLogTarget/)
 [![Nuget](https://img.shields.io/nuget/vpre/Microsoft.ApplicationInsights.NLogTarget.svg)](https://www.nuget.org/packages/Microsoft.ApplicationInsights.NLogTarget/)
-- For Log4Net: [Microsoft.ApplicationInsights.Log4NetAppender](http://www.nuget.org/packages/Microsoft.ApplicationInsights.Log4NetAppender/)
-[![Nuget](https://img.shields.io/nuget/vpre/Microsoft.ApplicationInsights.Log4NetAppender.svg)](https://www.nuget.org/packages/Microsoft.ApplicationInsights.Log4NetAppender/)
-- For System.Diagnostics: [Microsoft.ApplicationInsights.TraceListener](http://www.nuget.org/packages/Microsoft.ApplicationInsights.TraceListener/)
-[![Nuget](https://img.shields.io/nuget/vpre/Microsoft.ApplicationInsights.TraceListener.svg)](https://www.nuget.org/packages/Microsoft.ApplicationInsights.TraceListener/)
-- [Microsoft.ApplicationInsights.DiagnosticSourceListener](http://www.nuget.org/packages/Microsoft.ApplicationInsights.DiagnosticSourceListener/)
-[![Nuget](https://img.shields.io/nuget/vpre/Microsoft.ApplicationInsights.DiagnosticSourceListener.svg)](https://www.nuget.org/packages/Microsoft.ApplicationInsights.DiagnosticSourceListener/)
-- [Microsoft.ApplicationInsights.EtwCollector](http://www.nuget.org/packages/Microsoft.ApplicationInsights.EtwCollector/)
-[![Nuget](https://img.shields.io/nuget/vpre/Microsoft.ApplicationInsights.EtwCollector.svg)](https://www.nuget.org/packages/Microsoft.ApplicationInsights.EtwCollector/)
-- [Microsoft.ApplicationInsights.EventSourceListener](http://www.nuget.org/packages/Microsoft.ApplicationInsights.EventSourceListener/)
-[![Nuget](https://img.shields.io/nuget/vpre/Microsoft.ApplicationInsights.EventSourceListener.svg)](https://www.nuget.org/packages/Microsoft.ApplicationInsights.EventSourceListener/)
-
-Application Insights logging adapters. 
-==============================
-
-If you use NLog, log4Net or System.Diagnostics.Trace for diagnostic tracing in your  application, you can have your logs sent to Application Insights, where you can explore and search them. Your logs will be merged with the other telemetry coming from your application, so that you can identify the traces associated with servicing each user request, and correlate them with other events and exception reports.
 
-Read more:
-- [Microsoft Docs: "Explore .NET trace logs in Application Insights"](https://docs.microsoft.com/azure/application-insights/app-insights-asp-net-trace-logs)
-- [Microsoft Docs: "Diagnose sudden changes in your app telemetry"](https://docs.microsoft.com/azure/application-insights/app-insights-analytics-diagnostics#trace)
-
-## ILogger
-See [this](src/ILogger/Readme.md).
 
 ## NLog
 
@@ -78,7 +53,7 @@ For more information, see the [Azure.Identity documentation](https://learn.micro
     </extensions>
 	<targets>
 		<target xsi:type="ApplicationInsightsTarget" name="aiTarget">
-			<instrumentationKey>Your_Resource_Key</instrumentationKey>	<!-- Only required if not using ApplicationInsights.config -->
+			<connectionString>InstrumentationKey=YOUR_IKEY;IngestionEndpoint=https://YOUR_REGION.in.applicationinsights.azure.com/</connectionString>
 			<contextproperty name="threadid" layout="${threadid}" />	<!-- Can be repeated with more context -->
 		</target>
 	</targets>
@@ -91,34 +66,22 @@ For more information, see the [Azure.Identity documentation](https://learn.micro
 NLog allows you to configure conditional configs:
 
 ```xml
-<instrumentationKey>${configsetting:APPINSIGHTS.INSTRUMENTATIONKEY:whenEmpty=${environment:APPINSIGHTS_INSTRUMENTATIONKEY}}</instrumentationKey>	
+<connectionString>${configsetting:APPLICATIONINSIGHTS_CONNECTION_STRING:whenEmpty=${environment:APPLICATIONINSIGHTS_CONNECTION_STRING}}</connectionString>
 ```
 
 For more information see:
 - https://github.com/NLog/NLog/wiki/ConfigSetting-Layout-Renderer
 - https://github.com/nlog/nlog/wiki/Environment-Layout-Renderer
 - https://github.com/nlog/nlog/wiki/WhenEmpty-Layout-Renderer
 
-
-
-```csharp
-// You need this only if you did not define InstrumentationKey in ApplicationInsights.config (Or in the NLog.config)
-TelemetryConfiguration.Active.InstrumentationKey = "Your_Resource_Key";
-
-Logger logger = LogManager.GetLogger("Example");
-
-logger.Trace("trace log message");
-```
-
 * **Configure ApplicationInsightsTarget using NLog Config API** :
 If you configure NLog programmatically with the [NLog Config API](https://github.com/nlog/NLog/wiki/Configuration-API), then create Application Insights target in code and add it to your other targets:
 
 ```csharp
 var config = new LoggingConfiguration();
 
 ApplicationInsightsTarget target = new ApplicationInsightsTarget();
-// You need this only if you did not define InstrumentationKey in ApplicationInsights.config or want to use different instrumentation key
-target.InstrumentationKey = "Your_Resource_Key";
+target.ConnectionString = "InstrumentationKey=....;IngestionEndpoint=...";
 
 LoggingRule rule = new LoggingRule("*", LogLevel.Trace, target);
 config.LoggingRules.Add(rule);
@@ -130,79 +93,3 @@ Logger logger = LogManager.GetLogger("Example");
 logger.Trace("trace log message");
 ``` 
 
-## Log4Net
-
-Application Insights Log4Net adapter nuget modifies web.config and adds Application Insights Appender.
-
-For more information, see [Log4Net Configuration](https://logging.apache.org/log4net/release/manual/configuration.html)
-
-```csharp
-// You do not need this if you have instrumentation key in the ApplicationInsights.config
-TelemetryConfiguration.Active.InstrumentationKey = "Your_Resource_Key";
-
-log4net.Config.XmlConfigurator.Configure();
-var logger = LogManager.GetLogger(this.GetType());
-
-logger.Info("Message");
-logger.Warn("A warning message");
-logger.Error("An error message");
-```
-
-## System.Diagnostics
-
-Microsoft.ApplicationInsights.TraceListener nuget package modifies web.config and adds application insights listener. 
-
-For more information, see ["Microsoft Docs: "Tracing and Instrumenting Applications"](https://docs.microsoft.com/dotnet/framework/debug-trace-profile/tracing-and-instrumenting-applications)
-
-```xml
-<configuration>
-  <system.diagnostics>
-    <trace>
-      <listeners>
-        <add name="myAppInsightsListener" type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
-      </listeners>
-    </trace>
-  </system.diagnostics>
-</configuration>
-```
-
-If your application type does not have web.config, add listener programmatically or in the configuration file appropriate to your application type
-
-```csharp
-// You do not need this if you have instrumentation key in the ApplicationInsights.config
-TelemetryConfiguration.Active.InstrumentationKey = "Your_Resource_Key";
-System.Diagnostics.Trace.TraceWarning("Slow response - database01");
-
-``` 
-
-
-## EventSource
-
-`EventSourceTelemetryModule` allows you to configure EventSource events to be sent to Application Insights as traces. 
-
-For more information, see [Microsoft Docs: "Using EventSource Events"](https://docs.microsoft.com/azure/application-insights/app-insights-asp-net-trace-logs#using-eventsource-events).
-
-
-## ETW
-
-`EtwCollectorTelemetryModule` allows you to configure events from ETW providers to be sent to Application Insights as traces. 
-
-For more information, see [Microsoft Docs: "Using ETW Events"](https://docs.microsoft.com/azure/application-insights/app-insights-asp-net-trace-logs#using-etw-events).
-
-
-## DiagnosticSource
-
-You can configure `System.Diagnostics.DiagnosticSource` events to be sent to Application Insights as traces.
-
-For more information, see [CoreFX: "Diagnostic Source Users Guide"](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md).
-
-To enable, edit the `TelemetryModules` section of the ApplicationInsights.config file:
-
-```xml
-<Add Type="Microsoft.ApplicationInsights.DiagnsoticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
-      <Sources>
-        <Add Name="MyDiagnosticSourceName" />
-      </Sources>
- </Add>
- ```
-