Включение Application Insights для приложений ASP.NET Core

В этой статье описано, как включить Application Insights для приложения ASP.NET Core, развернутого как веб-приложение Azure. В этой реализации используется подход на основе пакета SDK. Также доступен подход к автоматической интрументации .

Application Insights может собирать из приложения ASP.NET Core следующие данные телеметрии:

• Requests
• Зависимости
• Исключения
• Счетчики производительности
• Пакеты пульса
• Журналы

Для примера приложения мы будем использовать ASP.NET Core приложение MVC, предназначенное для net6.0. Однако эти инструкции можно применить ко всем ASP.NET Core приложениям. Если применяется служба Worker Service, воспользуйтесь инструкциями, приведенными здесь.

Примечание

Доступно предложение .NET на основе OpenTelemetry . Подробнее.

Примечание

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

Поддерживаемые сценарии

Пакет SDK Application Insights для ASP.NET Core может отслеживать приложения независимо от того, где или как они выполняются. Если приложение запущено и имеет сетевое подключение к Azure, Application Insights может собирать данные телеметрии из него. Мониторинг Application Insights поддерживается везде, где поддерживается .NET Core. Поддерживаются следующие сценарии:

• Операционная система: Windows, Linux или Mac.
• Метод размещения: внутри или вне процесса.
• Метод развертывания: зависит от платформы либо автономный.
• Веб-сервер: IIS или Kestrel
• Платформа размещения: функция веб-приложений службы приложений Azure, виртуальная машина Azure, Docker, служба Azure Kubernetes (AKS) и т. д.
• Версия .NET Core: все официально поддерживаемые версии .NET Core, которых нет в предварительной версии
• Интегрированная среда разработки: Visual Studio, Visual Studio Code или командная строка

Предварительные требования

Для работы с этим учебником необходимы указанные ниже компоненты.

• Visual Studio 2022
• Следующие рабочие нагрузки Visual Studio:
  • ASP.NET и веб-разработка.
  • Хранение и обработка данных
  • Разработка Azure.
• .NET 6.0
• Подписка Azure и учетная запись пользователя (с возможностью создания и удаления ресурсов).

Развертывание ресурсов Azure

Следуйте указаниям по развертыванию примера приложения из репозитория GitHub.

Чтобы предоставить ресурсы глобально уникальные имена, некоторым ресурсам назначается суффикс из шести символов. Запишите этот суффикс для использования далее в рамках этой статьи.

Создание ресурса Application Insights

1. В портал Azure выберите группу ресурсов application-insights-azure-café.

2. В верхнем меню панели инструментов нажмите кнопку + Create (+ Создать).

   

3. На экране Создание ресурса найдите и выберите Application Insights в текстовом поле Поиск в Marketplace.

   

   Снимок экрана: экран создания ресурса в портал Azure. На снимке экрана показан поиск Application Insights, выделенный и Application Insights, отображаемый в результатах поиска, который также выделен.

4. На экране обзора ресурса Application Insights нажмите кнопку Создать.

   

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

   Поле	Значение
   Имя	Введите azure-cafe-application-insights-{SUFFIX}, заменив {SUFFIX} соответствующим значением суффикса, записанным ранее.
   Регион	Выберите тот же регион, выбранный при развертывании ресурсов статьи.
   Рабочая область Log Analytics	Выберите azure-café-log-analytics-workspace. Кроме того, можно создать новую рабочую область Log Analytics.

   

6. После прохождения проверки нажмите кнопку Создать, чтобы развернуть ресурс.

   

7. После развертывания ресурса вернитесь в группу application-insights-azure-cafe ресурсов и выберите развернутый ресурс Application Insights.

   

8. На экране Обзор ресурса Application Insights нажмите кнопку Копировать в буфер обмена, чтобы скопировать значение строка подключения. Значение строка подключения будет использоваться в следующем разделе этой статьи.

   

   Снимок экрана с обзором Application Insights в портал Azure. На снимке экрана показано выделенное значение строка подключения и выбранная и выделенная кнопка "Копировать в буфер обмена".

Настройка параметра приложения для строки подключения Application Insights в службе веб-приложений

1. Вернитесь в группу application-insights-azure-cafe ресурсов и откройте ресурс azure-café-web-{SUFFIX} Служба приложений.

   

