Configuration Reference

Complete reference for IConfiguration / IConfig passed to new ApplicationInsights(\{ config \}).

Identity & Endpoints

Key	Type	Default	Notes
connectionString	string	—	Required. Includes ingestion + live-metrics endpoints. Public — never reuse with backend secrets.
instrumentationKey	string	—	Legacy. Prefer connectionString.
endpointUrl	string	regional	Override ingestion endpoint (sovereign clouds, proxies).
userOverrideEndpointUrl	string	—	Force a specific ingestion URL bypassing connection-string parsing.
appId	string	—	App identifier for cross-component correlation.

Auto-Collection

Key	Type	Default	Notes
disableAjaxTracking	bool	false	Stops XHR auto-instrumentation.
disableFetchTracking	bool	false	Stops fetch auto-instrumentation.
disableExceptionTracking	bool	false	Stops window.onerror / unhandled-rejection capture.
autoTrackPageVisitTime	bool	false	Emit time-on-page when leaving.
enableAutoRouteTracking	bool	false	Hook history.pushState/replaceState. SPA only.
enableUnhandledPromiseRejectionTracking	bool	false	Emits unhandledRejection as exceptions.
excludeRequestFromAutoTrackingPatterns	RegExp[]	—	Skip URLs (e.g. health checks, telemetry endpoints).

Distributed Tracing

Key	Type	Default	Notes
distributedTracingMode	enum	AI (1)	AI_AND_W3C (2) is required for OTel-instrumented backends.
enableCorsCorrelation	bool	false	Add correlation headers on cross-origin requests (requires server CORS allow-list).
correlationHeaderExcludePatterns	RegExp[]	—	Skip correlation for matching URLs (e.g. third-party CDNs that reject unknown headers).
correlationHeaderDomains	string[]	—	Limit correlation to specific domains.
correlationHeaderExcludedDomains	string[]	—	Hard-exclude domains.
enableRequestHeaderTracking	bool	false	Capture outbound request headers (PII risk).
enableResponseHeaderTracking	bool	false	Capture inbound response headers.
enableAjaxErrorStatusText	bool	false	Include statusText on failed AJAX.
enableAjaxPerfTracking	bool	false	Use PerformanceResourceTiming for richer AJAX timing.
maxAjaxCallsPerView	number	500	Limit AJAX deps per page view (-1 = unlimited).

Sampling & Throttling

Key	Type	Default	Notes
samplingPercentage	number	100	Client-side ingestion sampling. Whole numbers only.
maxBatchSizeInBytes	number	102400	Batch send threshold.
maxBatchInterval	number	15000	ms between sends.

Cookies & Storage

Key	Type	Default	Notes
isCookieUseDisabled	bool	false	Hard-disable cookies (no ai_user/ai_session).
cookieCfg	object	—	\{ enabled, domain, path, expiry, secure, ... \}.
isStorageUseDisabled	bool	false	Disable localStorage for buffer/retry.
disableUserInitMessage	bool	false	Suppress noisy diagnostic init message.

Send Behaviour

Key	Type	Default	Notes
onunloadDisableBeacon	bool	false	If true, do not use sendBeacon on unload.
disableXhr	bool	false	Force-disable XHR transport (sendBeacon/fetch only).
disableFlushOnBeforeUnload	bool	false	Skip auto-flush on beforeunload.
disableFlushOnUnload	bool	false	Skip auto-flush on unload/pagehide.
enableSessionStorageBuffer	bool	true	Persist queued telemetry across reloads.

Retry & Failover

Key	Type	Default	Notes
maxRetries	number	10	Per-batch retry budget.
disableInstrumentationKeyValidation	bool	false	Skip GUID validation (sovereign clouds).
loggingLevelConsole	0–2	0	0=off, 1=critical, 2=warn+critical.
loggingLevelTelemetry	0–2	1	Same scale; sends SDK self-diagnostics as Trace.

Plugins

Key	Type	Default	Notes
extensions	ITelemetryPlugin[]	[]	E.g. ReactPlugin, ClickAnalyticsPlugin.
extensionConfig	Record<string, any>	\{\}	Keyed by plugin.identifier.
disableTelemetry	bool	false	Master kill-switch (set after consent flow).

Recommended Production Config

import { ApplicationInsights, DistributedTracingModes } from "@microsoft/applicationinsights-web";

new ApplicationInsights({
  config: {
    connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING,

    // Auto-collection
    enableAutoRouteTracking: true,
    autoTrackPageVisitTime: true,
    enableUnhandledPromiseRejectionTracking: true,
    excludeRequestFromAutoTrackingPatterns: [
      /\/healthz$/i,
      /dc\.services\.visualstudio\.com/i,
      /js\.monitor\.azure\.com/i
    ],

    // Distributed tracing
    distributedTracingMode: DistributedTracingModes.AI_AND_W3C,
    enableCorsCorrelation: true,
    correlationHeaderExcludedDomains: ["*.googleapis.com", "*.facebook.com"],

    // Privacy
    isCookieUseDisabled: false,
    cookieCfg: { domain: ".example.com" },

    // Throughput
    samplingPercentage: 100,        // tune down if egress is high
    maxBatchInterval: 5000,

    // Diagnostics (set 0 in prod after stable)
    loggingLevelConsole: 0,
    loggingLevelTelemetry: 1
  }
});

Tuning notes

• Mobile networks: lower maxBatchInterval to 3–5 s and maxBatchSizeInBytes to 32 KB so unload flushes are smaller.
• High-traffic SPAs: turn on samplingPercentage (e.g. 25) before paying for ingestion overage. Server-side ingestion sampling on the App Insights resource is preferred when available.
• Strict CSP: Loader Script needs script-src https://js.monitor.azure.com 'self'. The npm import path requires no extra CSP.
• Tracking opt-out: set disableTelemetry = true and call getCookieMgr().setEnabled(false) after the user revokes consent. Do not destroy the SDK instance — re-enable by toggling disableTelemetry = false.

See also

• Microsoft Learn — JavaScript SDK configuration: https://learn.microsoft.com/azure/azure-monitor/app/javascript-sdk-configuration
• IConfiguration source: https://github.com/microsoft/ApplicationInsights-JS/blob/main/shared/AppInsightsCommon/src/Interfaces/IConfig.ts