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

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

@@ -0,0 +1,169 @@
+# Basic Azure Monitor Setup for Express.js
+
+This guide shows how to add Azure Monitor OpenTelemetry to an Express.js application.
+
+## Prerequisites
+
+- Node.js 14.x or higher
+- npm or yarn
+- Express.js application
+- 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
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  }
+});
+
+// Now load your application code
+const express = require('express');
+const app = express();
+const port = process.env.PORT || 3000;
+
+// Your middleware and routes
+app.use(express.json());
+
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello World!' });
+});
+
+app.get('/api/users', (req, res) => {
+  // This request will be automatically tracked
+  res.json([{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]);
+});
+
+app.listen(port, () => {
+  console.log(`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://...
+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
+```
+
+## Step 4: Add Custom Telemetry (Optional)
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+app.get('/api/process', async (req, res) => {
+  const span = trace.getActiveSpan();
+  
+  // Add custom attributes
+  span?.setAttribute('user.id', req.headers['user-id']);
+  span?.setAttribute('operation.type', 'data-processing');
+  
+  try {
+    // Your business logic
+    const result = await processData();
+    res.json(result);
+  } catch (error) {
+    // Exceptions are automatically tracked
+    span?.recordException(error);
+    res.status(500).json({ error: 'Processing failed' });
+  }
+});
+```
+
+## What Gets Tracked Automatically
+
+✅ **HTTP Requests**: All incoming requests with duration, status, URL  
+✅ **Dependencies**: Outgoing HTTP calls, database queries  
+✅ **Exceptions**: Unhandled errors and exceptions  
+✅ **Performance**: Response times and request counts  
+✅ **Custom Logs**: `console.log()` statements are captured as traces
+
+## Verify It Works
+
+1. Start your application:
+   ```bash
+   npm start
+   ```
+
+2. Make some HTTP requests:
+   ```bash
+   curl http://localhost:3000/
+   curl http://localhost:3000/api/users
+   ```
+
+3. Check Azure Portal:
+   - Navigate to your Application Insights resource
+   - Go to "Transaction search" or "Live Metrics"
+   - You should see requests appearing within 1-2 minutes
+
+## Complete package.json Example
+
+```json
+{
+  "name": "express-azure-monitor-demo",
+  "version": "1.0.0",
+  "description": "Express app with Azure Monitor",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "dev": "nodemon index.js"
+  },
+  "dependencies": {
+    "@azure/monitor-opentelemetry": "^1.0.0",
+    "express": "^4.18.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}
+```
+
+## Troubleshooting
+
+**No telemetry appearing?**
+- Verify connection string is correct
+- Ensure `useAzureMonitor()` is called BEFORE loading Express
+- Check console for error messages
+- Wait 2-3 minutes for initial data to appear
+
+**Performance impact?**
+- Azure Monitor has minimal overhead (<5% in most cases)
+- Use sampling for high-traffic applications
+- Disable in development if needed
+
+## Next Steps
+
+- Configure custom dimensions and metrics
+- Set up alerts and dashboards in Azure Portal
+- Enable profiler for performance analysis
+- Add distributed tracing across microservices

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

@@ -0,0 +1,237 @@
+# Basic Azure Monitor Setup for Fastify
+
+This guide shows how to add Azure Monitor OpenTelemetry to a Fastify application.
+
+## Prerequisites
+
+- Node.js 18.x or higher
+- npm or yarn
+- Fastify application
+- Azure Application Insights resource
+
+## Step 1: Install Package
+
+```bash
+npm install @azure/monitor-opentelemetry
+```
+
+## Step 2: Initialize at Startup
+
+Update your main entry point (typically `index.js`, `server.js`, or `app.js`):
+
+```javascript
+// IMPORTANT: This must be the first line, before any other imports
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+
+// Enable Azure Monitor integration - must be called before other requires
+useAzureMonitor({
+    azureMonitorExporterOptions: {
+        connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+    }
+});
+
+// Now load your application code
+const fastify = require('fastify')({ logger: true });
+
+// Register routes
+fastify.get('/', async (request, reply) => {
+    return { message: 'Hello World!' };
+});
+
+fastify.get('/api/users', async (request, reply) => {
+    // This request will be automatically tracked
+    return [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' }
+    ];
+});
+
+// Start server
+const start = async () => {
+    try {
+        await fastify.listen({ port: process.env.PORT || 3000 });
+    } catch (err) {
+        fastify.log.error(err);
+        process.exit(1);
+    }
+};
+
+start();
+```
+
+> **Important**: `useAzureMonitor()` must be called before requiring Fastify or any other modules to ensure proper instrumentation.
+
+## 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://...
+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
+```
+
+## Step 4: Add Custom Telemetry (Optional)
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+fastify.get('/api/process/:id', async (request, reply) => {
+    const span = trace.getActiveSpan();
+    
+    // Add custom attributes to the current span
+    span?.setAttribute('process.id', request.params.id);
+    span?.setAttribute('operation.type', 'data-processing');
+    
+    try {
+        // Your business logic
+        const result = await processData(request.params.id);
+        return result;
+    } catch (error) {
+        // Exceptions are automatically tracked
+        span?.recordException(error);
+        reply.status(500).send({ error: 'Processing failed' });
+    }
+});
+```
+
+## Using with TypeScript
+
+For TypeScript projects, create your entry file:
+
+```typescript
+// IMPORTANT: This must be the first import
+import { useAzureMonitor } from '@azure/monitor-opentelemetry';
+
+useAzureMonitor({
+    azureMonitorExporterOptions: {
+        connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+    }
+});
+
+import Fastify from 'fastify';
+
+const fastify = Fastify({ logger: true });
+
+fastify.get('/', async () => {
+    return { message: 'Hello World!' };
+});
+
+fastify.listen({ port: 3000 });
+```
+
+## What Gets Tracked Automatically
+
+✅ **HTTP Requests**: All incoming requests with duration, status, URL  
+✅ **Dependencies**: Outgoing HTTP calls, database queries  
+✅ **Exceptions**: Unhandled errors and exceptions  
+✅ **Performance**: Response times and request counts  
+✅ **Custom Logs**: Fastify logger output is captured as traces
+
+## Using with Fastify Plugins
+
+Azure Monitor works seamlessly with Fastify plugins:
+
+```javascript
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+useAzureMonitor({
+    azureMonitorExporterOptions: {
+        connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+    }
+});
+
+const fastify = require('fastify')({ logger: true });
+
+// Register plugins - they will be automatically instrumented
+fastify.register(require('@fastify/postgres'), {
+    connectionString: process.env.DATABASE_URL
+});
+
+fastify.register(require('@fastify/redis'), {
+    host: process.env.REDIS_HOST
+});
+
+// Routes using the plugins
+fastify.get('/users', async (request, reply) => {
+    const { rows } = await fastify.pg.query('SELECT * FROM users');
+    return rows;
+});
+```
+
+## Verify It Works
+
+1. Start your application:
+   ```bash
+   npm start
+   ```
+
+2. Make some HTTP requests:
+   ```bash
+   curl http://localhost:3000/
+   curl http://localhost:3000/api/users
+   ```
+
+3. Check Azure Portal:
+   - Navigate to your Application Insights resource
+   - Go to "Transaction search" or "Live Metrics"
+   - You should see requests appearing within 1-2 minutes
+
+## Complete package.json Example
+
+```json
+{
+  "name": "fastify-azure-monitor-demo",
+  "version": "1.0.0",
+  "description": "Fastify app with Azure Monitor",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "dev": "nodemon index.js"
+  },
+  "dependencies": {
+    "@azure/monitor-opentelemetry": "^1.0.0",
+    "fastify": "^4.24.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}
+```
+
+## Troubleshooting
+
+**No telemetry appearing?**
+- Verify connection string is correct
+- Ensure `useAzureMonitor()` is called BEFORE requiring Fastify
+- Check console for error messages
+- Wait 2-3 minutes for initial data to appear
+
+**Fastify logger not working with telemetry?**
+- Both work independently; Fastify logs go to stdout, telemetry goes to Azure
+- Use `@opentelemetry/api` for custom spans within telemetry
+
+**Performance impact?**
+- Azure Monitor has minimal overhead (<5% in most cases)
+- Use sampling for high-traffic applications
+- Disable in development if needed
+
+## Next Steps
+
+- Configure custom dimensions and metrics
+- Set up alerts and dashboards in Azure Portal
+- Enable profiler for performance analysis
+- Add distributed tracing across microservices

package/dist/Instrumentation/Resources/examples/nodejs/langchain-js-setup.md

@@ -0,0 +1,310 @@
+# Basic Azure Monitor Setup for LangChain.js
+
+This guide shows how to add Azure Monitor OpenTelemetry to a LangChain.js application for observability into LLM calls, chains, and agents.
+
+## Prerequisites
+
+- Node.js 18.x or higher
+- npm or yarn
+- LangChain.js application
+- Azure Application Insights resource
+
+## Step 1: Install Package
+
+```bash
+npm install @azure/monitor-opentelemetry
+```
+
+## Step 2: Create Tracing File
+
+Create a separate tracing file to ensure OpenTelemetry initializes before LangChain imports. This is critical for proper instrumentation.
+
+**For CommonJS projects** - create `tracing.js`:
+
+```javascript
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+
+// Enable Azure Monitor integration
+// This must be called before any other imports to ensure proper instrumentation
+useAzureMonitor({
+    azureMonitorExporterOptions: {
+        connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+    }
+});
+```
+
+**For ES Module projects** - create `tracing.mjs`:
+
+```javascript
+import { useAzureMonitor } from '@azure/monitor-opentelemetry';
+
+// Enable Azure Monitor integration
+// This must be called before any other imports to ensure proper instrumentation
+useAzureMonitor({
+    azureMonitorExporterOptions: {
+        connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+    }
+});
+```
+
+## Step 3: Import Tracing First
+
+Update your main entry point to import tracing **as the very first line**:
+
+**For CommonJS** (`index.js`):
+
+```javascript
+require('./tracing'); // MUST be the first import
+
+const { ChatOpenAI } = require('@langchain/openai');
+const { PromptTemplate } = require('@langchain/core/prompts');
+const { StringOutputParser } = require('@langchain/core/output_parsers');
+
+// Your LangChain application code
+async function main() {
+    const model = new ChatOpenAI({
+        modelName: 'gpt-4',
+        temperature: 0.7
+    });
+
+    const prompt = PromptTemplate.fromTemplate(
+        'Tell me a short joke about {topic}'
+    );
+
+    const chain = prompt.pipe(model).pipe(new StringOutputParser());
+
+    const result = await chain.invoke({ topic: 'programming' });
+    console.log(result);
+}
+
+main().catch(console.error);
+```
+
+**For ES Modules** (`index.mjs`):
+
+```javascript
+import './tracing.mjs'; // MUST be the first import
+
+import { ChatOpenAI } from '@langchain/openai';
+import { PromptTemplate } from '@langchain/core/prompts';
+import { StringOutputParser } from '@langchain/core/output_parsers';
+
+// Your LangChain application code
+async function main() {
+    const model = new ChatOpenAI({
+        modelName: 'gpt-4',
+        temperature: 0.7
+    });
+
+    const prompt = PromptTemplate.fromTemplate(
+        'Tell me a short joke about {topic}'
+    );
+
+    const chain = prompt.pipe(model).pipe(new StringOutputParser());
+
+    const result = await chain.invoke({ topic: 'programming' });
+    console.log(result);
+}
+
+main().catch(console.error);
+```
+
+## Step 4: Configure Connection String
+
+Create a `.env` file in your project root:
+
+```env
+APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://...
+OPENAI_API_KEY=your-openai-key
+```
+
+Install `dotenv` to load environment variables:
+
+```bash
+npm install dotenv
+```
+
+Update your tracing file to load environment variables first:
+
+```javascript
+require('dotenv').config();
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+// ... rest of tracing setup
+```
+
+## Step 5: Add Custom Telemetry (Optional)
+
+Track custom attributes for LLM operations:
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+async function processWithTelemetry(userQuery) {
+    const span = trace.getActiveSpan();
+    
+    // Add custom attributes
+    span?.setAttribute('llm.query.length', userQuery.length);
+    span?.setAttribute('llm.model', 'gpt-4');
+    span?.setAttribute('operation.type', 'chat-completion');
+    
+    try {
+        const result = await chain.invoke({ query: userQuery });
+        
+        // Track response metrics
+        span?.setAttribute('llm.response.length', result.length);
+        span?.setAttribute('llm.success', true);
+        
+        return result;
+    } catch (error) {
+        span?.recordException(error);
+        span?.setAttribute('llm.success', false);
+        throw error;
+    }
+}
+```
+
+## What Gets Tracked Automatically
+
+✅ **HTTP Requests**: Outgoing calls to LLM APIs (OpenAI, Azure OpenAI, etc.)  
+✅ **Dependencies**: External service calls and database queries  
+✅ **Exceptions**: Errors from LLM providers, rate limits, timeouts  
+✅ **Performance**: Latency of LLM calls and chains  
+✅ **Token Usage**: When using supported providers
+
+## Using with Different LLM Providers
+
+### Azure OpenAI
+
+```javascript
+const { AzureChatOpenAI } = require('@langchain/openai');
+
+const model = new AzureChatOpenAI({
+    azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_DEPLOYMENT,
+    azureOpenAIApiVersion: '2024-02-15-preview',
+});
+```
+
+### Anthropic Claude
+
+```javascript
+const { ChatAnthropic } = require('@langchain/anthropic');
+
+const model = new ChatAnthropic({
+    modelName: 'claude-3-opus-20240229',
+});
+```
+
+## Using with Agents
+
+```javascript
+require('./tracing');
+
+const { ChatOpenAI } = require('@langchain/openai');
+const { AgentExecutor, createOpenAIToolsAgent } = require('langchain/agents');
+const { TavilySearchResults } = require('@langchain/community/tools/tavily_search');
+const { trace } = require('@opentelemetry/api');
+
+async function runAgent(input) {
+    const span = trace.getActiveSpan();
+    span?.setAttribute('agent.input', input);
+    
+    const tools = [new TavilySearchResults()];
+    const model = new ChatOpenAI({ modelName: 'gpt-4' });
+    
+    const agent = await createOpenAIToolsAgent({ llm: model, tools, prompt });
+    const executor = new AgentExecutor({ agent, tools });
+    
+    const result = await executor.invoke({ input });
+    
+    span?.setAttribute('agent.steps', result.intermediateSteps?.length || 0);
+    return result;
+}
+```
+
+## Verify It Works
+
+1. Start your application:
+   ```bash
+   node index.js
+   ```
+
+2. Run some LLM operations and check Azure Portal:
+   - Navigate to your Application Insights resource
+   - Go to "Transaction search" or "Application map"
+   - You should see outgoing requests to LLM APIs
+   - Check "Dependencies" to see LLM call latencies
+
+## Complete package.json Example
+
+**CommonJS:**
+```json
+{
+  "name": "langchain-azure-monitor-demo",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@azure/monitor-opentelemetry": "^1.0.0",
+    "@langchain/core": "^0.2.0",
+    "@langchain/openai": "^0.2.0",
+    "dotenv": "^16.0.0"
+  }
+}
+```
+
+**ES Modules:**
+```json
+{
+  "name": "langchain-azure-monitor-demo",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.mjs",
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "dependencies": {
+    "@azure/monitor-opentelemetry": "^1.0.0",
+    "@langchain/core": "^0.2.0",
+    "@langchain/openai": "^0.2.0",
+    "dotenv": "^16.0.0"
+  }
+}
+```
+
+## Project Structure
+
+```
+my-langchain-app/
+├── tracing.js          ← Azure Monitor setup (load first)
+├── index.js            ← Main entry point
+├── chains/
+│   └── qa-chain.js     ← Your LangChain chains
+├── .env                ← Connection strings and API keys
+└── package.json
+```
+
+## Troubleshooting
+
+**No telemetry appearing?**
+- Verify the tracing import is the FIRST line in your entry file
+- Check that connection string is correct
+- Ensure `dotenv.config()` is called in tracing file before `useAzureMonitor()`
+
+**LLM calls not tracked?**
+- Make sure OpenTelemetry initializes BEFORE importing LangChain
+- HTTP instrumentation should capture LLM API calls automatically
+
+**ES Module vs CommonJS issues?**
+- Check your `package.json` for `"type": "module"`
+- Use `.mjs` extension for ES modules or `.cjs` for CommonJS
+- Match import/require syntax to your module system
+
+## Next Steps
+
+- Add custom metrics for token usage and costs
+- Set up alerts for LLM error rates or latency
+- Create dashboards for LLM operation insights
+- Enable distributed tracing for multi-service architectures
+- Track RAG pipeline performance with custom spans