2. В меню слева в разделе Параметры выберите Конфигурация. Затем на вкладке Параметры приложения под заголовком параметров приложения выберите + New application setting (+ Новый параметр приложения).

   

   Снимок экрана: экран ресурса Служба приложений в портал Azure. На снимке экрана показана конфигурация в меню слева в разделе Параметры, выбрана и выделена вкладка Параметры приложения и выделена кнопка + Новый параметр приложения на панели инструментов.

3. В области Добавление и изменение параметров приложения заполните форму, как показано ниже, и нажмите кнопку ОК.

   Поле	Значение
   Имя	APPLICATIONINSIGHTS_CONNECTION_STRING
   Значение	Вставьте значение строка подключения Application Insights, скопированное в предыдущем разделе.

   

4. На экране конфигурации Службы приложений нажмите кнопку Сохранить в меню панели инструментов. При появлении запроса на сохранение изменений нажмите кнопку Далее.

   

Установка пакета NuGet Application Insights

Нам нужно настроить веб-приложение ASP.NET Core MVC для отправки данных телеметрии. Это достигается с помощью Application Insights для пакета NuGet веб-приложений ASP.NET Core.

1. В Visual Studio откройте .1 - Starter Application\src\AzureCafe.sln

2. На панели Обозреватель решений Visual Studio щелкните правой кнопкой мыши файл проекта AzureCafe и выберите Управление пакетами NuGet.

   

3. Перейдите на вкладку Обзор , а затем найдите и выберите Microsoft.ApplicationInsights.AspNetCore. Нажмите Установить и примите условия лицензии. Рекомендуется использовать последнюю стабильную версию. Полные заметки о выпуске пакета SDK см. в репозитории GitHub с открытым кодом.

   

   Снимок экрана: пользовательский интерфейс диспетчера пакетов NuGet в Visual Studio с выбранной вкладкой Обзор. Microsoft.ApplicationInsights.AspNetCore вводится в поле поиска, а пакет Microsoft.ApplicationInsights.AspNetCore выбирается из списка результатов. В области справа в раскрывающемся списке выбрана последняя стабильная версия пакета Microsoft.ApplicationInsights.AspNetCore и выделена кнопка Установить.

   Оставьте Visual Studio открытым для следующего раздела статьи.

Включение телеметрии на стороне сервера Application Insights

Application Insights для пакета NuGet веб-приложений ASP.NET Core инкапсулирует возможности для отправки телеметрии на стороне сервера для ресурса Application Insights в Azure.

1. В Обозреватель решений Visual Studio откройте файл Program.cs.

   

2. Вставьте указанный ниже код перед инструкцией builder.Services.AddControllersWithViews(). Этот код автоматически считывает значение строки подключения Application Insights из конфигурации. Метод AddApplicationInsightsTelemetry регистрирует со встроенным контейнером ApplicationInsightsLoggerProvider внедрения зависимостей, который затем будет использоваться для выполнения запросов реализации ILogger и ILogger<TCategoryName> .

   builder.Services.AddApplicationInsightsTelemetry();
   

   

   Совет

   Дополнительные сведения о параметрах конфигурации см. в ASP.NET Core.

Включение телеметрии на стороне клиента для веб-приложений

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

1. В Обозреватель решений Visual Studio откройте .\Views\_ViewImports.cshtml

2. В конце имеющегося файла добавьте указанный ниже код.

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

   

3. Чтобы правильно включить мониторинг на стороне клиента для приложения, в Visual Studio Обозреватель решений откройте \Views\Shared\_Layout.cshtml и вставьте следующий код непосредственно перед закрывающим <\head> тегом. Этот фрагмент Кода JavaScript необходимо вставить в <head> раздел каждой страницы приложения, которое вы хотите отслеживать.

   @Html.Raw(JavaScriptSnippet.FullScript)
   

   

   Совет

   Альтернативой использованию FullScript является ScriptBody. Используйте параметр ScriptBody, если необходимо управлять тегом <script> для задания политики безопасности содержимого:

   <script> // apply custom changes to this script tag.
       @Html.Raw(JavaScriptSnippet.ScriptBody)
   </script>
   

Примечание

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

Включение мониторинга запросов к базе данных

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

Выполните следующие действия, чтобы записать полный текст SQL-запроса.

Примечание

Текст SQL может содержать конфиденциальные данные, такие как пароли и персональные данные. Будьте внимательны при включении этой возможности.

1. В Обозреватель решений Visual Studio откройте файл Program.cs.

