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

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

@@ -0,0 +1,185 @@
+# Basic Azure Monitor Setup for Node.js with MongoDB
+
+This guide shows how to add Azure Monitor OpenTelemetry to a Node.js application using MongoDB.
+
+## Prerequisites
+
+- Node.js 14.x or higher
+- npm or yarn
+- Node.js application with MongoDB (`mongodb` 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 - MongoDB operations will be automatically instrumented
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  }
+});
+
+// Now load your application code
+const express = require('express');
+const { MongoClient } = require('mongodb');
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+// MongoDB connection
+const mongoUrl = process.env.MONGODB_URL || 'mongodb://localhost:27017';
+const dbName = process.env.MONGODB_DB || 'mydb';
+let db;
+
+async function connectToDatabase() {
+  const client = new MongoClient(mongoUrl);
+  await client.connect();
+  db = client.db(dbName);
+  console.log('Connected to MongoDB');
+}
+
+app.use(express.json());
+
+app.get('/api/users', async (req, res) => {
+  // This query will be automatically tracked as a dependency
+  const users = await db.collection('users').find({}).limit(10).toArray();
+  res.json(users);
+});
+
+connectToDatabase().then(() => {
+  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://...
+MONGODB_URL=mongodb://localhost:27017
+MONGODB_DB=mydb
+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 Instrumented Automatically
+
+With Azure Monitor OpenTelemetry, the following MongoDB operations are automatically tracked:
+
+- **Operations**: find, insert, update, delete, aggregate, etc.
+- **Operation duration**: Time taken for each database operation
+- **Collection name**: Which collection was accessed
+- **Database name**: Which database was used
+- **Success/failure**: Operation status
+
+## Step 4: Add Custom Telemetry (Optional)
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+app.post('/api/users', async (req, res) => {
+  const tracer = trace.getTracer('my-app');
+  
+  await tracer.startActiveSpan('create-user', async (span) => {
+    try {
+      span.setAttribute('user.email', req.body.email);
+      
+      const result = await db.collection('users').insertOne({
+        name: req.body.name,
+        email: req.body.email,
+        createdAt: new Date()
+      });
+      
+      span.setAttribute('user.id', result.insertedId.toString());
+      res.status(201).json({ _id: result.insertedId, ...req.body });
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      res.status(500).json({ error: 'Database error' });
+    } finally {
+      span.end();
+    }
+  });
+});
+```
+
+## Using with Mongoose
+
+If you're using Mongoose ODM, the setup is the same:
+
+```javascript
+require('dotenv').config();
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  }
+});
+
+const mongoose = require('mongoose');
+const express = require('express');
+
+// Mongoose operations will automatically be instrumented
+mongoose.connect(process.env.MONGODB_URL);
+
+const UserSchema = new mongoose.Schema({
+  name: String,
+  email: String
+});
+
+const User = mongoose.model('User', UserSchema);
+
+const app = express();
+
+app.get('/api/users', async (req, res) => {
+  const users = await User.find().limit(10);
+  res.json(users);
+});
+```
+
+## Viewing Telemetry in Azure Portal
+
+1. Open your Application Insights resource in Azure Portal
+2. Navigate to "Application Map" to see MongoDB as a dependency
+3. Use "Transaction search" to find specific database operations
+4. Check "Dependencies" under "Investigate" to see operation performance
+
+## Troubleshooting
+
+### MongoDB operations not appearing
+
+1. Ensure `useAzureMonitor()` is called **before** importing `mongodb` or `mongoose`
+2. Verify the connection string is set correctly
+3. Check that operations are being executed (not just connections)
+
+### High cardinality in telemetry
+
+MongoDB instrumentation captures collection names. For applications with dynamic collections, consider using a consistent naming pattern.

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

@@ -0,0 +1,231 @@
+# Basic Azure Monitor Setup for Node.js with MySQL
+
+This guide shows how to add Azure Monitor OpenTelemetry to a Node.js application using MySQL.
+
+## Prerequisites
+
+- Node.js 14.x or higher
+- npm or yarn
+- Node.js application with MySQL (`mysql2` 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 - MySQL queries will be automatically instrumented
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  }
+});
+
+// Now load your application code
+const express = require('express');
+const mysql = require('mysql2/promise');
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+// MySQL connection pool
+let pool;
+
+async function createPool() {
+  pool = mysql.createPool({
+    host: process.env.MYSQL_HOST || 'localhost',
+    port: process.env.MYSQL_PORT || 3306,
+    user: process.env.MYSQL_USER || 'root',
+    password: process.env.MYSQL_PASSWORD || '',
+    database: process.env.MYSQL_DATABASE || 'mydb',
+    waitForConnections: true,
+    connectionLimit: 10
+  });
+  console.log('MySQL connection pool created');
+}
+
+app.use(express.json());
+
+app.get('/api/users', async (req, res) => {
+  // This query will be automatically tracked as a dependency
+  const [rows] = await pool.execute('SELECT * FROM users LIMIT 10');
+  res.json(rows);
+});
+
+createPool().then(() => {
+  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://...
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=your_password
+MYSQL_DATABASE=mydb
+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 Instrumented Automatically
+
+With Azure Monitor OpenTelemetry, the following MySQL operations are automatically tracked:
+
+- **Queries**: All SQL queries executed via `mysql2` client
+- **Query duration**: Time taken for each database operation
+- **Query results**: Success/failure status
+- **Connection info**: Database name and server details
+
+## Step 4: Add Custom Telemetry (Optional)
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+app.post('/api/users', async (req, res) => {
+  const tracer = trace.getTracer('my-app');
+  
+  await tracer.startActiveSpan('create-user', async (span) => {
+    try {
+      span.setAttribute('user.email', req.body.email);
+      
+      const [result] = await pool.execute(
+        'INSERT INTO users (name, email) VALUES (?, ?)',
+        [req.body.name, req.body.email]
+      );
+      
+      span.setAttribute('user.id', result.insertId);
+      res.status(201).json({ id: result.insertId, ...req.body });
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: 2, message: error.message });
+      res.status(500).json({ error: 'Database error' });
+    } finally {
+      span.end();
+    }
+  });
+});
+```
+
+## Using with Azure Database for MySQL
+
+For Azure Database for MySQL, update your configuration:
+
+```env
+MYSQL_HOST=your-server.mysql.database.azure.com
+MYSQL_PORT=3306
+MYSQL_USER=your_user@your-server
+MYSQL_PASSWORD=your_password
+MYSQL_DATABASE=mydb
+```
+
+And enable SSL in your connection:
+
+```javascript
+const pool = mysql.createPool({
+  host: process.env.MYSQL_HOST,
+  port: process.env.MYSQL_PORT,
+  user: process.env.MYSQL_USER,
+  password: process.env.MYSQL_PASSWORD,
+  database: process.env.MYSQL_DATABASE,
+  ssl: {
+    rejectUnauthorized: true
+  }
+});
+```
+
+## Using with Sequelize ORM
+
+If you're using Sequelize, the setup is similar:
+
+```javascript
+require('dotenv').config();
+const { useAzureMonitor } = require('@azure/monitor-opentelemetry');
+
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  }
+});
+
+const { Sequelize, DataTypes } = require('sequelize');
+const express = require('express');
+
+const sequelize = new Sequelize(
+  process.env.MYSQL_DATABASE,
+  process.env.MYSQL_USER,
+  process.env.MYSQL_PASSWORD,
+  {
+    host: process.env.MYSQL_HOST,
+    dialect: 'mysql'
+  }
+);
+
+const User = sequelize.define('User', {
+  name: DataTypes.STRING,
+  email: DataTypes.STRING
+});
+
+const app = express();
+
+app.get('/api/users', async (req, res) => {
+  const users = await User.findAll({ limit: 10 });
+  res.json(users);
+});
+```
+
+## Viewing Telemetry in Azure Portal
+
+1. Open your Application Insights resource in Azure Portal
+2. Navigate to "Application Map" to see MySQL as a dependency
+3. Use "Transaction search" to find specific database operations
+4. Check "Dependencies" under "Investigate" to see query performance
+
+## Troubleshooting
+
+### MySQL queries not appearing
+
+1. Ensure `useAzureMonitor()` is called **before** importing `mysql2`
+2. Verify the connection string is set correctly
+3. Check that queries are being executed (not just connections)
+
+### High latency in telemetry
+
+MySQL instrumentation captures all queries. For high-throughput applications, consider:
+
+```javascript
+useAzureMonitor({
+  azureMonitorExporterOptions: {
+    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
+  },
+  samplingRatio: 0.5 // Sample 50% of requests
+});
+```

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

