@azure/mcp-linux-arm64 2.0.0-beta.9 → 2.0.0

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

@@ -0,0 +1,218 @@
+# Basic Azure Monitor Setup for Flask
+
+This guide shows how to add Azure Monitor OpenTelemetry to a Flask application.
+
+## Prerequisites
+
+- Python 3.8 or higher
+- Flask application
+- Azure Application Insights resource
+
+## Step 1: Install Packages
+
+```bash
+pip install azure-monitor-opentelemetry flask
+```
+
+Or add to your `requirements.txt`:
+```
+azure-monitor-opentelemetry
+flask
+```
+
+## Step 2: Initialize at Startup
+
+Update your main application file (e.g., `app.py`):
+
+```python
+# IMPORTANT: Configure Azure Monitor BEFORE importing Flask
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+# Now import Flask
+from flask import Flask, jsonify, request
+
+app = Flask(__name__)
+
+@app.route('/')
+def hello():
+    return jsonify({"message": "Hello, World!"})
+
+@app.route('/api/users')
+def get_users():
+    # This request is automatically tracked
+    return jsonify([
+        {"id": 1, "name": "Alice"},
+        {"id": 2, "name": "Bob"}
+    ])
+
+if __name__ == '__main__':
+    app.run(debug=True)
+```
+
+## Step 3: Configure Connection String
+
+Create a `.env` file:
+```env
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...
+FLASK_ENV=development
+```
+
+Load environment variables:
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+from flask import Flask
+# ... rest of your app
+```
+
+## What Gets Auto-Instrumented
+
+The Azure Monitor Distro automatically captures:
+- ✅ All HTTP requests to your Flask routes
+- ✅ Request duration, status codes, and paths
+- ✅ Exceptions and error details
+- ✅ Outbound HTTP calls (requests, urllib3)
+- ✅ Database queries (psycopg2 for PostgreSQL)
+
+## Step 4: Add Custom Telemetry (Optional)
+
+```python
+from flask import Flask, jsonify
+from opentelemetry import trace
+
+app = Flask(__name__)
+tracer = trace.get_tracer(__name__)
+
+@app.route('/api/orders/<order_id>')
+def get_order(order_id):
+    # Add custom span for business logic
+    with tracer.start_as_current_span("fetch-order") as span:
+        span.set_attribute("order.id", order_id)
+        
+        # Simulate database fetch
+        order = fetch_order_from_db(order_id)
+        
+        span.set_attribute("order.status", order.get("status"))
+        return jsonify(order)
+
+@app.route('/api/process', methods=['POST'])
+def process_data():
+    span = trace.get_active_span()
+    
+    # Add context to current request span
+    span.set_attribute("user.id", request.headers.get("X-User-ID"))
+    span.set_attribute("request.size", len(request.data))
+    
+    try:
+        result = do_processing(request.json)
+        return jsonify(result)
+    except Exception as e:
+        span.record_exception(e)
+        return jsonify({"error": str(e)}), 500
+```
+
+## Step 5: Add Logging Integration
+
+```python
+import logging
+from flask import Flask
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = Flask(__name__)
+
+@app.route('/api/users/<user_id>')
+def get_user(user_id):
+    logger.info(f"Fetching user {user_id}")  # Correlated with trace
+    
+    user = fetch_user(user_id)
+    
+    if not user:
+        logger.warning(f"User {user_id} not found")
+        return jsonify({"error": "Not found"}), 404
+    
+    logger.info(f"Found user {user_id}")
+    return jsonify(user)
+```
+
+## Complete Example
+
+```python
+# app.py
+import os
+import logging
+from dotenv import load_dotenv
+
+# Load environment variables first
+load_dotenv()
+
+# Configure Azure Monitor BEFORE importing Flask
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+# Now import Flask and other dependencies
+from flask import Flask, jsonify, request
+from opentelemetry import trace
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Create Flask app
+app = Flask(__name__)
+tracer = trace.get_tracer(__name__)
+
+@app.route('/')
+def index():
+    logger.info("Index page accessed")
+    return jsonify({"status": "healthy"})
+
+@app.route('/api/items')
+def list_items():
+    with tracer.start_as_current_span("list-items") as span:
+        items = [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]
+        span.set_attribute("items.count", len(items))
+        return jsonify(items)
+
+@app.errorhandler(Exception)
+def handle_error(error):
+    logger.error(f"Unhandled error: {error}")
+    return jsonify({"error": "Internal server error"}), 500
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=5000)
+```
+
+## Running the Application
+
+```bash
+# Set connection string
+export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=..."
+
+# Run Flask
+python app.py
+```
+
+Or with Flask CLI:
+```bash
+flask run
+```
+
+## Verification
+
+1. Make requests to your Flask endpoints
+2. Go to Azure Portal → Application Insights
+3. Check "Transaction search" for your requests
+4. View "Application map" for dependencies
+
+## Links
+
+- [Flask Documentation](https://flask.palletsprojects.com/)
+- [Azure Monitor Python](https://learn.microsoft.com/azure/azure-monitor/app/opentelemetry-enable?tabs=python)

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

@@ -0,0 +1,214 @@
+# Basic Azure Monitor Setup for GenAI Applications
+
+This guide shows how to add Azure Monitor OpenTelemetry to applications using GenAI libraries like OpenAI, LangChain, or Anthropic.
+
+## Prerequisites
+
+- Python 3.8 or higher
+- GenAI library (openai, langchain, anthropic, etc.)
+- Azure Application Insights resource
+
+## Step 1: Install Packages
+
+For OpenAI applications:
+```bash
+pip install azure-monitor-opentelemetry openai opentelemetry-instrumentation-openai
+```
+
+For LangChain applications:
+```bash
+pip install azure-monitor-opentelemetry langchain opentelemetry-instrumentation-langchain
+```
+
+For Anthropic applications:
+```bash
+pip install azure-monitor-opentelemetry anthropic opentelemetry-instrumentation-anthropic
+```
+
+Or add to your `requirements.txt`:
+```
+azure-monitor-opentelemetry>=1.8.3
+openai
+opentelemetry-instrumentation-openai
+```
+
+## Step 2: Initialize at Startup
+
+Update your main application file (e.g., `app.py`):
+
+```python
+# IMPORTANT: Configure Azure Monitor BEFORE importing GenAI libraries
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+# Now import your GenAI libraries
+from openai import OpenAI
+
+client = OpenAI()
+
+def generate_completion(prompt: str):
+    """Generate a completion - automatically traced by Azure Monitor."""
+    response = client.chat.completions.create(
+        model="gpt-4",
+        messages=[
+            {"role": "system", "content": "You are a helpful assistant."},
+            {"role": "user", "content": prompt}
+        ]
+    )
+    return response.choices[0].message.content
+
+if __name__ == "__main__":
+    result = generate_completion("What is the capital of France?")
+    print(f"Response: {result}")
+```
+
+## Step 3: Configure Connection String
+
+Create a `.env` file:
+```env
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...
+OPENAI_API_KEY=sk-...
+```
+
+Load environment variables:
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+from openai import OpenAI
+# ... rest of your app
+```
+
+## What Gets Auto-Instrumented
+
+The Azure Monitor Distro with GenAI instrumentations automatically captures:
+- ✅ All LLM API calls (OpenAI, Anthropic, etc.)
+- ✅ Request duration and latency
+- ✅ Token usage (prompt tokens, completion tokens, total)
+- ✅ Model names and parameters (temperature, max_tokens, etc.)
+- ✅ Prompt and completion content (configurable)
+- ✅ Error details and exceptions
+- ✅ Chain execution in LangChain applications
+- ✅ Agent interactions and tool calls
+
+## Advanced: Custom Tracing
+
+Add custom spans for business logic:
+
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+def process_user_query(user_id: str, query: str):
+    with tracer.start_as_current_span("process_query") as span:
+        span.set_attribute("user.id", user_id)
+        span.set_attribute("query.length", len(query))
+        
+        # Your LLM call is automatically traced as a child span
+        response = generate_completion(query)
+        
+        span.set_attribute("response.length", len(response))
+        return response
+```
+
+## Supported GenAI Libraries
+
+| Library | Instrumentation Package | What's Traced |
+|---------|------------------------|---------------|
+| OpenAI | `opentelemetry-instrumentation-openai` | Chat completions, embeddings, fine-tuning |
+| Anthropic | `opentelemetry-instrumentation-anthropic` | Messages API, Claude models |
+| LangChain | `opentelemetry-instrumentation-langchain` | Chains, agents, tools, retrievers |
+| OpenAI Agents | `opentelemetry-instrumentation-openai-agents` | Agent runs, function calls |
+
+## Example: LangChain Application
+
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+from langchain.chat_models import ChatOpenAI
+from langchain.chains import LLMChain
+from langchain.prompts import PromptTemplate
+
+llm = ChatOpenAI(model="gpt-4")
+template = PromptTemplate(
+    input_variables=["topic"],
+    template="Tell me a joke about {topic}"
+)
+chain = LLMChain(llm=llm, prompt=template)
+
+# This entire chain execution is traced
+result = chain.run(topic="programming")
+print(result)
+```
+
+## Example: OpenAI Agents
+
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+from openai import OpenAI
+from openai_agents import Agent, function_tool
+
+@function_tool
+def get_weather(location: str) -> dict:
+    """Get weather for a location."""
+    return {"location": location, "temperature": 72}
+
+agent = Agent(
+    name="Weather Assistant",
+    instructions="You are a helpful weather assistant.",
+    tools=[get_weather],
+    model="gpt-4"
+)
+
+# Agent runs and tool calls are automatically traced
+response = agent.run("What's the weather in San Francisco?")
+print(response)
+```
+
+## Configuration Options
+
+### Disable Content Logging
+
+To avoid logging prompt/completion content (for privacy):
+
+```python
+import os
+os.environ["OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"] = "openai-v2"
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+```
+
+### Control Sampling
+
+To sample only 10% of traces (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()
+```
+
+## Viewing Telemetry
+
+Once configured, view your GenAI telemetry in Azure Portal:
+1. Go to your Application Insights resource
+2. Navigate to **Performance** → **Dependencies** to see LLM calls
+3. Check **Transaction search** for individual requests
+4. Use **Application Map** to visualize your application topology
+5. Create custom dashboards to track token usage and costs
+
+## Next Steps
+
+- OpenTelemetry Pipeline Concepts(see in opentelemetry-pipeline-python.md)
+- Azure Monitor Python Overview(see in azure-monitor-python.md)

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

