applicationinsights-web-ts

Application Insights JavaScript SDK (Web) для TypeScript — это навык Microsoft для инструментирования браузерных и веб-приложений через пакет @microsoft/applicationinsights-web. Его предметная область — Real User Monitoring (RUM): сбор сведений о просмотрах страниц, переходах в одностраничном приложении, зависимостях AJAX и fetch, необработанных исключениях, пользовательских событиях и метриках. С подключённым Click Analytics можно автоматически собирать клики. В описании навыка отдельно указана поддержка браузерных трассировок GenAI-агентов, которые следуют семантическим соглашениям OpenTelemetry и могут быть связаны с серверными span-данными через W3C Trace Context. Это решение предназначено именно для клиентского кода. Microsoft прямо отделяет его от azure-monitor-opentelemetry-ts, предназначенного для Node.js-сервисов; тот же навык допускает сценарии браузера, веб-приложения и React Native. Основной пакет устанавливается через npm. Дополнительные пакеты добавляют сбор кликов, интеграцию с React, React Native и Angular, отладочный просмотр телеметрии и связку с User Timing через performance.mark/measure. Типы поставляются вместе с пакетом, поэтому отдельная установка @types для основного SDK не требуется. Есть два описанных способа загрузки. В сборочном проекте создаётся ApplicationInsights с connectionString и нужными настройками, затем loadAppInsights() вызывается один раз как можно раньше, а для первоначального экрана вызывается trackPageView(). При включённом enableAutoRouteTracking последующие изменения маршрута SPA отслеживаются автоматически. Для приложения без подходящего build pipeline доступен SDK Loader Script: его размещают первым скриптом в head; загрузчик содержит очередь вызовов, резервный CDN и отчёт о сбое загрузки. В обоих вариантах важно не инициализировать SDK повторно и не дублировать просмотры страниц ручным и автоматическим трекингом одновременно. Connection string в браузерном SDK попадает к клиенту в открытом виде. В исходном материале отдельно зафиксировано, что Microsoft Entra ID authentication для browser telemetry не поддерживается. Поэтому connection string нужно считать публичной конфигурацией, не помещать туда секреты и при необходимости отделять браузерный RUM от серверной телеметрии отдельным ресурсом Application Insights с локальной авторизацией. Для Vite, CRA и Next.js показано использование публичного префикса переменной окружения. Это не защита секрета, а способ передать клиенту строку подключения. Базовые операции охватывают несколько типов данных. trackPageView фиксирует страницу или маршрут и может принимать URI, имя и свойства. trackEvent подходит для действий пользователя или бизнес-событий, trackException — для пойманных ошибок, trackTrace — для диагностических сообщений, trackMetric — для числовых показателей, а trackDependencyData — для вручную описанных внешних запросов, когда требуется передать идентификатор, длительность, признак успеха, код ответа и адрес назначения. Loader API предоставляет те же основные вызовы через очередь, включая trackPageViewPerformance, измерение времени страниц и событий, добавление telemetry initializer, установку и очистку контекста пользователя и flush перед уходом со страницы. Контекст пользователя в примере помечен как содержащий персональные данные: навык не рекомендует передавать email. Telemetry initializer выполняется для каждого envelope до отправки. В примере он добавляет роль облака, экземпляр, версию и build приложения, может отбрасывать шумные health-check page views, а также заменять значения token, sig и key в query string на REDACTED. Это полезный слой фильтрации и обогащения, но он не отменяет требований к политике хранения данных: чувствительное содержимое нужно не собирать без одобрения и проверять до отправки в telemetry backend. Click Analytics подключается отдельным плагином. Для него задаются extensions и extensionConfig, можно включить autoCapture, использовать data-ai-* как префикс пользовательских атрибутов и отключить сбор hash URL. Пример также показывает behaviorValidator, который оставляет только значения нужного формата. В React Router навык предлагает withAITracking, а для ручной маршрутизации — trackPageView в эффекте роутера с выключенным автоматическим отслеживанием. Для Angular и React Native используются соответствующие официальные плагины, а не самодельные адаптеры. Для связи клиента с сервером описан режим DistributedTracingModes.AI_AND_W3C, задаваемый как distributedTracingMode: 2. SDK добавляет traceparent и legacy Request-Id к исходящим fetch/XHR. enableCorsCorrelation нужен для cross-origin запросов; сервер при этом должен разрешить вызывающему origin читать необходимые заголовки через CORS exposed headers. Это связывает browser dependency с backend OpenTelemetry, но не исправляет неверную CORS-конфигурацию и не делает внешнюю API-точку публично безопасной. Отдельный раздел посвящён трассировкам GenAI. Когда браузер напрямую вызывает агента, инструмент или модель, рекомендуется отправлять App Insights Dependency с атрибутами OpenTelemetry GenAI. Для invoke_agent и create_agent фиксируются операция, провайдер, имя агента и доступный идентификатор или модель; для chat — провайдер, запрошенная и ответившая модель и входные/выходные токены; для execute_tool — имя, тип инструмента и идентификатор вызова. В исходном примере также указан OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental, чтобы клиентская и серверная инструментация использовали согласованную схему. Системные инструкции, сообщения, аргументы и результаты инструментов отмечены как opt-in: их следует включать только за runtime-флагом и после проверки обработки чувствительных данных. Практически навык подходит для RUM в интернет-магазине или SaaS, измерения переходов в SPA, диагностики клиентских ошибок, наблюдения за fetch-зависимостями, разметки кликов и корреляции browser-to-backend трасс. Ограничения определяются самой областью применения: он не заменяет серверную Node.js-инструментацию, не скрывает connection string, требует аккуратной CORS-настройки для cross-origin correlation и не должен отправлять персональные либо GenAI-сообщения без явного разрешения. Перед внедрением Microsoft рекомендует сверяться с актуальными страницами документации по настройке JavaScript SDK, конфигурации и framework extensions, а версию @microsoft/applicationinsights-web проверять отдельно. Данные, которые навык перечисляет, следует включать только для реальной диагностической задачи, чтобы не превращать RUM в неконтролируемый сбор содержимого запросов.