@@ -0,0 +1,184 @@
+# Basic Azure Monitor Setup for NestJS
+
+This guide shows how to add Azure Monitor OpenTelemetry to a NestJS application.
+
+## Prerequisites
+
+- Node.js 18.x or higher
+- npm or yarn
+- NestJS application
+- Azure Application Insights resource
+
+## Step 1: Install Package
+
+```bash
+npm install @azure/monitor-opentelemetry
+```
+
+## Step 2: Create Tracing File
+
+Create a new file `src/tracing.ts` for OpenTelemetry initialization:
+
+```typescript
+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 in main.ts
+
+Update your `src/main.ts` to import tracing **as the very first line**:
+
+```typescript
+import './tracing'; // MUST be the first import
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+> **Important**: The tracing import must be before all other imports to ensure proper instrumentation of HTTP modules and other dependencies.
+
+## 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://...
+PORT=3000
+```
+
+Install and configure `@nestjs/config` for environment variables:
+
+```bash
+npm install @nestjs/config
+```
+
+Update `app.module.ts`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+    }),
+  ],
+  // ... your other modules
+})
+export class AppModule {}
+```
+
+## Step 5: Add Custom Telemetry (Optional)
+
+```typescript
+import { Controller, Get, Param } from '@nestjs/common';
+import { trace } from '@opentelemetry/api';
+
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async findOne(@Param('id') id: string) {
+    const span = trace.getActiveSpan();
+    
+    // Add custom attributes to the current span
+    span?.setAttribute('user.id', id);
+    span?.setAttribute('operation.type', 'user-lookup');
+    
+    try {
+      const user = await this.userService.findById(id);
+      return user;
+    } catch (error) {
+      // Exceptions are automatically tracked
+      span?.recordException(error);
+      throw error;
+    }
+  }
+}
+```
+
+## What Gets Tracked Automatically
+
+✅ **HTTP Requests**: All incoming requests to your NestJS controllers  
+✅ **Dependencies**: Outgoing HTTP calls, database queries (TypeORM, Prisma, etc.)  
+✅ **Exceptions**: Unhandled errors and NestJS exceptions  
+✅ **Performance**: Response times, request counts, and latency  
+✅ **Custom Logs**: Console statements are captured as traces
+
+## Verify It Works
+
+1. Start your application:
+   ```bash
+   npm run start:dev
+   ```
+
+2. Make some HTTP requests:
+   ```bash
+   curl http://localhost:3000/
+   curl http://localhost:3000/users/1
+   ```
+
+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": "nestjs-azure-monitor-demo",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:prod": "node dist/main"
+  },
+  "dependencies": {
+    "@azure/monitor-opentelemetry": "^1.0.0",
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/config": "^3.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/platform-express": "^10.0.0",
+    "reflect-metadata": "^0.1.13",
+    "rxjs": "^7.8.0"
+  }
+}
+```
+
+## Troubleshooting
+
+**No telemetry appearing?**
+- Verify the tracing import is the FIRST line in `main.ts`
+- Check that connection string is correct
+- Ensure environment variables are loaded before `useAzureMonitor()` is called
+- Wait 2-3 minutes for initial data to appear
+
+**TypeScript compilation errors?**
+- Ensure `@types/node` is installed
+- Add `"esModuleInterop": true` to tsconfig.json if needed
+
+**Performance impact?**
+- Azure Monitor has minimal overhead (<5% in most cases)
+- Use sampling for high-traffic applications
+
+## Next Steps
+
+- Configure custom dimensions and metrics
+- Set up alerts and dashboards in Azure Portal
+- Enable distributed tracing across microservices
+- Add interceptors for custom span attributes