@azure/mcp-linux-arm64 2.0.0-beta.8 → 3.0.0-beta.1

package/dist/Instrumentation/Resources/concepts/nodejs/opentelemetry-pipeline.md

@@ -0,0 +1,201 @@
+# OpenTelemetry Pipeline for Node.js
+
+## Overview
+
+The OpenTelemetry pipeline is the data flow path for telemetry signals (traces, metrics, logs) from your Node.js application to observability backends like Azure Monitor.
+
+## Pipeline Components
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Instrumentation │ ──▶ │   Processors    │ ──▶ │    Exporters    │
+│  (Sources)       │     │   (Transform)   │     │   (Backends)    │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+### 1. Instrumentation (Sources)
+- **HTTP Instrumentation** - Automatically captures HTTP requests/responses
+- **Database Instrumentation** - Tracks database queries (MongoDB, PostgreSQL, MySQL, etc.)
+- **Custom Spans** - Manual instrumentation using OpenTelemetry API
+- **Logs** - Console logs and structured logging
+
+### 2. Processors (Transform)
+- **Span Processors** - Modify or filter spans before export
+- **Batch Processors** - Batch telemetry for efficient export
+- **Sampling** - Control volume of telemetry sent
+
+### 3. Exporters (Backends)
+- **Azure Monitor Exporter** - Sends to Application Insights
+- **OTLP Exporter** - Sends to any OTLP-compatible backend
+- **Console Exporter** - Debug output to console
+
+## In Node.js with Express
+
+```javascript
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+const { trace } = require('@opentelemetry/api');
+
+// Initialize with Azure Monitor exporter
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  },
+  // Optional: Configure sampling
+  samplingRatio: 1.0 // 100% of requests
+});
+
+// Your Express app
+const express = require('express');
+const app = express();
+
+// HTTP requests are automatically instrumented
+app.get('/api/users', async (req, res) => {
+  // Get current span for custom attributes
+  const span = trace.getActiveSpan();
+  span?.setAttribute('user.role', 'admin');
+  
+  res.json({ users: [] });
+});
+```
+
+## In Next.js
+
+Next.js uses a special `instrumentation.js` hook instead of inline initialization. The key differences from Express/standard Node.js:
+
+1. **Instrumentation hook**: Create `instrumentation.js` at the project root with a `register()` export
+2. **Runtime check**: Guard with `process.env.NEXT_RUNTIME === 'nodejs'` to avoid Edge runtime
+3. **Webpack externals**: Must externalize OpenTelemetry packages in `next.config.js` to prevent webpack from bundling Node.js-only modules
+4. **Logging libraries (Next.js only)**: In Next.js, libraries like Bunyan and Winston must also be added to webpack externals because they have native/optional dependencies that webpack cannot resolve. This is **not** required in standard Node.js apps (Express, Fastify, etc.) where these libraries work out of the box.
+
+```javascript
+// instrumentation.js (project root)
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+
+export function register() {
+    if (process.env.NEXT_RUNTIME === 'nodejs') {
+        useAzureMonitor({
+            azureMonitorExporterOptions: {
+                connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+            }
+        });
+    }
+}
+```
+
+See Next.js Setup Guide(see in basic-setup-nextjs.md) for the complete configuration including webpack externals.
+
+## Automatic Instrumentation
+
+The `@azure/monitor-opentelemetry` package automatically instruments:
+
+- ✅ **HTTP/HTTPS** - Incoming and outgoing requests
+- ✅ **Express** - Routes, middleware, error handlers
+- ✅ **Next.js** - API routes, Server Components (via instrumentation hook)
+- ✅ **MongoDB** - Queries and operations
+- ✅ **MySQL/PostgreSQL** - Database queries
+- ✅ **Redis** - Cache operations
+- ✅ **DNS** - DNS lookups
+- ✅ **File System** - I/O operations (when configured)
+
+## Manual Instrumentation
+
+For custom telemetry:
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+// Get tracer
+const tracer = trace.getTracer('my-app');
+
+// Create custom span
+const span = tracer.startSpan('process-data');
+try {
+  // Your business logic
+  span.setAttribute('record.count', 100);
+  span.addEvent('Processing started');
+  
+  // ... do work ...
+  
+  span.addEvent('Processing completed');
+} catch (error) {
+  span.recordException(error);
+  span.setStatus({ code: SpanStatusCode.ERROR });
+} finally {
+  span.end();
+}
+```
+
+## Configuration Options
+
+```javascript
+useAzureMonitor({
+  // Connection string
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  },
+  
+  // Sampling (0.0 to 1.0)
+  samplingRatio: 0.5, // 50% of requests
+  
+  // Resource attributes
+  resource: {
+    attributes: {
+      'service.name': 'my-express-api',
+      'service.version': '1.0.0',
+      'deployment.environment': 'production'
+    }
+  },
+  
+  // Instrumentation configuration
+  instrumentationOptions: {
+    http: { enabled: true },
+    mongoDb: { enabled: true },
+    express: { enabled: true }
+  }
+});
+```
+
+## Telemetry Types
+
+### Traces (Spans)
+- Request/response flows
+- Database queries
+- External API calls
+- Custom operations
+
+### Metrics
+- Request counts
+- Response times
+- Error rates
+- Custom counters/gauges
+
+### Logs
+- Console output (`console.log`, `console.error`)
+- Structured logging frameworks (Winston, Bunyan)
+- Exception traces
+
+## Best Practices
+
+1. **Initialize Early** - Call `useAzureMonitor()` before importing application code
+2. **Use Environment Variables** - Store connection strings securely
+3. **Enable Sampling** - For high-volume apps, use sampling to control costs
+4. **Add Context** - Use custom attributes to enrich telemetry
+5. **Handle Errors** - Always record exceptions in custom spans
+
+## Comparison: Application Insights SDK vs OpenTelemetry
+
+| Feature | Classic SDK | OpenTelemetry |
+|---------|-------------|---------------|
+| Initialization | `appInsights.setup()` | `useAzureMonitor()` |
+| Custom Tracking | `trackEvent()`, `trackTrace()` | `span.addEvent()`, `console.log()` |
+| Dependencies | Automatic | Automatic (via instrumentations) |
+| Vendor Lock-in | Azure-specific | Vendor-neutral (CNCF standard) |
+| Future Support | Limited | Full Microsoft commitment |
+
+## See Also
+
+- Azure Monitor for Node.js(see in azure-monitor-nodejs.md)
+- Express Setup Guide(see in basic-setup-express.md)
+- Next.js Setup Guide(see in basic-setup-nextjs.md)
+- Bunyan Setup Guide(see in basic-setup-bunyan-nodejs.md)
+- [OpenTelemetry Documentation](https://opentelemetry.io/docs/instrumentation/js/)

package/dist/Instrumentation/Resources/concepts/python/azure-monitor-overview.md

@@ -0,0 +1,122 @@
+---
+title: Azure Monitor OpenTelemetry for Python
+category: concept
+applies-to: python
+---
+
+# Azure Monitor for Python
+
+**Category:** Concept  
+**Applies to:** Python
+
+Azure Monitor OpenTelemetry Distro for Python provides automatic instrumentation and telemetry collection for Python applications.
+
+## Key Features
+
+- **Automatic Instrumentation**: Captures HTTP requests, database calls, and external dependencies
+- **Custom Telemetry**: Track custom events, metrics, and traces
+- **Performance Monitoring**: Monitor response times, throughput, and failures
+- **Dependency Tracking**: Understand outgoing calls to databases, APIs, and services
+- **Distributed Tracing**: Follow requests across microservices
+
+## Supported Frameworks
+
+The Azure Monitor Distro automatically instruments:
+- **Django** - Full-featured web framework
+- **Flask** - Lightweight WSGI framework
+- **FastAPI** - Modern async API framework
+- **Requests** - HTTP library
+- **urllib/urllib3** - Standard HTTP libraries
+- **Psycopg2** - PostgreSQL adapter
+
+Additional instrumentations available via OpenTelemetry contrib packages.
+
+## Installation
+
+```bash
+pip install azure-monitor-opentelemetry
+```
+
+## Basic Setup
+
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+
+# Configure Azure Monitor - must be called before importing frameworks
+configure_azure_monitor()
+
+# Now import and use your framework
+from flask import Flask
+app = Flask(__name__)
+```
+
+## Configuration Options
+
+The `configure_azure_monitor()` function uses environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `APPLICATIONINSIGHTS_CONNECTION_STRING` | Required. Your App Insights connection string |
+| `OTEL_SERVICE_NAME` | Optional. Your application name |
+| `OTEL_RESOURCE_ATTRIBUTES` | Optional. Custom resource attributes |
+| `OTEL_TRACES_SAMPLER` | Optional. Sampling strategy |
+| `OTEL_TRACES_SAMPLER_ARG` | Optional. Sampling rate (0.0-1.0) |
+
+## What Gets Instrumented
+
+### Automatically Captured (Distro Bundled)
+- HTTP requests via Django, Flask, FastAPI
+- HTTP client calls via requests, urllib, urllib3
+- PostgreSQL queries via psycopg2
+- Azure SDK calls via azure-core
+
+### Manual Instrumentation Required
+For other libraries (Redis, MongoDB, Celery, etc.), install the OpenTelemetry instrumentation package:
+
+```bash
+pip install opentelemetry-instrumentation-redis
+```
+
+### Custom Telemetry
+```python
+from opentelemetry import trace
+
+# Get current tracer
+tracer = trace.get_tracer(__name__)
+
+# Create custom span
+with tracer.start_as_current_span("custom-operation") as span:
+    span.set_attribute("custom.attribute", "value")
+    # Your business logic here
+```
+
+## Best Practices
+
+1. **Initialize Early**: Call `configure_azure_monitor()` before importing frameworks
+2. **Use Environment Variables**: Store connection string in `.env` file
+3. **Enable Sampling**: For high-traffic apps, configure sampling to manage costs
+4. **Add Context**: Use custom attributes to enrich telemetry
+5. **Monitor Performance**: Set up alerts in Azure Monitor for key metrics
+
+## Connection String
+
+Get your connection string from Azure Portal:
+1. Navigate to your Application Insights resource
+2. Go to "Overview" section
+3. Copy the "Connection String" value
+
+Set it as an environment variable:
+```bash
+export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=..."
+```
+
+Or in `.env` file:
+```
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
+```
+
+## Links
+
+- [Azure Monitor OpenTelemetry Distro](https://learn.microsoft.com/azure/azure-monitor/app/opentelemetry-enable?tabs=python)
+- [OpenTelemetry Python](https://opentelemetry.io/docs/instrumentation/python/)
+- [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python)

package/dist/Instrumentation/Resources/concepts/python/opentelemetry-pipeline.md

@@ -0,0 +1,154 @@
+---
+title: OpenTelemetry Pipeline for Python
+category: concept
+applies-to: python
+---
+
+# OpenTelemetry Pipeline for Python
+
+**Category:** Concept  
+**Applies to:** Python
+
+This document explains how OpenTelemetry works in Python applications and how Azure Monitor integrates with it.
+
+## OpenTelemetry Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Your Python Application                  │
+├─────────────────────────────────────────────────────────────┤
+│  Instrumentation Layer                                      │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
+│  │   Django    │ │    Flask    │ │   FastAPI   │            │
+│  │ Instrumentor│ │ Instrumentor│ │ Instrumentor│            │
+│  └─────────────┘ └─────────────┘ └─────────────┘            │
+├─────────────────────────────────────────────────────────────┤
+│  OpenTelemetry SDK                                          │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
+│  │   Traces    │ │   Metrics   │ │    Logs     │            │
+│  │  Provider   │ │  Provider   │ │  Provider   │            │
+│  └─────────────┘ └─────────────┘ └─────────────┘            │
+├─────────────────────────────────────────────────────────────┤
+│  Exporters                                                  │
+│  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐  │
+│  │ Azure Monitor OpenTelemetry Distro (Thin Wrapper)     │  │
+│  │ ┌───────────────────────────────────────────────────┐ │  │
+│  │ │     Azure Monitor OpenTelemetry Exporter          │ │  │
+│  │ └───────────────────────────────────────────────────┘ │  │
+│  │ • Sets up TracerProvider, LoggerProvider, etc.        │  │
+│  │ • Attaches Flask/Django/FastAPI/Requests instrumentors│  │
+│  │ • Reads APPLICATIONINSIGHTS_CONNECTION_STRING env var │  │
+│  │ • Detects Azure App Service/Functions/AKS metadata    │  │
+│  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │  Azure Monitor  │
+                    │  (App Insights) │
+                    └─────────────────┘
+```
+
+## Core Components
+
+### 1. Instrumentors
+Instrumentors automatically capture telemetry from libraries:
+- `FlaskInstrumentor` - Captures Flask HTTP requests
+- `DjangoInstrumentor` - Captures Django requests and middleware
+- `FastAPIInstrumentor` - Captures FastAPI/Starlette requests
+- `RequestsInstrumentor` - Captures outbound HTTP calls
+
+### 2. Providers
+Providers manage the lifecycle of telemetry:
+- **TracerProvider**: Manages trace/span creation
+- **MeterProvider**: Manages metrics collection
+- **LoggerProvider**: Manages log correlation
+
+### 3. Exporters
+Exporters send telemetry to backends:
+- **Azure Monitor Exporter**: Sends to Application Insights
+- **Console Exporter**: Prints to stdout (for debugging)
+- **OTLP Exporter**: Sends to any OTLP-compatible backend
+
+## How Azure Monitor Distro Works
+
+The `azure-monitor-opentelemetry` package simplifies setup by:
+
+1. **Auto-configuring providers** - Sets up trace, metric, and log providers
+2. **Auto-instrumenting** - Enables bundled instrumentations automatically
+3. **Configuring export** - Sets up the Azure Monitor exporter
+4. **Resource detection** - Detects Azure resource metadata
+
+### One-Line Setup
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+
+configure_azure_monitor()  # That's it!
+```
+
+This replaces what would otherwise be 50+ lines of manual configuration.
+
+## Signal Types
+
+### Traces
+Distributed traces track requests across services:
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+with tracer.start_as_current_span("my-operation") as span:
+    span.set_attribute("user.id", user_id)
+    # ... operation code
+```
+
+### Metrics
+Metrics capture aggregated measurements:
+```python
+from opentelemetry import metrics
+
+meter = metrics.get_meter(__name__)
+request_counter = meter.create_counter("requests")
+
+request_counter.add(1, {"endpoint": "/api/users"})
+```
+
+### Logs
+Logs are correlated with traces:
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+logger.info("Processing request")  # Automatically correlated with active span
+```
+
+## Context Propagation
+
+OpenTelemetry automatically propagates trace context:
+- Across HTTP calls (via W3C Trace Context headers)
+- Between services (distributed tracing)
+- To logs (correlation IDs)
+
+## Sampling
+
+Control telemetry volume with sampling:
+
+```bash
+# Sample 10% of traces
+export OTEL_TRACES_SAMPLER=traceidratio
+export OTEL_TRACES_SAMPLER_ARG=0.1
+```
+
+## Best Practices
+
+1. **Initialize First**: Configure OpenTelemetry before importing instrumented libraries
+2. **Use Semantic Conventions**: Follow OpenTelemetry naming standards for attributes
+3. **Enrich Spans**: Add business context via custom attributes
+4. **Handle Errors**: Record exceptions on spans for better debugging
+5. **Configure Sampling**: Balance observability needs with costs
+
+## Links
+
+- [OpenTelemetry Python Documentation](https://opentelemetry.io/docs/instrumentation/python/)
+- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
+- [Azure Monitor OpenTelemetry](https://learn.microsoft.com/azure/azure-monitor/app/opentelemetry-overview)

package/dist/Instrumentation/Resources/examples/dotnet/aspnet-classic-setup.md

@@ -0,0 +1,80 @@
+---
+title: Classic ASP.NET Setup
+category: examples
+applies-to: dotnet-framework
+---
+
+# Classic ASP.NET — Application Insights Setup
+
+## Prerequisites
+
+- .NET Framework 4.6.2+ project (ASP.NET MVC, WebForms, or generic ASP.NET)
+- Visual Studio or MSBuild for building
+
+## Step 1 — Install the NuGet package
+
+In Visual Studio, open the **Package Manager Console** (View → Other Windows → Package Manager Console) and run:
+
+```
+Install-Package Microsoft.ApplicationInsights.Web
+```
+
+This automatically:
+- Creates `ApplicationInsights.config` with default 3.x settings
+- Adds `ApplicationInsightsHttpModule` and `TelemetryHttpModule` to `Web.config`
+- Adds all required assembly references to the project
+- Updates `packages.config`
+
+## Step 2 — Set connection string
+
+In `ApplicationInsights.config`, replace the placeholder `<ConnectionString>` with your actual connection string:
+
+```xml
+<ConnectionString>InstrumentationKey=your-key;IngestionEndpoint=https://dc.applicationinsights.azure.com/</ConnectionString>
+```
+
+Or set the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable.
+
+## Step 3 — Run and verify
+
+1. Build and run the application (F5 in Visual Studio)
+2. Make a few HTTP requests
+3. Check Azure Portal → Application Insights → Live Metrics to see incoming telemetry
+4. Check Transaction Search for request and dependency data
+
+## What's collected automatically
+
+- All incoming HTTP requests (path, status code, duration)
+- SQL and HTTP outgoing dependency calls
+- Unhandled exceptions
+- Performance counters (CPU, memory, request rate)
+- Live Metrics stream
+
+## Optional: Custom telemetry
+
+To track custom events or metrics, use `TelemetryClient`:
+
+```csharp
+var client = new TelemetryClient(TelemetryConfiguration.CreateDefault());
+client.TrackEvent("OrderCreated");
+client.TrackMetric("ProcessingTime", elapsed);
+```
+
+## Optional: Custom processors
+
+In `Global.asax.cs`:
+
+```csharp
+protected void Application_Start()
+{
+    var config = TelemetryConfiguration.CreateDefault();
+    config.ConnectionString = "InstrumentationKey=...;IngestionEndpoint=...";
+    config.ConfigureOpenTelemetryBuilder(otel =>
+    {
+        otel.WithTracing(tracing => tracing.AddProcessor<MyCustomProcessor>());
+    });
+
+    AreaRegistration.RegisterAllAreas();
+    RouteConfig.RegisterRoutes(RouteTable.Routes);
+}
+```