Настройка пакета SDK Аналитика приложения с помощью Application Аналитика.config или .xml

Статья
01/31/2024

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

Примечание.

В следующей документации используется классический API приложения Аналитика. Долгосрочный план приложения Аналитика заключается в сборе данных с помощью OpenTelemetry. Дополнительные сведения см. в разделе "Включить Azure Monitor OpenTelemetry" для приложений .NET, Node.js, Python и Java.

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

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

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

Примечание.

Инструкции ApplicationInsights.config и .xml не применяются к пакету SDK для .NET Core. Чтобы настроить приложения .NET Core, следуйте инструкциям в разделе Application Аналитика для приложений ASP.NET Core.

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

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

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

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

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

Вы также можете написать собственный код отслеживания зависимостей с помощью API TrackDependency.

Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
Microsoft.Application Аналитика. Пакет NuGet dependencyCollector

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

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

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

Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
Microsoft.Application Аналитика. Пакет NuGet PerfCounterCollector

Данные телеметрии приложений Аналитика диагностика

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

Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
Microsoft.ApplicationInsights . Если просто установить этот пакет, файл ApplicationInsights.config не создается автоматически.

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

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

Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
Application Insights Windows Server

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

Отслеживание веб-запросов сообщает время отклика и код результата HTTP-запросов.

Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
Microsoft.ApplicationInsights.Web

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

Класс ExceptionTrackingTelemetryModule отслеживает необработанные исключения в веб-приложении. Дополнительные сведения см. в разделе "Сбои и исключения".

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

EventSource tracking

Класс EventSourceTelemetryModule позволяет настроить события EventSource для отправки в Приложение Аналитика в качестве трассировок. Сведения об отслеживании событий EventSource см. в разделе "Использование событий EventSource".

Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
Microsoft.ApplicationInsights.EventSourceListener

Отслеживание событий ETW

Класс EtwCollectorTelemetryModule позволяет настроить события от поставщиков ETW для отправки в приложение Аналитика в качестве трассировок. Сведения об отслеживании событий ETW см. в разделе "Использование событий ETW".

Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

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

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

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

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

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

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

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

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

Стандартные инициализаторы задаются пакетами NuGet в Интернете или WindowsServer:

AccountIdTelemetryInitializerAccountId задает свойство.
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 имеет значение name of the CurrentCulture property.
DomainNameRoleInstanceTelemetryInitializer обновляет свойства RoleInstance контекста Device для всех элементов телеметрии с учетом доменного имени компьютера, на котором выполняется веб-приложение.
OperationNameTelemetryInitializerName обновляет свойство и Name свойство RequestTelemetryOperation контекста всех элементов телеметрии на основе метода HTTP, а также имена контроллера и действия ASP.NET MVC, вызываемых для обработки запроса.
OperationIdTelemetryInitializer или OperationCorrelationTelemetryInitializer обновляет свойство контекста Operation.Id всех элементов телеметрии, отслеживаемых при обработке запроса с автоматически созданным RequestTelemetry.Id.
SessionTelemetryInitializerId обновляет свойство контекста Session для всех элементов телеметрии со значением, извлеченным из ai_session файла cookie, созданного ApplicationInsights кодом инструментирования JavaScript, запущенным в браузере пользователя.
SyntheticTelemetryInitializerили SyntheticUserAgentTelemetryInitializer обновляет UserSessionOperation свойства контекста всех элементов телеметрии, отслеживаемых при обработке запроса из искусственного источника, например теста доступности или поискового бота. По умолчанию обозреватель метрик не отображает искусственные данные телеметрии.

<Filters> задает идентификационные свойства запросов.
UserTelemetryInitializerId обновляет и AcquisitionDate свойства контекста User для всех элементов телеметрии со значениями, извлеченными из ai_user файла cookie, созданного приложением Аналитика кодом инструментирования JavaScript, выполняемым в браузере пользователя.
WebTestTelemetryInitializer задает идентификатор пользователя, идентификатор сеанса и свойства искусственного источника для HTTP-запросов, поступающих из тестов доступности. <Filters> задает идентификационные свойства запросов.

Для приложений .NET, работающих в Azure Service Fabric, можно включить Microsoft.ApplicationInsights.ServiceFabric пакет NuGet. Этот пакет содержит 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>

ConnectionString

См. строка подключения примеры кода.

InstrumentationKey

Примечание.

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

Этот параметр определяет ресурс 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);

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


    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.Application Аналитика: ApplicationInsightsApplicationIdProvider и DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

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

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

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

Пример конфигурации с помощью Application Аналитика.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 свойство, которое является парой Dictionary<string,string> ключей инструментирования или идентификаторов приложения.

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

Пример конфигурации с помощью Application Аналитика.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"}
    }
};

Настройка сбора моментальных снимков для приложений

Настройте коллекцию моментальных снимков для приложений ASP.NET.

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

Дополнительные сведения об API

Настройка пакета SDK Аналитика приложения с помощью Application Аналитика.config или .xml

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

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

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

Данные телеметрии приложений Аналитика диагностика

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

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

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

EventSource tracking

Отслеживание событий ETW

Microsoft.ApplicationInsights

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

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

Процессоры телеметрии (ASP.NET)

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

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

ConnectionString

InstrumentationKey

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

Интерфейс: IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

Пример конфигурации с помощью Application Аналитика.config

Пример конфигурации с помощью кода

DictionaryApplicationIdProvider

Пример конфигурации с помощью Application Аналитика.config

Пример конфигурации с помощью кода

Настройка сбора моментальных снимков для приложений

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

Дополнительные ресурсы