references/configuration.md
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
maxBatchIntervalto 3–5 s andmaxBatchSizeInBytesto 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 = trueand callgetCookieMgr().setEnabled(false)after the user revokes consent. Do not destroy the SDK instance — re-enable by togglingdisableTelemetry = 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