Merge pull request #3067 from microsoft/harskaur/webExporterOptions

Documentation for setting exporter options (BASE and WEB)

Author: harsimar

BASE/README.md

@@ -59,7 +59,7 @@ Select the option that best describes your situation:
   - [Tracking Page Views](#tracking-page-views)
 - [Configuration](#configuration)
   - [TelemetryConfiguration](#telemetryconfiguration)
-  - [Setting Context Properties](#setting-context-properties)
+- [Setting Context Properties](#setting-context-properties)
   - [Dependency Injection](#dependency-injection)
 - [Advanced Scenarios](#advanced-scenarios)
   - [Enriching Telemetry with Activity Processors](#enriching-telemetry-with-activity-processors)
@@ -627,6 +627,44 @@ var configuration = new TelemetryConfiguration
 };
 ```
 
+#### Telemetry Configuration Properties 
+
+`TelemetryConfiguration` exposes properties that configure settings related to sampling, offline storage, and live metrics emission. 
+
+| Property | Type | Default (when null) | Description |
+|----------|------|---------------------|-------------|
+| `SamplingRatio` | `float?` | `1.0` (100%) | Percentage of opentelemetry traces to sample (0.0 to 1.0) |
+| `TracesPerSecond` | `double?` | None | Traces per second (rate-limited sampling) |
+| `StorageDirectory` | `string` | Platform-specific* | Directory for offline telemetry storage |
+| `DisableOfflineStorage` | `bool?` | `false` | When `true`, disables offline storage for failed transmissions |
+| `EnableLiveMetrics` | `bool?` | `true` | Enables Live Metrics stream in Azure Portal |
+| `EnableTraceBasedLogsSampler` | `bool?` | `true` | Applies trace sampling decisions to related logs |
+
+*Storage directory defaults: Windows: `%LOCALAPPDATA%\Microsoft\AzureMonitor`, Linux/macOS: `$TMPDIR/Microsoft/AzureMonitor`
+
+> **⚠️ Sampling Configuration:** Configure **either** `SamplingRatio` **or** `TracesPerSecond`, not both. Use `SamplingRatio` for percentage-based sampling (e.g., keep 50% of telemetry). Use `TracesPerSecond` for rate-limited sampling (e.g., keep at most 5 traces per second regardless of load).
+
+**Example:**
+
+```csharp
+var configuration = new TelemetryConfiguration
+{
+    ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...",
+    
+    // Sampling: Choose ONE of these approaches
+    SamplingRatio = 0.5f,       // Keep 50% of telemetry
+    // TracesPerSecond = 5.0,   // OR: Keep max 5 traces/second
+    
+    // Offline storage
+    StorageDirectory = @"C:\AppData\MyApp\Telemetry",
+    DisableOfflineStorage = false,
+    
+    // Features
+    EnableLiveMetrics = true,
+    EnableTraceBasedLogsSampler = true
+};
+```
+
 #### Configuring OpenTelemetry Integration
 
 In version 3.x, you can extend the SDK using OpenTelemetry's extensibility model. Use `ConfigureOpenTelemetryBuilder()` to access the underlying OpenTelemetry configuration:

WEB/Src/Web/README.md

@@ -38,3 +38,6 @@ public class Global : HttpApplication
 **Note:** You need to install the `Azure.Identity` NuGet package to use AAD authentication.
 
 For more information, see the [Azure.Identity documentation](https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme).
+
+### Sampling, Offline Storage, and other configuration
+Other options can also be set via the TelemetryConfiguration in the `Global.asax.cs` file. See [documentation for Microsoft.ApplicationInsights](../../../BASE/README.smd#azure-monitor-exporter-options).

examples/ClassicAspNetWebApp/Global.asax.cs

@@ -17,12 +17,40 @@ void Application_Start(object sender, EventArgs e)
             // Code that runs on application startup
             RouteConfig.RegisterRoutes(RouteTable.Routes);
             // BundleConfig.RegisterBundles(BundleTable.Bundles);
-            
-            // Example: Configure Azure Active Directory (AAD) authentication for Application Insights
-            // Requires: Install-Package Azure.Identity
+
+            // ============================================================================
+            // EXAMPLE: Configure Application Insights with Azure Monitor Exporter Options
+            // ============================================================================
+            // 
             // var telemetryConfig = TelemetryConfiguration.CreateDefault();
-            // telemetryConfig.ConnectionString = "InstrumentationKey=YOUR_IKEY;IngestionEndpoint=https://ingestion-endpoint.applicationinsights.azure.com/";
-            // telemetryConfig.SetAzureTokenCredential(new Azure.Identity.DefaultAzureCredential());
+            // telemetryConfig.ConnectionString = "";
+            //
+            // // SAMPLING: Choose ONE approach (not both)
+            // // SamplingRatio: Percentage of telemetry to keep (0.0 to 1.0). Default: 1.0 (100%)
+            // telemetryConfig.SamplingRatio = 0.5f;           // Keep 50% of telemetry
+            // // TracesPerSecond: Rate-limited sampling. Default: null (disabled)
+            // // telemetryConfig.TracesPerSecond = 5.0;       // OR: Keep max 5 traces/second
+            //
+            // // OFFLINE STORAGE: Persists telemetry when network is unavailable
+            // // StorageDirectory: Custom path for offline storage.
+            // //   Default: %LOCALAPPDATA%\Microsoft\AzureMonitor (Windows)
+            // //            $TMPDIR/Microsoft/AzureMonitor (Linux/macOS)
+            // // telemetryConfig.StorageDirectory = @"C:\AppInsightsStorage";
+            // // DisableOfflineStorage: Set to true to disable offline storage. Default: false
+            // telemetryConfig.DisableOfflineStorage = false;
+            //
+            // // FEATURES
+            // // EnableLiveMetrics: Enable real-time metrics streaming. Default: true
+            // telemetryConfig.EnableLiveMetrics = true;
+            // // EnableTraceBasedLogsSampler: Apply trace-based sampling to logs. Default: true
+            // telemetryConfig.EnableTraceBasedLogsSampler = true;
+            //
+            // // AUTHENTICATION: Azure AD (Entra ID) token-based auth
+            // // Requires: Install-Package Azure.Identity
+            // // telemetryConfig.SetAzureTokenCredential(new Azure.Identity.DefaultAzureCredential());
+            //
+            // var telemetryClient = new TelemetryClient(telemetryConfig);
+            // telemetryClient.Context.Cloud.RoleName = "MyWebApp";
         }
     }
 }