2. Добавьте в начало файла указанную ниже инструкцию using.

   using Microsoft.ApplicationInsights.DependencyCollector;
   

3. Чтобы включить инструментирование текста команды SQL, вставьте следующий код сразу после builder.Services.AddApplicationInsightsTelemetry() кода.

   builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module.EnableSqlCommandTextInstrumentation = true; });
   

   

Запуск веб-приложения Azure Cafe

После развертывания кода веб-приложения данные телеметрии будут передаваться в Application Insights. Пакет SDK для Application Insights автоматически собирает входящие веб-запросы в приложение.

1. В Обозреватель решений Visual Studio щелкните правой кнопкой мыши проект AzureCafe и выберите Опубликовать в контекстном меню.

   

2. Выберите Опубликовать, чтобы повысить уровень нового кода до Службы приложений Azure.

   

   После успешной публикации веб-приложения Кафе Azure Cafe откроется новое окно браузера для веб-приложения Azure Cafe.

   

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

   1. Выберите Сведения рядом с Cafe, чтобы просмотреть меню и проверки.

      

   2. Чтобы просмотреть и добавить проверки, на экране Cafe выберите вкладку Проверки. Нажмите кнопку Добавить проверку, чтобы добавить проверку.

      

   3. В диалоговом окне создания отзыва введите имя, оценку, комментарии и отправьте фотографию для отзыва. По завершении выберите Добавить проверку.

      

   4. Если необходимо создать дополнительную телеметрию, добавьте дополнительные проверки.

Динамические метрики

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

Просмотр карты приложения

Пример приложения вызывает несколько ресурсов Azure, включая Azure SQL, Хранилище BLOB-объектов Azure и языковую службу Azure (для проверки анализа тональности).

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

1. Войдите на портал Azure.

2. Откройте группу ресурсов для примера приложения. Это application-insights-azure-cafe.

3. В списке ресурсов выберите ресурс Application Insights azure-cafe-insights-{SUFFIX}.

4. В меню слева под заголовком Исследование выберите Карта приложения. Обратите внимание на созданную схему приложений.

   

Просмотр вызовов HTTP и текста команды SQL базы данных

1. Откройте ресурс Application Insights на портале Azure.

2. В меню слева под заголовком Исследование выберите Производительность.

3. Вкладка Операции содержит сведения о вызовах HTTP, полученных приложением. Для переключения между представлениями сервера и браузера (на стороне клиента) данных используйте переключатель Сервер/Браузер.

   

   Снимок экрана: экран производительности Application Insights в портал Azure. Снимок экрана: выделенный переключатель "Сервер/браузер" и HTTP-вызовы, полученные приложением.

4. Выберите операцию из таблицы и перейдите к детализации примера запроса.

   

   Снимок экрана: экран производительности Application Insights в портал Azure. На снимке экрана показана операция POST и пример операции из предлагаемого списка, выбранные и выделенные, а также выделена кнопка Детализация примеров.

   Для выбранного запроса отображается сквозная транзакция. В этом случае была создана проверка с изображением, поэтому она включает вызовы к службе хранилища Azure и языковой службе (для анализа тональности). Он также включает вызовы базы данных в SQL Azure для сохранения проверки. В этом примере первое выбранное событие отображает сведения относительно вызова POST HTTP.

   

5. Выберите элемент SQL, чтобы просмотреть текст команды SQL, выданный базе данных.

   

6. При необходимости выберите зависимости (исходящие) запросы к службе хранилища Azure или языковой службе.

7. Вернитесь на экран Производительность и выберите вкладку Зависимости , чтобы исследовать вызовы внешних ресурсов. Обратите внимание, что таблица операций включает вызовы анализа тональности, хранилища BLOB-объектов и Azure SQL.

   

Ведение журнала приложений с помощью Application Insights

Общие сведения о ведении журналов

Application Insights — это один из типов поставщиков ведения журнала, доступных для ASP.NET Core приложений, которые становятся доступными для приложений при установке пакета NuGet Application Insights для ASP.NET Core и включении сбора данных телеметрии на стороне сервера.

Как напоминание, указанный ниже код в Program.cs регистрирует ApplicationInsightsLoggerProvider с помощью встроенного контейнера внедрения зависимостей.

builder.Services.AddApplicationInsightsTelemetry();

При регистрации в ApplicationInsightsLoggerProvider качестве поставщика ведения журнала приложение готово к входу в Application Insights с помощью внедрения конструктора с ILogger или альтернативного ILogger<TCategoryName>универсального типа .

