skilld
All skills
microsoft avatar

/applicationinsights-web-ts

@a6112cc
by microsoftmicrosoft/skills3.1k stars
351

Instrument browser/web apps with the Application Insights JavaScript SDK (@microsoft/applicationinsights-web). Use for Real User Monitoring (RUM) — page views, clicks, AJAX/fetch dependencies, exceptions, custom events, and browser-side GenAI agent traces correlated to backend OpenTelemetry traces. Covers SDK Loader Script and npm setup, framework extensions (React, React Native, Angular), Click Analytics, telemetry initializers, and OTel GenAI semantic conventions for agent/tool/model spans emitted from the browser.

Ask your Agent

Use this Skill: https://skilld.dev/gh/microsoft/skills/applicationinsights-web-ts

This session only. Nothing lands on disk.

referencesconfiguration.md

≈1.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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

Source: SKILL.md on GitHub

Third-party checks

No alerts16d3 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides comprehensive instructions for instrumenting web applications with telemetry. It includes security considerations regarding the ingestion of untrusted browser data and the handling of sensitive GenAI trace content, which are addressed through recommended best practices and opt-in configurations.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

Provenance

Signed by skilld at a6112cc. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago

Capability

Other metadata
metadata
{
  "author": "Microsoft",
  "version": "1.0.0",
  "package": "@microsoft/applicationinsights-web"
}

README badge

README badge for microsoft/skills/applicationinsights-web-ts