Настройка пакета SDK для Application Insights с использованием файла ApplicationInsights.config или ApplicationInsights.xml

Пакет SDK .NET Application Insights состоит из нескольких пакетов NuGet. Основной пакет предоставляет API для отправки телеметрии в Application Insights. Дополнительные пакеты предоставляют модули и инициализаторы телеметрии для автоматического отслеживания телеметрии вашего приложения и его контекста. При настройке файла конфигурации можно включить или отключить модули телеметрии и задать для них параметры.

Имя файла конфигурации – ApplicationInsights.config или ApplicationInsights.xml в зависимости от типа приложения. Он добавляется в проект автоматически при установке большинства версий пакета SDK. по умолчанию при использовании автоматизированного интерфейса проектов шаблонов Visual Studio, поддерживающих добавление телеметрия Application Insights, файл ApplicationInsights.config создается в корневой папке проекта, а при компиляции — в папку bin. Он также добавляется в веб-приложение монитором состояния на сервере IIS. Файл конфигурации не учитывается, если используется расширение для веб-сайта Azure или расширение для виртуальной машины и масштабируемого набора виртуальных машин Azure.

Эквивалентного файла для управления пакетом SDK на веб-странице не существует.

В этом документе описываются разделы файла конфигурации и то, как они управляют компонентами пакета SDK. Кроме того, в нем содержатся сведения о пакетах NuGet, загружающих эти компоненты.

Примечание

ApplicationInsights.config и XML-файлы инструкций не применяются к пакету SDK для .NET Core. Для настройки приложений .NET Core следуйте этому руководству.

Модули телеметрии (ASP.NET)

Каждый модуль телеметрии собирает определенный тип данных и использует основной API для их отправки. Модули устанавливаются разными пакетами NuGet, что также добавляет необходимые строки в CONFIG-файл.

В файле конфигурации есть узел для каждого модуля. Чтобы удалить модуль, удалите узел или закомментируйте его.

Отслеживание зависимостей

Dependency tracking собирает данные телеметрии о вызовах, выполняемых приложением к базам данных и внешним службам. Чтобы этот модуль работал на сервере IIS, установите монитор состояний.

Можно также написать код отслеживания зависимостей, используя API TrackDependency.

Зависимости можно собирать автоматически, не изменяя код, с помощью присоединения на основе агента (без кода). Чтобы использовать его в веб-приложениях Azure, включите расширение Application Insights. Чтобы использовать его в виртуальной машине Azure или в масштабируемом наборе виртуальных машин Azure, включите расширение мониторинга приложений для виртуальной машины и масштабируемого набора виртуальных машин.

Сборщик данных производительности

Собирает данные счетчиков производительности системы, например ЦП, памяти и сетевой нагрузки из установок IIS. Можно указать конкретные счетчики для сбора данных, включая счетчики производительности, настроенные самостоятельно.

Телеметрия диагностики Application Insights

DiagnosticsTelemetryModule информирует об ошибках в самом коде инструментирования Application Insights, например, если код не может получить доступ к счетчикам производительности или ITelemetryInitializer вызывает исключение. Данные телеметрии трассировки, собранные этим модулем, отображаются в колонке Diagnostic Search (Поиск в диагностических данных).

