@carrot/logging-applicationinsights

ts

Application Insights sink for @carrot/logging. Maps log events to AI traces and exceptions, with per-event severity mapping and structured property forwarding.

Installation

import { appInsightsSink } from '@carrot/logging-applicationinsights';

Peer dependencies: @carrot/logging and @microsoft/applicationinsights-web ^3.3.0.

How It Works

Instance Resolution

Either provide a connectionString (the sink creates and initialises the AI instance) or pass an existing instance (the sink piggybacks on it). When creating its own instance, the sink applies sensible defaults:

• disableFetchTracking: false
• enableAutoRouteTracking: false
• enableCorsCorrelation: true
• enableRequestHeaderTracking: true
• enableResponseHeaderTracking: true

These can be overridden via the config option.

Event Mapping

Log Level	AI Severity
verbose, debug	Verbose
info	Information
warn	Warning
error	Error
fatal	Critical

Every event sends a trackTrace. Events with an error field additionally send a trackException for proper AI exception grouping.

Property Forwarding

Properties are built from:

1. baseProperties (static, from options)
2. event.properties (merged context + write-time properties)
3. Internal fields: _logId, _level, _parentId (if nested), _module (if custom module)

Flush

Calls ai.flush(false) (synchronous flush). Use log.flush() to trigger this before process exit.

Accessor

The returned sink exposes appInsights so consumers can call trackEvent, trackMetric, trackPageView, etc. without instantiating a second AI client.

Dependencies

Dependency	Kind
@carrot/logging	peer
@microsoft/applicationinsights-web	peer

Build

npm run build

Compiles TypeScript to ESM via tsc. Output lands in dist/.

---

Usage Guide

Application Insights sink for @carrot/logging - send traces and exceptions to Azure with structured properties.

Import

import { appInsightsSink } from '@carrot/logging-applicationinsights';

Common Patterns

1. Basic setup

import { Log, consoleSink } from '@carrot/logging';
import { appInsightsSink } from '@carrot/logging-applicationinsights';

const log = Log.configure()
    .addSink(consoleSink(), 'debug')
    .addSink(appInsightsSink({ connectionString: AI_CONN }), 'warn')
    .build();

2. Base properties for environment tagging

const sink = appInsightsSink({
    connectionString: AI_CONN,
    baseProperties: {
        service: 'carrot-web',
        environment: 'production',
        version: '1.2.3',
    },
});

Every trace and exception in App Insights will carry these properties.

3. Bring-your-own AI instance

If the host app already initialises Application Insights:

import { ApplicationInsights } from '@microsoft/applicationinsights-web';

const ai = new ApplicationInsights({ config: { connectionString: AI_CONN } });
ai.loadAppInsights();

const sink = appInsightsSink({ instance: ai });

4. Access the AI instance for additional telemetry

const sink = appInsightsSink({ connectionString: AI_CONN });

// Use the same AI instance for custom events
sink.appInsights.trackEvent({ name: 'FeatureUsed' }, { feature: 'dark-mode' });
sink.appInsights.trackMetric({ name: 'RenderTime', average: 12.5 });

5. Custom AI configuration

const sink = appInsightsSink({
    connectionString: AI_CONN,
    config: {
        enableAutoRouteTracking: true,
        maxBatchSizeInBytes: 100000,
    },
});

6. Flush before exit

await log.flush();  // triggers ai.flush() on the AI sink

Tips

• Set the sink level to 'warn' or higher in production to avoid sending noisy debug traces to App Insights.
• Use baseProperties to tag environment, service name, and version - makes filtering in the AI portal much easier.
• Prefer instance when the app already has AI set up to avoid duplicate telemetry clients.