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

package/dist/Instrumentation/Resources/examples/nodejs/winston-setup.md

@@ -0,0 +1,260 @@
+# Basic Azure Monitor Setup for Node.js with Winston Logging
+
+This guide shows how to add Azure Monitor OpenTelemetry to a Node.js application using Winston for logging.
+
+## Prerequisites
+
+- Node.js 14.x or higher
+- npm or yarn
+- Node.js application with Winston (`winston` package)
+- Azure Application Insights resource
+
+## Step 1: Install Package
+
+```bash
+npm install @azure/monitor-opentelemetry
+```
+
+## Step 2: Initialize at Startup
+
+Create or update your main entry point (typically `index.js` or `server.js`):
+
+```javascript
+// IMPORTANT: This must be the first line, before any other imports
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+
+// Initialize Azure Monitor with Winston log collection enabled
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  },
+  instrumentationOptions: {
+    winston: { enabled: true }
+  }
+});
+
+// Now load your application code
+const express = require('express');
+const winston = require('winston');
+
+// Create Winston logger
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  defaultMeta: { service: 'my-app' },
+  transports: [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      )
+    })
+  ]
+});
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+app.use(express.json());
+
+// Request logging middleware
+app.use((req, res, next) => {
+  logger.info('Incoming request', {
+    method: req.method,
+    path: req.path
+  });
+  next();
+});
+
+app.get('/api/users', (req, res) => {
+  logger.info('Fetching users');
+  res.json([{ id: 1, name: 'Alice' }]);
+});
+
+app.listen(port, () => {
+  logger.info(`Server listening on port ${port}`);
+});
+```
+
+## Step 3: Configure Connection String
+
+Create a `.env` file in your project root:
+
+```env
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...
+LOG_LEVEL=info
+PORT=3000
+```
+
+Install `dotenv` to load environment variables:
+
+```bash
+npm install dotenv
+```
+
+Load it at the very top of your entry file:
+
+```javascript
+require('dotenv').config();
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+// ... rest of code
+```
+
+## What Gets Collected
+
+With Winston instrumentation enabled, the following log data is sent to Azure Monitor:
+
+- **Log level**: error, warn, info, debug, etc.
+- **Log message**: The log content
+- **Metadata**: Any additional properties passed to the logger
+- **Timestamp**: When the log was created
+- **Trace context**: Correlation with distributed traces
+
+## Log Level Mapping
+
+Winston log levels are mapped to Application Insights severity levels:
+
+| Winston Level | Application Insights Severity |
+|--------------|------------------------------|
+| error | Error |
+| warn | Warning |
+| info | Information |
+| http | Information |
+| verbose | Verbose |
+| debug | Verbose |
+| silly | Verbose |
+
+## Step 4: Structured Logging Best Practices
+
+### Add Context to Logs
+
+```javascript
+// Good: Structured logging with context
+logger.info('User created', {
+  userId: user.id,
+  email: user.email,
+  action: 'create'
+});
+
+// Good: Error logging with stack trace
+logger.error('Failed to create user', {
+  error: err.message,
+  stack: err.stack,
+  email: req.body.email
+});
+```
+
+### Correlation with Requests
+
+Logs are automatically correlated with HTTP requests when using Express:
+
+```javascript
+app.get('/api/users/:id', (req, res) => {
+  // This log will be correlated with the request trace
+  logger.info('Fetching user', { userId: req.params.id });
+  
+  try {
+    const user = getUserById(req.params.id);
+    logger.debug('User found', { user });
+    res.json(user);
+  } catch (error) {
+    logger.error('User not found', { 
+      userId: req.params.id,
+      error: error.message 
+    });
+    res.status(404).json({ error: 'User not found' });
+  }
+});
+```
+
+## Step 5: Custom Telemetry (Optional)
+
+Combine logging with custom spans:
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+app.post('/api/orders', async (req, res) => {
+  const tracer = trace.getTracer('my-app');
+  
+  await tracer.startActiveSpan('create-order', async (span) => {
+    logger.info('Creating order', { items: req.body.items.length });
+    
+    try {
+      const order = await createOrder(req.body);
+      
+      logger.info('Order created successfully', {
+        orderId: order.id,
+        total: order.total
+      });
+      
+      span.setAttribute('order.id', order.id);
+      res.status(201).json(order);
+    } catch (error) {
+      logger.error('Failed to create order', {
+        error: error.message,
+        stack: error.stack
+      });
+      
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      res.status(500).json({ error: 'Failed to create order' });
+    } finally {
+      span.end();
+    }
+  });
+});
+```
+
+## Viewing Logs in Azure Portal
+
+1. Open your Application Insights resource in Azure Portal
+2. Navigate to "Logs" under Monitoring
+3. Query traces table:
+
+```kusto
+traces
+| where timestamp > ago(1h)
+| where customDimensions.service == "my-app"
+| project timestamp, message, severityLevel, customDimensions
+| order by timestamp desc
+```
+
+4. Use "Transaction search" to see logs correlated with requests
+
+## Troubleshooting
+
+### Winston logs not appearing
+
+1. Ensure `winston` instrumentation is enabled in options
+2. Verify `useAzureMonitor()` is called **before** importing `winston`
+3. Check that the connection string is valid
+
+### Too many logs being sent
+
+Control log volume by adjusting the log level:
+
+```javascript
+const logger = winston.createLogger({
+  level: process.env.NODE_ENV === 'production' ? 'warn' : 'debug',
+  // ...
+});
+```
+
+Or use sampling:
+
+```javascript
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  },
+  instrumentationOptions: {
+    winston: { enabled: true }
+  },
+  samplingRatio: 0.5 // Sample 50% of telemetry
+});
+```

package/dist/Instrumentation/Resources/examples/python/console-setup.md

@@ -0,0 +1,392 @@
+# Basic Azure Monitor Setup for Python Console/Script Applications
+
+This guide shows how to add Azure Monitor OpenTelemetry to standalone Python scripts, console applications, or background workers.
+
+## Prerequisites
+
+- Python 3.8 or higher
+- Python script or console application
+- Azure Application Insights resource
+
+## Step 1: Install Packages
+
+```bash
+pip install azure-monitor-opentelemetry>=1.8.3
+```
+
+Or add to your `requirements.txt`:
+```
+azure-monitor-opentelemetry>=1.8.3
+```
+
+## Step 2: Initialize at Startup
+
+Update your main script file (e.g., `app.py`, `main.py`):
+
+```python
+# IMPORTANT: Configure Azure Monitor at the very top
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+# Now import your other libraries
+import time
+import logging
+
+# Your application code
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def main():
+    logger.info("Application started")
+    # Your logic here
+    time.sleep(1)
+    logger.info("Application completed")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Step 3: Configure Connection String
+
+Create a `.env` file:
+```env
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...
+```
+
+Load environment variables:
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+# ... rest of your app
+```
+
+## What Gets Auto-Instrumented
+
+The Azure Monitor Distro automatically captures:
+- ✅ Basic Python logging (via logging module)
+- ✅ Exceptions and error stack traces
+- ✅ Application lifecycle events
+
+**Note**: Unlike web frameworks, console apps don't have automatic HTTP request tracing. You need to add library-specific instrumentations.
+
+## ⚠️ Important: Instrumentation Order
+
+**CRITICAL**: The correct initialization order is:
+1. Import standard libraries and your dependencies (requests, httpx, etc.) **FIRST**
+2. Configure logging with `logging.basicConfig()` **SECOND**
+3. Import and call `configure_azure_monitor()` **THIRD**
+4. Get logger with `logging.getLogger(__name__)` **FOURTH**
+5. Import and call instrumentor `.instrument()` methods **LAST**
+
+**Incorrect Order** (logs won't appear in Application Insights):
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()  # ❌ Before logging config
+logging.basicConfig(level=logging.INFO)
+LoggingInstrumentor().instrument()
+```
+
+**Correct Order** (logs will appear in Application Insights):
+```python
+import logging
+import requests
+
+logging.basicConfig(level=logging.INFO)  # ✅ 1. Configure logging after regular imports
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()  # ✅ 2. Then configure Azure Monitor
+
+logger = logging.getLogger(__name__)  # ✅ 3. Get logger after configure_azure_monitor
+
+from opentelemetry.instrumentation.logging import LoggingInstrumentor
+LoggingInstrumentor().instrument()  # ✅ 4. Finally instrument
+```
+
+This order applies to all instrumentors (HTTPXClientInstrumentor, URLLib3Instrumentor, AioHttpClientInstrumentor, AsyncioInstrumentor, etc.).
+
+## Adding Library-Specific Instrumentations
+
+### For HTTP Clients (requests, httpx, urllib3)
+
+```bash
+pip install opentelemetry-instrumentation-requests
+pip install opentelemetry-instrumentation-httpx
+```
+
+```python
+import logging
+import requests
+import httpx
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+logger = logging.getLogger(__name__)
+
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from opentelemetry.instrumentation.logging import LoggingInstrumentor
+
+RequestsInstrumentor().instrument()
+HTTPXClientInstrumentor().instrument()
+LoggingInstrumentor().instrument()
+
+# Now these calls are automatically traced
+response = requests.get("https://api.example.com/data")
+```
+
+### For Database Clients (psycopg2, pymongo, redis)
+
+```bash
+pip install opentelemetry-instrumentation-psycopg2
+pip install opentelemetry-instrumentation-pymongo
+pip install opentelemetry-instrumentation-redis
+```
+
+```python
+import logging
+import psycopg2
+
+logging.basicConfig(level=logging.INFO)
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+logger = logging.getLogger(__name__)
+
+from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
+Psycopg2Instrumentor().instrument()
+
+# Database queries are now traced
+```
+
+### For Async Operations
+
+```bash
+pip install opentelemetry-instrumentation-asyncio
+```
+
+```python
+import logging
+import asyncio
+
+logging.basicConfig(level=logging.INFO)
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+logger = logging.getLogger(__name__)
+
+from opentelemetry.instrumentation.asyncio import AsyncioInstrumentor
+AsyncioInstrumentor().instrument()
+
+# Async tasks are now traced
+```
+
+## Adding Custom Tracing
+
+Use OpenTelemetry APIs to create custom spans for your business logic:
+
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+def process_data(data):
+    with tracer.start_as_current_span("process_data") as span:
+        span.set_attribute("data.size", len(data))
+        
+        # Your processing logic
+        result = do_something(data)
+        
+        span.set_attribute("result.count", len(result))
+        return result
+
+def do_something(data):
+    # This automatically becomes a child span
+    with tracer.start_as_current_span("do_something"):
+        # Processing logic
+        return [item * 2 for item in data]
+```
+
+## Example: Complete Console Application
+
+```python
+"""Example console application with Azure Monitor."""
+from dotenv import load_dotenv
+load_dotenv()
+
+import logging
+import requests
+import time
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+logger = logging.getLogger(__name__)
+
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.instrumentation.logging import LoggingInstrumentor
+RequestsInstrumentor().instrument()
+LoggingInstrumentor().instrument()
+
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+def fetch_data(url):
+    """Fetch data from API - automatically traced."""
+    logger.info(f"Fetching data from {url}")
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()
+    return response.json()
+
+def process_batch(items):
+    """Process items with custom tracing."""
+    with tracer.start_as_current_span("process_batch") as span:
+        span.set_attribute("batch.size", len(items))
+        
+        results = []
+        for i, item in enumerate(items):
+            with tracer.start_as_current_span(f"process_item_{i}"):
+                time.sleep(0.1)  # Simulate processing
+                results.append(item * 2)
+        
+        span.set_attribute("results.count", len(results))
+        logger.info(f"Processed {len(results)} items")
+        return results
+
+def main():
+    """Main application entry point."""
+    with tracer.start_as_current_span("main") as span:
+        logger.info("Application started")
+        
+        try:
+            # Fetch data (HTTP call is auto-traced)
+            data = fetch_data("https://jsonplaceholder.typicode.com/posts")
+            span.add_event("data_fetched", {"count": len(data)})
+            
+            # Process data (custom spans)
+            results = process_batch(data[:10])
+            
+            logger.info(f"Application completed successfully. Processed {len(results)} items")
+            span.set_status(trace.Status(trace.StatusCode.OK))
+            
+        except Exception as e:
+            logger.error(f"Application failed: {e}", exc_info=True)
+            span.record_exception(e)
+            span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
+            raise
+
+if __name__ == "__main__":
+    main()
+```
+
+## Common Use Cases
+
+### Batch Processing Scripts
+```python
+with tracer.start_as_current_span("batch_job") as span:
+    span.set_attribute("job.type", "daily_report")
+    process_records()
+```
+
+### CLI Tools
+```python
+import click
+
+@click.command()
+@click.option('--input', required=True)
+def cli_tool(input):
+    with tracer.start_as_current_span("cli_execution") as span:
+        span.set_attribute("cli.input", input)
+        # Process CLI logic
+```
+
+### Background Workers
+```python
+while True:
+    with tracer.start_as_current_span("worker_iteration"):
+        process_queue()
+        time.sleep(60)
+```
+
+## Available Instrumentations
+
+| Library | Instrumentation Package | What's Traced |
+|---------|------------------------|---------------|
+| requests | `opentelemetry-instrumentation-requests` | HTTP requests |
+| httpx | `opentelemetry-instrumentation-httpx` | HTTP/2 requests |
+| urllib3 | `opentelemetry-instrumentation-urllib3` | Low-level HTTP |
+| psycopg2 | `opentelemetry-instrumentation-psycopg2` | PostgreSQL queries |
+| pymongo | `opentelemetry-instrumentation-pymongo` | MongoDB operations |
+| redis | `opentelemetry-instrumentation-redis` | Redis commands |
+| asyncio | `opentelemetry-instrumentation-asyncio` | Async tasks |
+| logging | Built-in | Log records |
+
+## Configuration Options
+
+### Control Sampling
+
+Sample only 10% of traces to reduce costs:
+
+```python
+import os
+os.environ["OTEL_TRACES_SAMPLER"] = "traceidratio"
+os.environ["OTEL_TRACES_SAMPLER_ARG"] = "0.1"
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+```
+
+### Set Service Name
+
+```python
+import os
+os.environ["OTEL_SERVICE_NAME"] = "my-batch-processor"
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+```
+
+### Add Resource Attributes
+
+```python
+import os
+os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "deployment.environment=production,service.version=1.2.3"
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+```
+
+## Viewing Telemetry
+
+Once configured, view your console app telemetry in Azure Portal:
+1. Go to your Application Insights resource
+2. Navigate to **Transaction search** for individual executions
+3. Check **Performance** for operation timing
+4. Use **Failures** to track exceptions
+5. Create custom queries in **Logs** for batch job analytics
+
+## Next Steps
+
+- OpenTelemetry Pipeline Concepts(see in opentelemetry-pipeline-python.md)
+- Azure Monitor Python Overview(see in azure-monitor-python.md)
+- [OpenTelemetry Python Documentation](https://opentelemetry.io/docs/instrumentation/python/)