@azure/mcp-linux-arm64 2.0.0-beta.27 → 2.0.0-beta.29

package/dist/Resources/concepts/dotnet/azure-monitor-distro.md

@@ -0,0 +1,102 @@
+---
+title: Azure Monitor OpenTelemetry Distro
+category: concept
+applies-to: 3.x
+---
+
+# Azure Monitor OpenTelemetry Distro
+
+**Category:** Concept  
+**Applies to:** 3.x
+
+## Overview
+
+The Azure Monitor OpenTelemetry Distro (`Azure.Monitor.OpenTelemetry.AspNetCore`) is a batteries-included package that configures OpenTelemetry with sensible defaults for Azure Monitor/Application Insights.
+
+## What It Provides
+
+One line of code enables:
+
+```csharp
+builder.Services.AddOpenTelemetry().UseAzureMonitor();
+```
+
+### Automatic Instrumentation
+- **ASP.NET Core** - HTTP requests (traces)
+- **HttpClient** - Outgoing HTTP calls (dependencies)
+- **SQL Client** - Database calls
+- **Azure SDK** - Azure service calls
+
+### Automatic Export
+- Traces → Application Insights (requests, dependencies)
+- Metrics → Application Insights (performance counters, custom metrics)
+- Logs → Application Insights (traces, exceptions)
+
+### Automatic Enrichment
+- Cloud role name detection
+- Kubernetes metadata
+- Azure App Service metadata
+
+## Configuration
+
+### Connection String (Required)
+
+Option 1: Environment variable (recommended)
+```bash
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=https://...
+```
+
+Option 2: appsettings.json
+```json
+{
+  "AzureMonitor": {
+    "ConnectionString": "InstrumentationKey=xxx;IngestionEndpoint=https://..."
+  }
+}
+```
+
+Option 3: Code
+```csharp
+builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
+{
+    options.ConnectionString = "InstrumentationKey=xxx;...";
+});
+```
+
+### Optional Configuration
+
+```csharp
+builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
+{
+    // Sampling
+    options.SamplingRatio = 0.1f; // 10% sampling
+    
+    // Disable specific auto-instrumentation
+    options.EnableLiveMetrics = false;
+    
+    // Custom resource attributes
+    options.Resource = ResourceBuilder.CreateDefault()
+        .AddService("MyService", "1.0.0");
+});
+```
+
+## Package Reference
+
+```xml
+<PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" Version="1.3.0" />
+```
+
+## When to Use
+
+| Scenario | Recommendation |
+|----------|----------------|
+| New ASP.NET Core app | ✅ Use Distro |
+| Existing AI SDK 2.x app | ✅ Migrate to Distro |
+| Need custom exporters | Consider manual OpenTelemetry setup |
+| Non-ASP.NET Core | Use `Azure.Monitor.OpenTelemetry.Exporter` directly |
+
+## See Also
+
+- OpenTelemetry Pipeline(see in opentelemetry-pipeline.md)
+- UseAzureMonitor API(see in api-reference/dotnet/UseAzureMonitor.md)
+- Basic Setup Example(see in examples/dotnet/aspnetcore-setup.md)

package/dist/Resources/concepts/dotnet/opentelemetry-pipeline.md

