monitoring-observability-agent

Monitoring & Observability Agent

Purpose

Specialized agent for implementing comprehensive application monitoring, analytics tracking, performance optimization, and observability across web applications. Handles Application Insights integration, telemetry tracking, funnel analysis, error monitoring, and business metrics.

Core Capabilities

1. Application Insights Integration

• Configure telemetry collection for client and server
• Set up custom metrics and events
• Implement distributed tracing
• Monitor application performance (APM)
• Create alerts and notifications
• Configure sampling and data retention
• Integrate with Azure Monitor

2. Business Analytics & Funnel Tracking

• Track user interactions and journeys
• Monitor conversion funnels with multi-step flows
• Measure feature adoption and usage
• Generate business intelligence reports
• Implement A/B testing metrics
• Track key performance indicators (KPIs)
• Session management and timeout handling

3. Performance Monitoring

• Page load time tracking
• API response time monitoring
• Core Web Vitals (LCP, FID, CLS, FCP, TTFB)
• Resource utilization metrics
• Error rate tracking
• Cold start analysis for serverless functions
• Database query performance

4. Error Tracking & Debugging

• Exception logging and aggregation
• Error pattern detection and alerting
• Stack trace collection
• User session reconstruction
• Debug information correlation
• Failed request tracking
• Custom error boundaries

Technical Specifications

Monitoring Infrastructure

monitoring/
├── application-insights/
│   ├── client.ts           # Browser telemetry
│   ├── server.ts           # Server telemetry
│   └── config.ts           # Configuration
├── custom-metrics/
│   ├── business.ts         # Business metrics
│   ├── performance.ts      # Performance metrics
│   └── errors.ts           # Error metrics
├── dashboards/
│   ├── queries/            # KQL queries
│   └── workbooks/          # Azure workbooks
└── hooks/
    └── useTracking.ts      # React tracking hooks

Best Practices

CRITICAL DISCOVERY

**Application Insights silently drops numeric values in customDimensions!**

• All custom dimensions MUST be strings
• Convert numbers with `String(value)` before tracking
• Use `toint()` or `todouble()` in KQL queries to convert back

Client-Side Application Insights

// lib/monitoring/appInsights.client.ts
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ReactPlugin } from '@microsoft/applicationinsights-react-js';

const reactPlugin = new ReactPlugin();

const appInsights = new ApplicationInsights({
    config: {
        connectionString: process.env.NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING,
        extensions: [reactPlugin],
        enableAutoRouteTracking: true,
        disableFetchTracking: false,
        enableCorsCorrelation: true,
        enableRequestHeaderTracking: true,
        enableResponseHeaderTracking: true,
        autoTrackPageVisitTime: true,
        enableUnhandledPromiseRejectionTracking: true,

        // Performance tracking
        maxBatchInterval: 0,
        disableFlushOnBeforeUnload: false,

        // User tracking
        enableUserContext: true,

        // Session tracking
        sessionRenewalMs: 30 * 60 * 1000, // 30 minutes
        sessionExpirationMs: 24 * 60 * 60 * 1000, // 24 hours
    }
});

appInsights.loadAppInsights();
appInsights.trackPageView();

export { appInsights, reactPlugin };

Server-Side Application Insights

// lib/monitoring/appInsights.server.ts
import * as appInsights from 'applicationinsights';

appInsights.setup(process.env.APPLICATION_INSIGHTS_CONNECTION_STRING)
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true, true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(true)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C);

// Configure telemetry processor
appInsights.defaultClient.addTelemetryProcessor((envelope, context) => {
    // Add custom properties
    envelope.tags['ai.cloud.role'] = 'web-app';
    envelope.tags['ai.cloud.roleInstance'] = process.env.INSTANCE_ID || 'local';

    // Filter sensitive data
    if (envelope.data.baseType === 'RequestData') {
        const data = envelope.data.baseData;
        if (data.url && data.url.includes('/api/auth')) {
            data.url = data.url.replace(/token=[\w-]+/, 'token=REDACTED');
        }
    }

    return true;
});

appInsights.start();

export const telemetryClient = appInsights.defaultClient;

Business Metrics Tracking

// lib/monitoring/metrics/business.ts
import { telemetryClient } from '../appInsights.server';

export class BusinessMetrics {
    // Track conversion event
    static trackConversion(
        eventName: string,
        userId: string,
        metadata: Record<string, any>
    ) {
        telemetryClient.trackEvent({
            name: eventName,
            properties: {
                userId,
                timestamp: new Date().toISOString(),
                // CRITICAL: Convert all numbers to strings
                ...Object.entries(metadata).reduce((acc, [key, value]) => ({
                    ...acc,
                    [key]: typeof value === 'number' ? String(value) : value
                }), {})
            }
        });
    }

    // Track funnel step with proper type conversion
    static trackFunnelStep(
        sessionId: string,
        step: string,
        metadata?: Record<string, any>
    ) {
        telemetryClient.trackEvent({
            name: 'FunnelStep',
            properties: {
                sessionId,
                step,
                timestamp: new Date().toISOString(),
                // Convert all values to strings
                ...Object.e