appinsights-instrumentation

Files (1)

• SKILL.md

SKILL.md (first lines)

# App Insights Instrumentation

Implement high-value telemetry with minimal noise and strong trace correlation for production troubleshooting and performance optimization.

## Use This Skill When

- The user needs monitoring for apps running in Azure
- The user needs distributed tracing across microservices
- The user needs alerting, dashboards, or root cause analysis visibility
- The user wants to migrate from custom logging to structured telemetry

## Context: Observability Maturity

**Immature**: No monitoring, errors discovered by users  
**Developing**: Logs and metrics collected, no correlation or alerting  
**Managed**: Traces linked across services, alerts firing, dashboards useful → **Target**  
**Optimized**: Real-time anomaly detection, SLO tracking, automated runbooks

## Required Inputs

- **Application stack**: Node.js, Python, .NET, Java, Go, etc.
- **Deployment target**: App Service, Container Apps, AKS, Function, VM
- **Critical user journeys**: Signup → Confirmation, Payment → Order, Search → Results
- **SLO targets**: Availability (%), latency (ms p99), error budget
- **Compliance needs**: PII filtering, data residency, retention policy
- **Existing telemetry**: Custom logging, APM, or greenfield?

## Decision Tree

```
Is this a new application or existing?
├─ New → Start with OpenTelemetry SDK from day one
└─ Existing → Assess current logging, add instrumentation incrementally

Which language?
├─ .NET → Application Insights .NET SDK (auto-instrumentation or manual)
├─ Node.js → OpenTelemetry + @opentelemetry/sdk-node
├─ Python → OpenTelemetry + opentelemetry-sdk
├─ Java → OpenTelemetry agent (zero-code) or manual SDK
└─ Other → OpenTelemetry language-specific SDK

How many services (microservices)?
├─ Single → Simple Application Insights setup, no special tracing
├─ 2-5 services → OpenTelemetry with correlation IDs across calls
└─ 5+ services → Distributed trace propagation (W3C Trace Context)

What's the expected volume?
├─ < 1M events/day → 100% sampling acceptable
├─ 1-10M → 10-25% sampling with head-based decisions
└─ > 10M → 1-5% sampling with tail-based (post-request) sampling decisions
```

## Workflow

### Phase 1: Setup Application Insights Workspace

1. **Create Application Insights resource**:
   ```bash
   az monitor app-insights component create \
     --resource-group $RG \
     --app-name "ai-${app}-${env}" \
     --location eastus
   
   # Get instrumentation key
   IKEY=$(az monitor app-insights component show --resource-group $RG --app-name "ai-${app}-${env}" --query "instrumentationKey")
   ```

2. **Create Log Analytics workspace** (for KQL queries):
   ```bash
   az monitor log-analytics workspace create \
     --resource-group $RG \
     --workspace-name "law-${app}-${env}"
   
   # Link to Application Insights
   az monitor app-insights component update --resource-group $RG --app-name "ai-${app}-${env}" \
     --workspace "/subscriptions/$SUBID/resourceGroups/$RG/providers/Microsoft.OperationalInsights/workspaces/law-${app}-${env}"
   ```

3. **Configure retention policy**:
   - Default: 30 days free
   - Increase if needed (paid): 90 days, 1 year
   - Archive to Storage: 7+ years for compliance

### Phase 2: Add SDK to Application

**Example 1: .NET**
```bash
# Install NuGet packages
dotnet add package Microsoft.ApplicationInsights.AspNetCore
dotnet add package Microsoft.ApplicationInsights.DependencyCollector
```

```csharp
// In Program.cs
builder.Services.AddApplicationInsightsTelemetry();

// Instrumentation key from Key Vault
var ikeySecret = new DefaultAzureCredential();
var kvUri = new Uri($"https://{kvName}.vault.azure.net");
var kvClient = new SecretClient(kvUri, ikeySecret);
var ikeySecret = kvClient.GetSecret("APPINSIGHTS_INSTRUMENTATION_KEY");
```

**Example 2: Node.js with OpenTelemetry**
```bash
npm install @opentelemetry/api @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-trace-node
```

```javascript
// instrumentation.js (first require in entry point)
const { NodeTracerProvider } = require("@opentelemetry/sdk-node");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-http");

const traceExporter = new OTLPTraceExporter({
  url: `https://${process.env.APPLICATIONINSIGHTS_ENDPOINT_URL}/v2.1/track`
});

From manu14357/zskills, MIT.

More from manu14357/zskills