@@ -0,0 +1,57 @@
+---
+title: OpenTelemetry Pipeline
+category: concept
+applies-to: 3.x
+---
+
+# OpenTelemetry Pipeline
+
+**Category:** Concept  
+**Applies to:** 3.x
+
+## Overview
+
+The OpenTelemetry pipeline is the data flow path for telemetry signals (traces, metrics, logs) from your application to observability backends. Understanding this pipeline is essential for Azure Monitor integration.
+
+## Pipeline Components
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Instrumentation │ ──▶ │   Processors    │ ──▶ │    Exporters    │
+│  (Sources)       │     │   (Transform)   │     │   (Backends)    │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+### 1. Instrumentation (Sources)
+- **ActivitySource** - Creates spans/traces
+- **Meter** - Creates metrics
+- **ILogger** - Creates logs (via OpenTelemetry.Extensions.Logging)
+
+### 2. Processors (Transform)
+- **BaseProcessor<Activity>** - Enrich or filter spans
+- **BaseProcessor<LogRecord>** - Enrich or filter logs
+- Run in pipeline order before export
+
+### 3. Exporters (Backends)
+- **Azure Monitor Exporter** - Sends to Application Insights
+- **OTLP Exporter** - Sends to any OTLP-compatible backend
+- **Console Exporter** - Debug output
+
+## Wiring Up the Pipeline
+
+See the AddOpenTelemetry API reference(see in AddOpenTelemetry.md) for full setup examples showing how sources, processors, and exporters are composed via the builder API.
+
+## Key Differences from Application Insights 2.x
+
+| 2.x Concept | 3.x Equivalent |
+|-------------|----------------|
+| TelemetryClient | ActivitySource / Meter / ILogger |
+| ITelemetryInitializer | BaseProcessor<Activity>.OnStart |
+| ITelemetryProcessor | BaseProcessor<Activity>.OnEnd |
+| TelemetryChannel | Exporter |
+| TelemetryConfiguration | OpenTelemetryBuilder |
+
+## See Also
+
+- Azure Monitor Distro(see in azure-monitor-distro.md)
+- AddOpenTelemetry API(see in AddOpenTelemetry.md)

package/dist/Resources/examples/dotnet/aspnetcore-setup.md

@@ -0,0 +1,156 @@
+---
+title: Basic ASP.NET Core Setup
+category: example
+applies-to: 3.x
+source: ApplicationInsightsDemo/Program.cs
+---
+
+# Basic ASP.NET Core Setup
+
+**Category:** Example  
+**Applies to:** 3.x
+
+## Overview
+
+Complete working example of adding Azure Monitor to a new ASP.NET Core application.
+
+## Step 1: Add Package
+
+```bash
+dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
+```
+
+Or in `.csproj`:
+
+```xml
+<PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" Version="1.3.0" />
+```
+
+## Step 2: Configure in Program.cs
+
+### Minimal Setup
+
+```csharp
+using Azure.Monitor.OpenTelemetry.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add Azure Monitor - one line!
+builder.Services.AddOpenTelemetry().UseAzureMonitor();
+
+builder.Services.AddControllers();
+
+var app = builder.Build();
+
+app.MapControllers();
+app.Run();
+```
+
+### With Configuration Options
+
+```csharp
+using Azure.Monitor.OpenTelemetry.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
+{
+    // Connection string from configuration
+    options.ConnectionString = builder.Configuration["AzureMonitor:ConnectionString"];
+    
+    // Sample 50% of requests in production
+    if (!builder.Environment.IsDevelopment())
+    {
+        options.SamplingRatio = 0.5f;
+    }
+});
+
+builder.Services.AddControllers();
+
+var app = builder.Build();
+
+app.MapControllers();
+app.Run();
+```
+
+## Step 3: Configure Connection String
+
+### Option A: Environment Variable (Recommended for Production)
+
+```bash
+export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=xxx;IngestionEndpoint=https://..."
+```
+
+### Option B: appsettings.json
+
+```json
+{
+  "AzureMonitor": {
+    "ConnectionString": "InstrumentationKey=xxx;IngestionEndpoint=https://..."
+  }
+}
+```
+
+### Option C: User Secrets (Development)
+
+```bash
+dotnet user-secrets set "AzureMonitor:ConnectionString" "InstrumentationKey=xxx;..."
+```
+
+## Complete Program.cs
+
+```csharp
+using Azure.Monitor.OpenTelemetry.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add services
+builder.Services.AddControllers();
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+// Add Azure Monitor OpenTelemetry
+builder.Services.AddOpenTelemetry().UseAzureMonitor();
+
+var app = builder.Build();
+
+// Configure pipeline
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+
+app.UseHttpsRedirection();
+app.UseAuthorization();
+app.MapControllers();
+
+app.Run();
+```
+
+## What You Get Automatically
+
+After this setup, Azure Monitor will collect:
+
+| Signal | Data |
+|--------|------|
+| **Requests** | All incoming HTTP requests with timing, status codes |
+| **Dependencies** | Outgoing HTTP calls, SQL queries, Azure SDK calls |
+| **Exceptions** | Unhandled exceptions with stack traces |
+| **Logs** | ILogger output (Information level and above) |
+| **Metrics** | Request rate, response time, CPU, memory |
+
+## Verify It Works
+
+1. Run your application
+2. Make some requests
+3. Check Application Insights in Azure Portal (may take 2-5 minutes)
+4. Look for:
+   - Live Metrics (immediate)
+   - Transaction Search (requests, dependencies)
+   - Failures (exceptions)
+
+## See Also
+
+- Azure Monitor Distro(see in azure-monitor-distro.md)
+- UseAzureMonitor API(see in UseAzureMonitor.md)