Примечание

По умолчанию поставщик ведения журнала настроен для автоматического записи событий журнала с уровнем серьезности LogLevel.Warning или больше.

Рассмотрим следующий пример контроллера. В нем демонстрируется внедрение ILogger, которое разрешается с ApplicationInsightsLoggerProvider помощью , зарегистрированного в контейнере внедрения зависимостей. Обратите внимание на то, что в методе Get записываются информационные сообщения, предупреждения и сообщения об ошибке.

Примечание

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

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInformation("An example of an Info trace..");
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Дополнительные сведения см. в разделе Introduction to Logging in ASP.NET Core (Вводные сведения о ведении журналов в ASP.NET Core).

Просмотр журналов Application Insights

Указанный объект ValuesController развертывается с примером приложения и находится в папке Controllers проекта.

1. Откройте пример приложения с помощью браузера. В адресной строку добавьте /api/Values и нажмите Ввести.

   

2. В портал Azure подождите несколько секунд, а затем выберите ресурс Application Insights azure-café-insights-{SUFFIX}.

   

3. В меню слева ресурса Application Insights в разделе Мониторинг выберите Журналы.

4. В области Таблицы в дереве Application Insights дважды щелкните таблицу трассировок .

5. Измените запрос, чтобы получить трассировки для контроллера Значения как указано ниже, а затем выберите Выполнить, чтобы отфильтровать результаты.

   traces 
   | where operation_Name == "GET Values/Get"
   

   В результатах отображаются сообщения ведения журнала, присутствующие в контроллере. Серьезность журнала степени 2 указывает порог предупреждений, а степень 3 — уровень ошибки.

6. Кроме того, можно написать запрос для получения результатов на основе категории журнала. По умолчанию категория — это полное имя класса, в который внедряется ILogger. В этом случае имя категории — ValuesController (если с классом связано пространство имен, имя будет иметь префикс пространства имен). Повторно напишите и выполните указанный ниже запрос, чтобы получить результаты на основе категории.

   traces 
   | where customDimensions.CategoryName == "ValuesController"
   

Управление уровнем журналов, отправляемых в Application Insights

Реализации ILogger имеют встроенный механизм для применения фильтрации журналов. Эта фильтрация позволяет управлять журналами, которые отправляются каждому зарегистрированному поставщику, включая поставщика Application Insights. Фильтрацию можно выполнять либо в конфигурации (например с помощью файла appsettings.json), либо в коде. Дополнительные сведения об уровнях журналов и рекомендации по их использованию см. в документации по уровню журнала .

В указанных ниже примерах показано, как применить правила фильтрации к ApplicationInsightsLoggerProvider для управления уровнем журналов, отправляемых в Application Insights.

Создание правил фильтрации с помощью конфигурации

В конфигурации ApplicationInsightsLoggerProvider получает псевдоним ApplicationInsights. В указанном ниже разделе файла appsettings.json задается уровень журнала по умолчанию для всех поставщиков LogLevel.Warning. Конфигурация поставщика ApplicationInsights, в частности для категорий, которые начинаются с "ValuesController", переопределяет это значение по умолчанию на LogLevel.Error и выше.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

Развертывание примера приложения с указанным кодом в appsettings.json даст только трассировку ошибок, отправляемую в Application Insights при взаимодействии с ValuesController. Это связано с тем, что для параметра LogLevel для категории ValuesController задано значение Ошибка. Поэтому трассировка предупреждений подавляется.

Отключение ведения журнала в Application Insights

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

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

Аналогичным образом в коде задайте для уровня по умолчанию для ApplicationInsightsLoggerProvider и всех последующих уровней журнала значение Нет.

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

Пакет SDK с открытым исходным кодом

• Чтение кода и дополнительные наработки.

Последние обновления и исправления ошибок см. в заметках о выпуске.

Дальнейшие действия

• Изучите маршруты пользователей, чтобы понять, как пользователи перемещаются через приложение.
• Настройте коллекцию моментальных снимков для отображения состояния исходного кода и переменных в момент создания исключения.
• Используйте API для отправки собственных событий и метрик для более четкого представления о производительности и использовании приложения.
• Обзор доступности
• Использование внедрения зависимостей в ASP.NET Core
• Ведение журналов в ASP.NET Core
• Просмотр журналов трассировки .NET в Application Insights
• Автоинструментация для Application Insights