@@ -0,0 +1,164 @@
+# Basic Azure Monitor Setup for Python
+
+This guide shows how to add Azure Monitor OpenTelemetry to a Python application.
+
+## Prerequisites
+
+- Python 3.8 or higher
+- pip
+- Azure Application Insights resource
+
+## Step 1: Install Package
+
+```bash
+pip install azure-monitor-opentelemetry
+```
+
+Or add to your `requirements.txt`:
+```
+azure-monitor-opentelemetry
+```
+
+## Step 2: Initialize at Startup
+
+Add the following to your application entry point:
+
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+
+# Configure Azure Monitor - MUST be called before importing other libraries
+configure_azure_monitor()
+
+# Now import your application code
+# ...
+```
+
+## Step 3: Configure Connection String
+
+### Option A: Environment Variable (Recommended)
+
+```bash
+export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://..."
+```
+
+### Option B: .env File
+
+Create a `.env` file:
+```env
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...
+```
+
+Load it with python-dotenv:
+```bash
+pip install python-dotenv
+```
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+```
+
+### Option C: Direct Configuration
+
+```python
+from azure.monitor.opentelemetry import configure_azure_monitor
+
+configure_azure_monitor(
+    connection_string="InstrumentationKey=..."
+)
+```
+
+## Step 4: Optional Configuration
+
+### Service Name
+```bash
+export OTEL_SERVICE_NAME="my-python-app"
+```
+
+### Resource Attributes
+```bash
+export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.version=1.0.0"
+```
+
+### Sampling
+```bash
+export OTEL_TRACES_SAMPLER=traceidratio
+export OTEL_TRACES_SAMPLER_ARG=0.1  # 10% sampling
+```
+
+## Step 5: Add Custom Telemetry (Optional)
+
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+def process_order(order_id: str):
+    with tracer.start_as_current_span("process-order") as span:
+        span.set_attribute("order.id", order_id)
+        
+        try:
+            # Your business logic
+            result = do_processing(order_id)
+            span.set_attribute("order.status", "completed")
+            return result
+        except Exception as e:
+            span.record_exception(e)
+            span.set_attribute("order.status", "failed")
+            raise
+```
+
+## Verification
+
+After setup, you should see telemetry in Azure Portal:
+1. Navigate to your Application Insights resource
+2. Go to "Transaction search" or "Live Metrics"
+3. Make some requests to your application
+4. Verify data appears within a few minutes
+
+## Complete Example
+
+```python
+# app.py
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Configure Azure Monitor FIRST
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor()
+
+# Now import and run your application
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def main():
+    logger.info("Application started")
+    # Your application logic here
+    logger.info("Application finished")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Troubleshooting
+
+### No Data in Azure Portal
+1. Verify connection string is correct
+2. Check for firewall/proxy blocking outbound HTTPS
+3. Enable debug logging: `export OTEL_LOG_LEVEL=debug`
+
+### Import Order Issues
+Ensure `configure_azure_monitor()` is called before importing instrumented libraries.
+
+## Links
+
+- [Azure Monitor OpenTelemetry](https://learn.microsoft.com/azure/azure-monitor/app/opentelemetry-enable?tabs=python)
+- [Troubleshooting Guide](https://learn.microsoft.com/troubleshoot/azure/azure-monitor/app-insights/telemetry/opentelemetry-troubleshooting-python)