package/dist/Resources/migration/dotnet/appinsights-2x-to-3x-code-migration.md

@@ -0,0 +1,134 @@
+---
+title: Application Insights 2.x to 3.x Migration
+category: migration
+applies-to: 3.x
+---
+
+# App Insights 2.x → 3.x Code Migration
+
+## What changed
+
+3.x uses OpenTelemetry under the hood. The main entry point is the same — `AddApplicationInsightsTelemetry()` — but several options and extension methods were removed.
+
+Key changes:
+- `InstrumentationKey` → use `ConnectionString`
+- `EnableAdaptiveSampling` → use `TracesPerSecond` (default `5`) or `SamplingRatio`
+- Logging is automatic — `ApplicationInsightsLoggerProvider` was removed
+- New: `Credential` for AAD authentication, `EnableTraceBasedLogsSampler` for log sampling control
+
+## Before / after
+
+**2.x**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.InstrumentationKey = "your-ikey";          // Removed in 3.x
+    options.EnableAdaptiveSampling = false;             // Removed in 3.x
+    options.DeveloperMode = true;                       // Removed in 3.x
+});
+```
+
+**3.x**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.ApplicationInsights.AspNetCore.Extensions;
+
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+    options.SamplingRatio = 1.0f;       // No sampling (collect everything)
+    // DeveloperMode — no replacement needed, remove the line
+});
+```
+
+Or set `APPLICATIONINSIGHTS_CONNECTION_STRING` as an environment variable and call `AddApplicationInsightsTelemetry()` with no arguments.
+
+## Property changes
+
+| Property | Status | Action required |
+|---|---|---|
+| `ConnectionString` | Unchanged | None. |
+| `ApplicationVersion` | Unchanged | None. |
+| `EnableQuickPulseMetricStream` | Unchanged | None. Default `true`. |
+| `EnablePerformanceCounterCollectionModule` | Unchanged | None. Default `true`. |
+| `EnableDependencyTrackingTelemetryModule` | Unchanged | None. Default `true`. |
+| `EnableRequestTrackingTelemetryModule` | Unchanged | None. Default `true`. |
+| `AddAutoCollectedMetricExtractor` | Unchanged | None. Default `true`. |
+| `EnableAuthenticationTrackingJavaScript` | Unchanged | None. Default `false`. |
+| `InstrumentationKey` | **Removed** | Use `ConnectionString`. |
+| `EnableAdaptiveSampling` | **Removed** | Use `TracesPerSecond` or `SamplingRatio`. |
+| `DeveloperMode` | **Removed** | Delete the line. |
+| `EndpointAddress` | **Removed** | Endpoint is now part of `ConnectionString`. |
+| `EnableHeartbeat` | **Removed** | Delete the line; heartbeat is automatic. |
+| `EnableDebugLogger` | **Removed** | Delete the line. |
+| `RequestCollectionOptions` | **Removed** | Delete the line. |
+| `DependencyCollectionOptions` | **Removed** | Delete the line. |
+| `TelemetryInitializers` | **Removed** | Delete the line. |
+| `Credential` | **New** | `TokenCredential`, default `null`. Set for AAD auth. |
+| `TracesPerSecond` | **New** | `double?`, effective default `5`. Rate-limited sampling. |
+| `SamplingRatio` | **New** | `float?`, default `null`. Fixed-rate sampling (0.0–1.0). |
+| `EnableTraceBasedLogsSampler` | **New** | `bool?`, effective default `true`. Logs follow parent trace sampling. |
+
+## Removed extension methods
+
+| Method | Replacement |
+|---|---|
+| `AddApplicationInsightsTelemetry(string instrumentationKey)` | Use parameterless overload + `ConnectionString` in options or env var. |
+| `UseApplicationInsights()` (all `IWebHostBuilder` overloads) | Use `AddApplicationInsightsTelemetry()` on `IServiceCollection`. |
+| `AddApplicationInsightsTelemetryProcessor<T>()` | Use OpenTelemetry processors. |
+| `ConfigureTelemetryModule<T>()` | Removed; module functionality is built-in. |
+
+## Removed interfaces and classes
+
+| Type | Notes |
+|---|---|
+| `ITelemetryInitializer` | Removed. Convert to `BaseProcessor<Activity>` with `OnStart`. Register via `.AddProcessor<T>()` in the OpenTelemetry pipeline. |
+| `ITelemetryProcessor` | Removed. Convert to `BaseProcessor<Activity>` with `OnEnd`. To drop telemetry, clear `data.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded`. Register via `.AddProcessor<T>()`. |
+| `ApplicationInsightsLoggerProvider` | Logging is now automatic. No replacement needed. |
+| `ExceptionTrackingMiddleware` | Exception tracking is built-in. |
+
+## TelemetryClient changes
+
+| Change | Details |
+|---|---|
+| `TrackEvent` | 3-param overload `(string, IDictionary<string,string>, IDictionary<string,double>)` **removed** — metrics dict dropped. Use 2-param overload and track metrics separately via `TrackMetric()`. |
+| `TrackException` | 3-param overload with `IDictionary<string,double>` **removed**. Use 2-param overload and track metrics separately via `TrackMetric()`. |
+| `TrackAvailability` | 8-param overload with trailing `IDictionary<string,double>` **removed**. Use 7-param overload and track metrics separately via `TrackMetric()`. |
+| `TrackPageView` | **Removed entirely** (both overloads). Use `TrackEvent` or `TrackRequest` instead. |
+| `GetMetric` | `MetricConfiguration` and `MetricAggregationScope` params **removed** from all overloads. Use simplified `GetMetric(metricId, ...)`. |
+| parameterless `TelemetryClient()` | **Removed**. Use `TelemetryClient(TelemetryConfiguration)` via DI. |
+| `client.InstrumentationKey` | **Removed**. Use `TelemetryConfiguration.ConnectionString`. |
+| `TrackTrace`, `TrackMetric`, `TrackRequest`, `TrackDependency` (full overload), `Flush` | **Unchanged** — no action needed. |
+
+## Migration steps
+
+1. Update the package:
+   ```xml
+   <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="3.*" />
+   ```
+
+2. Find and replace in your code:
+   - `InstrumentationKey = "..."` → `ConnectionString = "InstrumentationKey=...;IngestionEndpoint=..."`
+   - `EnableAdaptiveSampling = false` → `SamplingRatio = 1.0f` (or set `TracesPerSecond`)
+   - Delete any lines setting `DeveloperMode`, `EndpointAddress`, `EnableHeartbeat`, `EnableDebugLogger`, `RequestCollectionOptions`, `DependencyCollectionOptions`, or `TelemetryInitializers`
+   - Delete calls to `UseApplicationInsights()`, `AddApplicationInsightsTelemetryProcessor<T>()`, `ConfigureTelemetryModule<T>()`
+
+3. Migrate custom telemetry types:
+   - Convert each `ITelemetryInitializer` implementation to a `BaseProcessor<Activity>` with `OnStart`. Register via `.AddProcessor<T>()` in the OpenTelemetry pipeline.
+   - Convert each `ITelemetryProcessor` implementation to a `BaseProcessor<Activity>` with `OnEnd`. To drop telemetry, clear the Recorded flag: `data.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded`. Register via `.AddProcessor<T>()`.
+   - `TelemetryClient` mostly works in 3.x but has breaking changes: remove `IDictionary<string, double> metrics` parameter from `TrackEvent`/`TrackException`/`TrackAvailability` calls (track metrics separately via `TrackMetric()`). Replace `TrackPageView` with `TrackEvent` or `TrackRequest`. Remove `GetMetric` overloads that take `MetricConfiguration`/`MetricAggregationScope`.
+
+4. Build and verify — the `Enable*` flags (`EnableQuickPulseMetricStream`, `EnableDependencyTrackingTelemetryModule`, etc.) still work with the same defaults. No changes needed for those.
+
+## Behavior notes
+
+- `TracesPerSecond` is the default sampling mode (effective default `5`). No configuration needed for most apps.
+- Connection string resolution order: `ApplicationInsightsServiceOptions.ConnectionString` → `APPLICATIONINSIGHTS_CONNECTION_STRING` env var → `ApplicationInsights:ConnectionString` in config.
+
+## See also
+
+- No-code-change migration(see in appinsights-2x-to-3x-no-code-change.md)
+- AddApplicationInsightsTelemetry API reference(see in AddApplicationInsightsTelemetry.md)
+- TelemetryClient breaking changes(see in TelemetryClient.md)