* `Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule`
* [Microsoft.ApplicationInsights](https://www.nuget.org/packages/Microsoft.ApplicationInsights) NuGet package. If you only install this package, the ApplicationInsights.config file is not automatically created.

Режим разработчика

DeveloperModeWithDebuggerAttachedTelemetryModule заставляет Application Insights TelemetryChannel отправлять данные незамедлительно (по одному элементу телеметрии за один раз), как только к процессу приложения присоединяется отладчик. Это сокращает период времени между моментом получения данных телеметрии вашим приложением и моментом их отображения на портале Application Insights. Это вызывает значительную нагрузку на процессор и пропускную способность сети.

Отслеживание веб-запросов

Передает данные о времени отклика и коде результата HTTP-запросов.

Отслеживание исключений

ExceptionTrackingTelemetryModule отслеживает количество необработанных исключений в вашем веб-приложении. Ознакомьтесь со статьей Ошибки и исключения.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
  • Microsoft.ApplicationInsights.Web
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule отслеживает незамеченные исключения задач.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule— отслеживает необработанные исключения для рабочих ролей, Windows служб и консольных приложений.
  • Application Insights Windows Server .

Отслеживание EventSource

EventSourceTelemetryModule позволяет настроить отправку событий EventSource в Application Insights в качестве трассировок. Сведения об отслеживании событий EventSource см. в разделе Использование событий EventSource.

Трассировка событий Windows

EtwCollectorTelemetryModule позволяет настроить отправку событий от поставщиков трассировки событий Windows в Application Insights в качестве трассировок. Сведения об отслеживании событий трассировки событий Windows см. в разделе Использование событий трассировки событий Windows.

Microsoft.ApplicationInsights

Пакет Microsoft.ApplicationInsights предоставляет основной API пакета SDK. Его используют другие модули телеметрии. Кроме того, вы можете использовать его для определения собственной телеметрии.

  • Нет записей в файле ApplicationInsights.config.
  • Microsoft.ApplicationInsights . Если просто установить этот пакет NuGet, CONFIG-файл не создается.

Канал телеметрии

Канал телеметрии управляет буферизацией и передачей данных телеметрии в службу Application Insights.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel — это канал по умолчанию для веб-приложений. Он буферизует данные в памяти и использует механизмы повтора и локальное дисковое хранилище для более надежной доставки телеметрии.
  • Microsoft.ApplicationInsights.InMemoryChannel — это упрощенный канал телеметрии, который используется, если другие каналы не настроены.

Инициализаторы телеметрии (ASP.NET)

Инициализаторы телеметрии задают свойства контекста, которые отправляются вместе с каждым элементом телеметрии.

Вы можете написать собственные инициализаторы для задания свойств контекста.

Все стандартные инициализаторы задаются пакетами NuGet Web или WindowsServer.

  • AccountIdTelemetryInitializer задает свойство AccountId.

  • AuthenticatedUserIdTelemetryInitializer задает свойство AuthenticatedUserId, как задано пакетом SDK JavaScript.

  • AzureRoleEnvironmentTelemetryInitializer обновляет свойства RoleName и RoleInstance контекста Device для всех элементов телеметрии с учетом данных, извлеченных из среды выполнения Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializer обновляет свойство Version контекста Component для всех элементов телеметрии с учетом значения, извлеченного из файла BuildInfo.config, созданного платформой MSBuild.

  • ClientIpHeaderTelemetryInitializer обновляет свойство Ip контекста Location всех элементов телеметрии в соответствии с HTTP-заголовком запроса X-Forwarded-For.

  • DeviceTelemetryInitializer обновляет следующие свойства контекста Device для всех элементов телеметрии.

    • Type получает значение «PC» (Компьютер).
    • Id получает значение, соответствующее доменному имени компьютера, на котором выполняется веб-приложение.
    • OemName получает значение, извлеченное из поля Win32_ComputerSystem.Manufacturer с помощью WMI.
    • Model получает значение, извлеченное из поля Win32_ComputerSystem.Model с помощью WMI.
    • NetworkType получает значение, извлеченное из NetworkInterface.
    • Language получает значение, соответствующее имени CurrentCulture.
  • DomainNameRoleInstanceTelemetryInitializer обновляет свойства RoleInstance контекста Device для всех элементов телеметрии с учетом доменного имени компьютера, на котором выполняется веб-приложение.

  • OperationNameTelemetryInitializerобновляет свойство Name контекста RequestTelemetry и свойство Name контекста Operation всех элементов телеметрии в соответствии с методом HTTP, а также именами контроллера MVC ASP.NET и действия, вызываемого для обработки запроса.

  • OperationIdTelemetryInitializer или OperationCorrelationTelemetryInitializer обновляет свойство контекста Operation.Id всех элементов телеметрии, отслеживаемых при обработке запроса с автоматически созданным RequestTelemetry.Id.

  • SessionTelemetryInitializer обновляет свойство Id контекста Session для всех элементов телеметрии со значениями, извлеченными из файла cookie ai_session, созданного кодом JavaScript инструментирования Application Insights, который выполняется в браузере пользователя.

  • SyntheticTelemetryInitializer или SyntheticUserAgentTelemetryInitializer обновляет свойства контекстов User, Session и Operation всех элементов телеметрии, отслеживаемых при обработке запроса от искусственного источника, например теста доступности или программы-робота поисковой системы. По умолчанию обозреватель метрик не отображает данные телеметрии искусственных источников.

    <Filters> задает идентификационные свойства запросов.

  • UserTelemetryInitializer обновляет свойства Id и AcquisitionDate контекста User для всех элементов телеметрии со значениями, извлеченными из файла cookie ai_user, созданного кодом JavaScript инструментирования Application Insights, который выполняется в браузере пользователя.

  • WebTestTelemetryInitializer Задает идентификатор пользователя, идентификатор сеанса и свойства искусственного источника для HTTP-запросов, поступающих из WebTestTelemetryInitializer. <Filters> задает идентификационные свойства запросов.

Для приложений .NET, работающих в Service Fabric, можно добавить пакет NuGet Microsoft.ApplicationInsights.ServiceFabric. Данный пакет содержит компонент FabricTelemetryInitializer, который добавляет свойства Service Fabric в элементы телеметрии. Дополнительные сведения см. на странице GitHub, посвященной свойствам, добавляемым пакетом NuGet.

Обработчики данных телеметрии (ASP.NET)

Обработчики данных телеметрии могут фильтровать и изменять любые элементы телеметрии непосредственно перед отправкой из пакета SDK на портал.

Вы можете написать собственные обработчики данных телеметрии.

Обработчик адаптивной выборки телеметрии (начиная с версии 2.0.0-beta3)

Эта функция включена по умолчанию. Если приложение отправляет слишком много телеметрических данных, обработчик удаляет часть из них.


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

С помощью параметра можно задать целевой показатель, которого алгоритм будет пытаться достичь. Каждый экземпляр пакета SDK работает независимо от других, поэтому если сервер представляет собой кластер из нескольких машин, фактический объем телеметрических данных будет кратен их количеству.

Дополнительная информация о выборке.

Обработчик выборки телеметрии с фиксированной частотой (начиная с версии 2.0.0-beta1)

Также имеется стандартный обработчик выборочной телеметрии (начиная с версии 2.0.1):


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

InstrumentationKey

Он определяет ресурс Application Insights, в котором отображаются данные. Обычно создается отдельный ресурс с отдельным ключом инструментирования для каждого приложения.

Если необходимо задать ключ динамически, например если вам нужно отправлять результаты из приложения в различные ресурсы, можно удалить ключ в файле конфигурации и задать его в коде.

Вы можете задать ключ для всех экземпляров TelemetryClient, включая стандартные модули телеметрии. Задайте ключ в методе инициализации, таком как global.aspx.cs, в службе ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Если нужно только отправлять определенный набор событий в другой ресурс, можно задать ключ для конкретного TelemetryClient:


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Чтобы получить новый ключ, создайте новый ресурс на портале Application Insights.

Поставщик идентификаторов приложений

Доступно начиная с версии 2.6.0.

Этот поставщик предназначен для поиска идентификатора приложения по ключу инструментирования. Идентификатор приложения включен в RequestTelemetry и DependencyTelemetry и используется для определения корреляции на портале.

Чтобы использовать его, установите TelemetryConfiguration.ApplicationIdProvider в коде или в конфигурации приложения.

Интерфейс: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Мы предоставляем две реализации в пакете SDK для Microsoft. ApplicationInsights : и DictionaryApplicationIdProvider .

ApplicationInsightsApplicationIdProvider

Этот интерфейс является оболочкой API-интерфейса Profile. Он регулирует запросы и кэширует их результаты.

Этот поставщик добавляется в файл конфигурации после установки Microsoft.ApplicationInsights.DependencyCollector или Microsoft.ApplicationInsights.Web.

Этот класс содержит необязательное свойство ProfileQueryEndpoint. По умолчанию оно имеет значение https://dc.services.visualstudio.com/api/profiles/{0}/appId. Если для этой конфигурации вам нужен прокси-сервер, мы рекомендуем настроить на нем базовый адрес и добавить /api/profiles/{0}/appId. Обратите внимание, что во время выполнения заполнитель {0} заменяется ключом инструментирования для каждого конкретного запроса.

Пример настройки в ApplicationInsights.config:

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Пример настройки напрямую в коде:

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Это статический поставщик, который использует настроенные пары ключей инструментирования и идентификаторов приложений.

Этот класс имеет свойство Defined , которое является < строкой словаря, строкой > ключа инструментирования и пар идентификаторов приложений.

Этот класс содержит необязательное свойство Next, с помощью которого вы можете настроить другой поставщик, который будет использоваться при запросе тех ключей инструментирования, которых не существует в вашей конфигурации.

Пример настройки в ApplicationInsights.config:

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Пример настройки напрямую в коде:

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Следующие шаги

Узнайте больше об API.