package/dist/Resources/migration/dotnet/appinsights-2x-to-3x-no-code-change.md

@@ -0,0 +1,92 @@
+---
+title: Application Insights 2.x to 3.x — No-Code-Change Migration
+category: migration
+applies-to: 3.x
+---
+
+# App Insights 2.x → 3.x — No Code Change
+
+## When this applies
+
+Your migration requires **only a package upgrade** (no code changes) if both of these are true:
+
+1. You call `AddApplicationInsightsTelemetry()` with no arguments, an `IConfiguration`, or with options that only set **unchanged properties**.
+2. You do not use any **removed extension methods** (`UseApplicationInsights()`, `AddApplicationInsightsTelemetryProcessor<T>()`, `ConfigureTelemetryModule<T>()`).
+
+### Unchanged properties (safe to keep as-is)
+
+| Property | Default |
+|---|---|
+| `ConnectionString` | `null` |
+| `ApplicationVersion` | Entry assembly version |
+| `EnableQuickPulseMetricStream` | `true` |
+| `EnablePerformanceCounterCollectionModule` | `true` |
+| `EnableDependencyTrackingTelemetryModule` | `true` |
+| `EnableRequestTrackingTelemetryModule` | `true` |
+| `AddAutoCollectedMetricExtractor` | `true` |
+| `EnableAuthenticationTrackingJavaScript` | `false` |
+
+If your code only uses these properties (or none at all), **and** does not use `ITelemetryInitializer` or `ITelemetryProcessor`, no code changes are needed. (`TelemetryClient` still works in 3.x — existing usage does not block a no-code-change upgrade.)
+
+## Migration steps
+
+### 1. Update the package
+
+```xml
+<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="3.*" />
+```
+
+### 2. Build and run
+
+That's it. No code changes required.
+
+## Examples that work without changes
+
+**Parameterless call:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddApplicationInsightsTelemetry();
+var app = builder.Build();
+```
+
+**IConfiguration overload:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddApplicationInsightsTelemetry(builder.Configuration);
+var app = builder.Build();
+```
+
+**Options with only unchanged properties:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.ApplicationInsights.AspNetCore.Extensions;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddApplicationInsightsTelemetry(options =>
+{
+    options.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+    options.EnableQuickPulseMetricStream = true;
+    options.EnableDependencyTrackingTelemetryModule = true;
+});
+var app = builder.Build();
+```
+
+All three examples above work identically in 2.x and 3.x.
+
+## What changes under the hood
+
+Even though your code stays the same, 3.x brings these improvements automatically:
+
+- Telemetry is now collected via OpenTelemetry — better standards alignment and ecosystem compatibility.
+- `TracesPerSecond` (effective default `5`) provides rate-limited sampling out of the box. No configuration needed.
+- Logging is integrated automatically — `ILogger` output is exported to Application Insights without additional setup.
+- Azure resource detection (App Service, VM) happens automatically.
+
+## See also
+
+- Application Insights 2.x to 3.x Code Migration(see in appinsights-2x-to-3x-code-migration.md)
+- AddApplicationInsightsTelemetry API reference(see in AddApplicationInsightsTelemetry.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/mcp-linux-arm64",
-  "version": "2.0.0-beta.27",
+  "version": "2.0.0-beta.29",
   "description": "Azure MCP Server - Model Context Protocol implementation for Azure, for linux on arm64",
   "author": "Microsoft",
   "homepage": "https://github.com/Microsoft/mcp/blob/main/servers/Azure.Mcp.Server#readme",