Application Insights для приложений ASP.NET, ASP.NET Core и Worker Service (не HTTP)

В этой статье объясняется, как включить и настроить Application Insights для приложений ASP.NET, ASP.NET Core и Worker Service (non-HTTP). Application Insights может собирать следующие данные телеметрии из приложений:

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

Добавьте Application Insights

Предпосылки

Создание базового веб-приложения

Если у вас еще нет работающего веб-приложения, можно использовать следующее руководство для создания веб-приложения.

Автоматическое добавление Application Insights (Visual Studio)

В этом разделе описано автоматическое добавление Application Insights в веб-приложение на основе шаблона.

Добавление Application Insights вручную (без Visual Studio)

В этом разделе описано, как вручную добавить Application Insights в веб-приложение на основе шаблона.

Проверка получения данных телеметрии Application Insights

Настройка телеметрии

В этом разделе

• Показатели в реальном времени
• Трассировка (журнал)
• Распределенная трассировка
• Зависимости
• Исключения
• Пользовательские метрики
• Пользовательские операции

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

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

Включение динамических метрик с помощью кода для любого приложения .NET

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a TelemetryConfiguration instance.
            TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
            config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
            QuickPulseTelemetryProcessor quickPulseProcessor = null;
            config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
                .Use((next) =>
                {
                    quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
                    return quickPulseProcessor;
                })
                .Build();

            var quickPulseModule = new QuickPulseTelemetryModule();

            // Secure the control channel.
            // This is optional, but recommended.
            quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
            quickPulseModule.Initialize(config);
            quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

            // Create a TelemetryClient instance. It is important
            // to use the same TelemetryConfiguration here as the one
            // used to set up live metrics.
            TelemetryClient client = new TelemetryClient(config);

            // This sample runs indefinitely. Replace with actual application logic.
            while (true)
            {
                // Send dependency and request telemetry.
                // These will be shown in live metrics.
                // CPU/Memory Performance counter is also shown
                // automatically without any additional steps.
                client.TrackDependency("My dependency", "target", "http://sample",
                    DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
                client.TrackRequest("My Request", DateTimeOffset.Now,
                    TimeSpan.FromMilliseconds(230), "200", true);
                Task.Delay(1000).Wait();
            }
        }
    }
}

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Трассировки (журналы)

Application Insights записывает журналы из ASP.NET Core и других приложений .NET через ILogger и из классической ASP.NET (.NET Framework) с помощью классического пакета SDK и адаптеров.

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

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

Консольное приложение

Чтобы добавить ведение журнала Application Insights в консольные приложения, сначала установите следующие пакеты NuGet:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

В следующем примере используется Microsoft.Extensions.Logging.ApplicationInsights пакет и демонстрируется поведение по умолчанию для консольного приложения. Пакет Microsoft.Extensions.Logging.ApplicationInsights следует использовать в консольном приложении или всякий раз, когда требуется минимальная реализация Application Insights без полного набора функций, таких как метрики, распределенные трассировки, выборки и инициализаторы телеметрии.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Дополнительные сведения см. в статье о типе телеметрии Application Insights из журналов ILogger? Где можно увидеть журналы ILogger в Application Insights?.

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

ApplicationInsightsLoggingProvider поддерживает области журналов, которые включены по умолчанию.

Если область имеет тип IReadOnlyCollection<KeyValuePair<string,object>>, каждая пара "ключ-значение" в коллекции добавляется в телеметрию Application Insights в качестве настраиваемых свойств. В следующем примере журналы записываются как TraceTelemetry и имеются ("MyKey", "MyValue") в свойствах.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

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

using (_logger.BeginScope("hello scope"))
{
    _logger.LogError("An example of an Error level message");
}

Поиск журналов

Журналы ILogger отображаются в виде телеметрии трассировки (таблица traces в Application Insights и AppTraces Log Analytics).

Пример

На портале Azure перейдите в Application Insights и выполните следующие действия:

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

Распределенная трассировка

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

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

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

Включите распределённую трассировку через Application Insights с помощью автоинструментирования или пакетов SDK.

Агенты Application Insights и пакеты SDK для .NET, .NET Core, Java, Node.jsи JavaScript поддерживают собственную распределенную трассировку.

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

Любые технологии также можно отслеживать вручную с помощью вызова TrackDependency в TelemetryClient.

Модель данных для корреляции телеметрии

Application Insights определяет модель данных для корреляции распределенной телеметрии. Для связывания телеметрии с логической операцией каждый элемент телеметрии имеет поле operation_Idконтекста. Каждый элемент телеметрии в распределенной трассировке использует этот идентификатор. Таким образом, даже если вы теряете данные телеметрии из одного слоя, вы по-прежнему можете связать данные телеметрии, сообщаемые другими компонентами.

Распределенная логическая операция обычно состоит из набора небольших операций, обрабатываемых одним из компонентов. Запрос телеметрии определяет эти операции. Каждый элемент телеметрии запроса имеет свой собственный id идентификатор, определяющий его уникально и глобально. И все элементы телеметрии (например, трассировки и исключения), связанные с запросом, должны установить operation_parentId в значение запроса id.

Телеметрия зависимостей представляет каждую исходящую операцию, например вызов HTTP к другому компоненту. Он также определяет свой собственный id, который глобально уникален. Запрос телеметрии, инициированный этим вызовом зависимости, использует это id в качестве operation_parentId.

Вы можете создать представление распределенной логической операции с помощью operation_Id, operation_parentId, request.id и dependency.id. Эти поля также определяют порядок причинно-следственных вызовов телеметрии.

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

Если количество элементов хранилища большое, вам потребуется указание о том, где искать дальше. Модель данных Application Insights определяет два поля для решения этой проблемы: request.source и dependency.target. Первое поле определяет компонент, инициирующий запрос зависимостей. Второе поле определяет, какой компонент вернул ответ вызова зависимостей.

Сведения о запросах из нескольких разрозненных экземпляров см. в статье "Запрос данных в рабочих областях Log Analytics, приложениях и ресурсах в Azure Monitor".

Example

Рассмотрим пример. Приложение под названием "Цены акций" показывает текущую рыночную цену акций с помощью внешнего API с именем Stock. Приложение "Цены на акции" имеет страницу с именем "Фондовая страница", которая открывается в веб-браузере клиента с помощью GET /Home/Stock. Приложение запрашивает API stock с помощью http-вызова GET /api/stock/value.

Чтобы проанализировать полученную телеметрию, выполните запрос:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

В результатах все элементы телеметрии имеют общий корень operation_Id. При вызове Ajax на странице новый уникальный идентификатор (qJSXU) назначается телеметрии зависимостей, а идентификатор pageView используется как operation_ParentId. Затем запрос сервера использует идентификатор Ajax в качестве operation_ParentId.

При вызове GET /api/stock/value внешней службы необходимо знать идентификацию сервера, чтобы можно было соответствующим образом установить поле dependency.target. Если внешняя служба не поддерживает мониторинг, target устанавливается в имя узла службы. Примером является stock-prices-api.com. Но если служба идентифицирует себя путем возврата предопределенного заголовка HTTP, target содержит удостоверение службы, позволяющее Application Insights создавать распределенную трассировку путем запроса телеметрии из этой службы.

Заголовки корреляции с помощью W3C TraceContext

Application Insights переходит в контекст трассировки W3C, который определяет:

• traceparent: содержит глобальный уникальный идентификатор операции и уникальный идентификатор вызова.
• tracestate: содержит контекст трассировки для конкретной системы.

Последняя версия пакета SDK Application Insights поддерживает протокол Trace-Context, но может потребоваться принять его. (Поддерживается обратная совместимость с предыдущим протоколом корреляции, поддерживаемым пакетом SDK Application Insights.)

Протокол HTTP корреляции, также называемый Request-Id, устарел. Этот протокол определяет два заголовка:

• Request-Id: несет глобально уникальный идентификатор вызова.
• Correlation-Context: содержит коллекцию пар "имя-значение" свойств распределенной трассировки.

Application Insights также определяет расширение для протокола HTTP корреляции. Он использует Request-Context пары "имя-значение" для распространения коллекции свойств, используемых непосредственным вызывающим или вызываемой стороной. Пакет SDK Application Insights использует этот заголовок для задания полей dependency.target и request.source.

Модели данных W3C Trace-Context и Application Insights сопоставляются следующим образом:

Дополнительные сведения см. в модели данных телеметрии Application Insights.

Включение поддержки распределенной трассировки W3C

Распределенная трассировка на основе W3C TraceContext включена по умолчанию во всех новейших SDK для .NET Framework/.NET Core, включая обратную совместимость с устаревшим Request-Id протоколом.

Корреляция телеметрии

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

Среда выполнения .NET поддерживает поддержку распределённых операций с помощью Activity и DiagnosticSource

Пакет SDK для .NET от Application Insights использует DiagnosticSource и Activity, чтобы собирать и сопоставлять данные телеметрии.

Зависимости

Автоматически отслеживаемые зависимости

Пакеты SDK Application Insights для .NET и .NET Core содержат DependencyTrackingTelemetryModule, который является модулем телеметрии для автоматического сбора данных о зависимостях. Модуль DependencyTrackingTelemetryModule поставляется как пакет NuGet Microsoft.ApplicationInsights.DependencyCollector и автоматически добавляется при использовании Microsoft.ApplicationInsights.Web пакета NuGet или Microsoft.ApplicationInsights.AspNetCore пакета NuGet.

Сейчас DependencyTrackingTelemetryModule автоматически отслеживает следующие зависимости:

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

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

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

Для автоматического отслеживания зависимостей из консольных приложений .NET установите пакет NuGet Microsoft.ApplicationInsights.DependencyCollector и инициализируйте DependencyTrackingTelemetryModule:

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

Отслеживание зависимостей вручную

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

• Azure Cosmos DB отслеживается автоматически только в том случае, если используется HTTP/HTTPS. Режим TCP не автоматически фиксируется Application Insights для версий ПАКЕТА SDK старше 2.22.0-Beta1.
• Redis

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

Пример

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

Чтобы эти данные отображались в диаграммах зависимостей Application Insights, отправляйте их с использованием TrackDependency:

    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

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

Отключение стандартного модуля отслеживания зависимостей

Дополнительные сведения см. в модулях телеметрии.

Расширенное отслеживание SQL для получения полного SQL-запроса

Для вызовов SQL всегда собирается и сохраняется имя сервера и базы данных как имя собранных данных DependencyTelemetry. Другое поле с именем data может содержать весь текст SQL-запроса.

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

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

В приведенных выше случаях, чтобы надлежащим образом проверить установку подсистемы инструментирования, убедитесь, что собираемые данные DependencyTelemetry относятся к пакету SDK версии rddp. rdddsd Использование или rddf указывает, что зависимости собираются с помощью DiagnosticSource или EventSource обратного вызова, поэтому полный SQL-запрос не фиксируется.

Exceptions

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

Настройка отчетов об исключениях

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

Диагностика сбоев и исключений

Пользовательские данные трассировки и журнала

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

Microsoft.VisualStudio.ApplicationInsights.TelemetryClientИспользуя несколько доступных API:

• TelemetryClient.TrackEvent обычно используется для мониторинга шаблонов использования, но данные, которые он отправляет, также отображаются в разделе "Пользовательские события " в поиске диагностики. События именуются и могут содержать строковые свойства и числовые метрики, на которых можно фильтровать диагностические поиски.
• TelemetryClient.TrackTrace позволяет отправлять более длинные данные, такие как сведения POST.
• TelemetryClient.TrackException отправляет сведения об исключении, например трассировки стека в Application Insights.

Чтобы просмотреть эти события, в меню слева откройте "Поиск". Выберите типы событий раскрывающегося меню, а затем выберите "Пользовательское событие", " Трассировка" или "Исключение".

Просмотр данных POST запроса

Сведения о запросе не включают данные, отправленные приложению в вызов POST. Чтобы сообщить об этих данных, выполните указанные ниже действия.

• Добавьте пакет SDK Application Insights в код приложения.
• Вставьте код в приложение, чтобы вызвать Microsoft.ApplicationInsights.TrackTrace(). Отправьте данные POST в параметре сообщения. Существует ограничение на допустимый размер, поэтому следует попытаться отправить только необходимые данные.
• При изучении неудачного запроса найдите связанные трассировки.

Запись исключений и связанных диагностических данных

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

Вы можете:

• Явным образом регистрируются исключения , вставляя код в обработчики исключений, чтобы сообщить об исключениях.
• Автоматическое запись исключений путем настройки платформы ASP.NET. Необходимые дополнения отличаются для различных типов платформы.

Явное исключение отчета

Самый простой способ отчета — вставить вызов trackException() в обработчик исключений.

var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}

try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

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

Исключения браузера

Сообщается большинство исключений браузера.

Если веб-страница содержит файлы скриптов из сетей доставки содержимого или других доменов, убедитесь, что тег скрипта имеет атрибут crossorigin="anonymous" и что сервер отправляет заголовки CORS. Это поведение позволяет получить трассировку стека и подробные сведения об необработанных исключениях JavaScript из этих ресурсов.

Повторное использование клиента телеметрии

Благодаря внедрению зависимостей (DI) в .NET, соответствующему пакету SDK для .NET и правильной настройке Application Insights для DI можно требовать параметр TelemetryClient конструктора.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

В предыдущем примере TelemetryClient он внедряется в ExampleController класс.

Веб-формы

Для веб-форм модуль HTTP может собирать исключения при отсутствии перенаправлений, настроенных с CustomErrorsпомощью . Однако при наличии активных перенаправлений добавьте следующие строки в функцию Application_Error в Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

В предыдущем примере _telemetryClient это переменная типа с областью действия TelemetryClientкласса.

MVC

Начиная с версии 2.6 (бета-версия 3 и более поздних версий) Application Insights собирает необработанные исключения, создаваемые в методах контроллеров MVC 5 и более поздних версий. Если вы ранее добавили пользовательский обработчик для отслеживания таких исключений, его можно удалить, чтобы предотвратить двойное отслеживание исключений.

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

• Из конструкторов контроллеров
• Из обработчиков сообщений
• Во время маршрутизации
• Во время сериализации содержимого ответа
• Во время запуска приложения
• В фоновых задачах

Все исключения, обрабатываемые приложением, по-прежнему должны отслеживаться вручную. Необработанные исключения, исходящие из контроллеров, обычно приводят к ответу "Внутренняя ошибка сервера" 500. Если такой ответ создается вручную в результате обработанного исключения или исключения вообще нет, он отслеживается в соответствующей телеметрии запроса с ResultCode 500. Однако пакет SDK Application Insights не может отслеживать соответствующее исключение.

Поддержка предыдущих версий

Если вы используете MVC 4 (и более ранее) веб-пакета SDK Application Insights 2.5 (и выше), ознакомьтесь со следующими примерами для отслеживания исключений.

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

Веб-API

Начиная с версии 2.6 (бета-версия 3 и более поздней версии) Application Insights собирает необработанные исключения, создаваемые в методах контроллера автоматически для веб-API 2 и более поздних версий. Если вы ранее добавили пользовательский обработчик для отслеживания таких исключений, как описано в следующих примерах, его можно удалить, чтобы предотвратить двойное отслеживание исключений.

Существует несколько случаев, когда фильтры исключений не могут обрабатываться. Рассмотрим пример.

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

Все исключения, обрабатываемые приложением, по-прежнему должны отслеживаться вручную. Необработанные исключения, исходящие из контроллеров, обычно приводят к ответу "Внутренняя ошибка сервера" 500. Если такой ответ создается вручную в результате обработанного исключения или исключения вообще нет, он отслеживается в соответствующей телеметрии запроса с ResultCode 500. Однако пакет SDK Application Insights не может отслеживать соответствующее исключение.

Поддержка предыдущих версий

Если вы используете веб-API 1 (и более ранние версии) веб-пакета SDK Application Insights 2.5 (и более ранних версий), ознакомьтесь со следующими примерами для отслеживания исключений.

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

WCF

Добавьте класс, который расширяет Attribute и реализует IErrorHandler и IServiceBehavior.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

Добавьте атрибут в реализации службы:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Образец

Счетчики производительности исключений

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

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

Платформа .NET Framework вычисляет частоту, подсчитывая количество исключений в интервале и разделяя по длине интервала.

Это число отличается от количества исключений, вычисляемых отчетами на портале TrackException Application Insights. Интервалы выборки отличаются, и пакет SDK не отправляет TrackException отчеты для всех обработанных и необработанных исключений.

Настраиваемая коллекция метрик

Пакеты SDK для Azure Monitor Application Insights для .NET и .NET Core имеют два разных метода сбора пользовательских метрик:

• Метод TrackMetric() , который не имеет предварительной статистической обработки.
• Метод GetMetric() , имеющий предварительную агрегацию.

Мы рекомендуем использовать агрегирование, поэтому TrackMetric()больше не является предпочтительным методом сбора пользовательских метрик. В этой статье описывается использование GetMetric() метода и некоторые из причин его работы.

Начало работы с GetMetric

В наших примерах мы будем использовать базовое приложение рабочей службы .NET Core 3.1. Если вы хотите реплицировать тестовую среду, используемую с этими примерами, выполните действия 1–6 в приложении .NET Core Worker Service. Эти действия добавляют Application Insights в базовый шаблон проекта рабочей службы. Основные понятия применяются к любому общему приложению, в котором можно использовать пакет SDK, включая веб-приложения и консольные приложения.

Отправка метрик

Замените содержимое worker.cs файла следующим кодом:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

При запуске примера кода в while окне вывода Visual Studio отображается цикл, повторяющийся при отправке данных телеметрии. Один элемент телеметрии отправляется вокруг 60-секундной отметки, которая в нашем тесте выглядит следующим образом:

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

Этот элемент телеметрии представляет агрегат 41 различных измерений метрик. Так как мы отправляли одно и то же значение снова и снова, у нас есть стандартное отклонение () с идентичными максимальными (stDev0) max и минимальными (min) значениями. Свойство value представляет сумму всех отдельных значений, которые были агрегированы.

Если мы рассмотрим ресурс Application Insights в интерфейсе Logs (Analytics), отдельный элемент телеметрии будет выглядеть на следующем снимке экрана.

Вы также можете получить доступ к пользовательской телеметрии метрик в разделе "Метрики " портала как на основе журнала, так и на основе пользовательской метрики. На следующем снимка экрана показан пример метрики на основе журнала.

Справочник по метрике кэша для использования высокой пропускной способности

Значения метрик часто могут наблюдаться в некоторых случаях. Например, служба высокой пропускной способности, обрабатывающая 500 запросов в секунду, может потребоваться выдавать 20 метрик телеметрии для каждого запроса. Результат означает отслеживание 10 000 значений в секунду. В таких сценариях с высокой пропускной способностью пользователям может потребоваться помочь пакету SDK, избегая некоторых подстановок.

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

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Помимо кэширования дескриптора метрик, предыдущий пример также сократился Task.Delay до 50 миллисекундах, чтобы цикл выполнялся чаще. Результатом является 772 TrackValue() вызовов.

Многомерные метрики

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

Ниже приведен пример создания одномерной метрики:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Выполнение примера кода не менее 60 секунд приводит к отправке в Azure трех отдельных элементов телеметрии. Каждый элемент представляет агрегат одного из трех форм-факторов. Как и раньше, вы можете продолжить изучение в представлении Журналов (Аналитика).

В обозревателе метрик:

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

По умолчанию многомерные метрики в обозревателе метрик не включаются в ресурсы Application Insights.

Включение многомерных метрик

Чтобы включить многомерные метрики для ресурса Application Insights, выберите "Использование" и "Предполагаемые затраты>",чтобы включить оповещения о пользовательских измерениях>> метрикОК. Дополнительные сведения см. в разделе "Пользовательские измерения метрик" и предварительной статистической обработки.

После внесения этого изменения и отправки новых многомерных данных телеметрии можно выбрать "Применить разделение".

Просмотрите агрегаты метрик для каждого FormFactor измерения.

Использование MetricIdentifier при наличии более трех измерений

В настоящее время поддерживаются 10 измерений. Использование более трех измерений требует использования MetricIdentifier:

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

Настраиваемая конфигурация метрик

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

Специальные имена измерений

Метрики не используют контекст телеметрии, используемый TelemetryClient для доступа к ним. Использование специальных имен измерений, доступных в качестве констант в MetricDimensionNames классе, является оптимальным решением для этого ограничения.

Агрегаты метрик, отправленные приведенными ниже Special Operation Request Size метриками , не имеют Context.Operation.Name значения Special Operation. Метод TrackMetric() или любой другой TrackXXX() метод правильно OperationName задан Special Operation.

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

В этом случае используйте специальные имена измерений, перечисленные в MetricDimensionNames классе, чтобы указать TelemetryContext значения.

Например, если агрегат метрик, полученный из следующей инструкции, отправляется в конечную точку облака Application Insights, его Context.Operation.Name поле данных имеет Special Operationзначение :

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

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

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

Ограничение измерений и временных рядов

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

В контексте ограничения измерений и временных рядов мы используем Metric.TrackValue(..) , чтобы убедиться, что ограничения выполняются. Если ограничения уже достигнуты, Metric.TrackValue(..) возвращается False и значение не отслеживается. В противном случае возвращается True. Это поведение полезно, если данные для метрики исходят из ввода пользователем.

Конструктор MetricConfiguration принимает некоторые параметры по управлению различными рядами в соответствующей метрии и объектом класса, реализующего IMetricSeriesConfiguration агрегаты для каждой отдельной серии метрики:

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call does not track the metric, and returns false.

• seriesCountLimit — максимальное количество временных рядов данных, которые может содержать метрика. Когда это ограничение достигнуто, вызовы TrackValue() к этому обычно приводят к возврату falseновой серии.
• valuesPerDimensionLimit ограничивает число уникальных значений для каждого измерения аналогичным образом.
• restrictToUInt32Values определяет, следует ли отслеживать не только неотрицательных целых значений.

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

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

Отслеживание пользовательских операций

Пакеты SDK Application Insights автоматически отслеживают входящие HTTP-запросы и вызовы зависимых служб, например HTTP-запросы и SQL-запросы. Отслеживание и корреляция запросов и зависимостей обеспечивают видимость отклика и надежности всего приложения во всех микрослужбах, которые объединяют это приложение.

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

В этом разделе содержатся рекомендации по отслеживанию пользовательских операций с помощью пакета SDK Application Insights.

Обзор

Операция — это логическая часть работы, выполняемая приложением. Он имеет имя, время начала, длительность, результат и контекст выполнения, например имя пользователя, свойства и результат. Если операция A была инициирована операцией B, операция B устанавливается как родительская для A. Операция может иметь только один родительский объект, но может иметь множество дочерних операций. Дополнительные сведения об операциях и корреляции телеметрии см. в разделе Корреляция телеметрии Application Insights.

В пакете SDK для Application Insights для .NET операция описывается абстрактным классом OperationTelemetry и его потомками RequestTelemetry и DependencyTelemetry.

Отслеживание входящих операций

Веб-пакет SDK Application Insights автоматически собирает HTTP-запросы для приложений ASP.NET, работающих в конвейере IIS, и всех ASP.NET основных приложений. Существуют решения, поддерживаемые сообществом для других платформ и платформ. Если приложение не поддерживается ни в одном из стандартных или поддерживаемых сообществом решений, его можно инструментирование вручную.

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

Давайте посмотрим, как можно отслеживать такие операции.

На высоком уровне задача состоит в создании RequestTelemetry и задании известных свойств. После завершения операции вы отслеживаете данные телеметрии. В следующем примере показана эта задача.

HTTP-запрос в локальном приложении Owin

В этом примере контекст трассировки распространяется в соответствии с протоколом HTTP для корреляции. Вы должны ожидать получения заголовков, описанных там.

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

Протокол HTTP для корреляции также объявляет Correlation-Context заголовок. Это опущено здесь для простоты.

Инструментирование очередей

Контекст трассировки W3C и ПРОТОКОЛ HTTP для корреляции передают сведения о корреляции с HTTP-запросами, но каждый протокол очереди должен определить, как те же сведения передаются по сообщению очереди. Некоторые протоколы очередей, такие как AMQP, позволяют передавать дополнительные метаданные. Для других протоколов, таких как очередь службы хранилища Azure, требуется закодировать контекст в полезные данные сообщения.

Очередь служебной шины

Сведения о трассировке см. в статье "Распределенная трассировка и корреляция с помощью обмена сообщениями служебной шины Azure".

Очередь службы хранилища Azure

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

Очередь хранилища имеет HTTP-API. Все вызовы очереди отслеживаются сборщиком зависимостей Application Insights для HTTP-запросов. Он настроен по умолчанию для приложений ASP.NET и ASP.NET Core. Сведения о других типах приложений см. в документации по консольным приложениям.

Кроме того, может потребоваться сопоставить идентификатор операции Application Insights с идентификатором запроса хранилища. Сведения о настройке и получении клиента запроса хранилища и идентификатора сервера см. в статье "Мониторинг, диагностика и устранение неполадок службы хранилища Azure".

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

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

При инструментировании удаления сообщений убедитесь, что заданы идентификаторы операции (корреляции). Кроме того, можно использовать Activity API. Затем вам не нужно задавать идентификаторы операций в элементах телеметрии, так как пакет SDK Application Insights делает это для вас:

• Создайте новый Activity элемент после того, как вы получили элемент из очереди.
• Используется Activity.SetParentId(message.ParentId) для сопоставления журналов потребителей и производителей.
• ActivityЗапустите .
• Отслеживайте операции отмены, обработки и удаления с помощью Start/StopOperation вспомогательных средств. Сделайте это из одного и того же асинхронного потока управления (контекст выполнения). Таким образом, они коррелируются должным образом.
• Остановите Activity.
• Используйте Start/StopOperation или вызовите Track данные телеметрии вручную.

Типы зависимостей

Application Insights использует тип зависимостей для настройки пользовательского интерфейса. Для очередей он распознает следующие типы DependencyTelemetry , которые улучшают возможности диагностики транзакций:

• Azure queue для очередей службы хранилища Azure
• Azure Event Hubs Для Центров событий Azure
• Azure Service Bus Для служебной шины Azure

Пакетная обработка

В некоторых очередях можно разоказать несколько сообщений с одним запросом. Обработка таких сообщений предположительно является независимой и принадлежит разным логическим операциям. Невозможно сопоставить Dequeue операцию с определенным обработанным сообщением.

Каждое сообщение должно обрабатываться в собственном асинхронном потоке управления. Дополнительные сведения см. в разделе отслеживания исходящих зависимостей .

Длительные фоновые задачи

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

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

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

Когда задача начинается с фонового потока, с которым не связана Activity операция (BackgroundTask), не имеет родительского элемента. Однако он может иметь вложенные операции. Все элементы телеметрии, сообщаемые из задачи, коррелируются с DependencyTelemetry созданным в BackgroundTask.

Отслеживание исходящих зависимостей

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

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

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

• TelemetryClient.StartOperation Вызовите метод (extension), который заполняет DependencyTelemetry свойства, необходимые для корреляции, и некоторые другие свойства, такие как начальная, метка времени и длительность.
• Задайте другие настраиваемые свойства в поле DependencyTelemetry, например имя и любой другой контекст.
• Вызов зависимостей и подождите его.
• Остановите операцию после StopOperation завершения.
• Обработка исключений.

public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

Удаление операции приводит к остановке операции, поэтому ее можно сделать вместо вызова StopOperation.

Параллельные операции обработки и отслеживания

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

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Убедитесь, что вы всегда вызываете StartOperation и обрабатываете операцию в одном асинхронном методе, чтобы изолировать операции, выполняемые параллельно. Если операция синхронна (или не асинхронна), обтекайте процесс и отслеживайте его.Task.Run

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Операции ApplicationInsights и System.Diagnostics.Activity

System.Diagnostics.Activity представляет контекст распределенной трассировки и используется платформами и библиотеками для создания и распространения контекста внутри и за пределами процесса и сопоставления элементов телеметрии. Activity работает вместе с System.Diagnostics.DiagnosticSource механизмом уведомлений между платформой или библиотекой, чтобы уведомить о интересных событиях, таких как входящие или исходящие запросы и исключения.

Действия — это функции верхнего уровня в Application Insights. Автоматическая зависимость и сбор запросов сильно зависят от них вместе с событиями DiagnosticSource . Если вы создали в приложении, это не приведет к созданию Activity телеметрии Application Insights. Application Insights должен получать события DiagnosticSource, а также знать имена событий и нагрузку данных для перевода Activity в данные телеметрии.

Каждая операция Application Insights (запрос или зависимость) включает в себя Activity. При StartOperation вызове он создает Activity под ним. StartOperation рекомендуется отслеживать данные телеметрии запросов или зависимостей вручную и убедиться, что все сопоставляется.

Счетчики в Application Insights

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

Обзор

Счетчики производительности

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

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

Предпосылки

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

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Просмотр счетчиков

На панели метрик показан набор счетчиков производительности по умолчанию.

Добавление счетчиков

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

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();

Сбор счетчиков производительности в коде для веб-приложений ASP.NET или консольных приложений .NET/.NET Core

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

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Или вы можете сделать то же самое с пользовательскими метриками, созданными вами:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Счетчики производительности для приложений, работающих в веб-приложениях Azure и контейнерах Windows в Службе приложений Azure

Оба приложения ASP.NET и ASP.NET Core, развернутые в веб-приложениях Azure, выполняются в специальной песочнице. Приложения, развернутые в Службе приложений Azure, могут использовать контейнер Windows или размещаться в изолированной среде. Если приложение развертывается в контейнере Windows, все стандартные счетчики производительности доступны на образе контейнера.

Среда песочницы не разрешает прямой доступ к счетчикам производительности системы. Однако ограниченное подмножество счетчиков предоставляется в виде переменных среды, как описано в счетчиках Perf, предоставляемых как переменные среды. В этой среде доступно только подмножество счетчиков. Полный список см. в разделе Счетчики Perf, предоставляемые как переменные среды.

Пакет SDK Application Insights для ASP.NET и ASP.NET Core определяет, развертывается ли код в веб-приложении или контейнере, отличном от Windows. Обнаружение определяет, собирает ли он счетчики производительности в изолированной среде или использует стандартный механизм сбора данных при размещении в контейнере Windows или виртуальной машине.

Запросы Log Analytics для счетчиков производительности

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

Схема performanceCounters предоставляет categoryимя counter и instance имя каждого счетчика производительности. В телеметрии для каждого приложения отображаются только счетчики для этого приложения. Например, чтобы узнать, какие счетчики доступны:

performanceCounters | summarize count(), avg(value) by category, instance, counter

Instance Здесь относится к экземпляру счетчика производительности, а не к экземпляру компьютера сервера. Имя экземпляра счетчика производительности обычно сегментирует счетчики, например время процессора, по имени процесса или приложения.

Чтобы получить диаграмму доступной памяти за последний период:

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

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

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

Вопросы и ответы о счетчиках производительности

Чтобы просмотреть часто задаваемые вопросы (часто задаваемые вопросы) см. вопросы и ответы о счетчиках производительности.

Счетчики событий

EventCounter — это механизм .NET/.NET Core для публикации и использования счетчиков или статистики. СобытияCounters поддерживаются во всех платформах ОС — Windows, Linux и macOS. Его можно рассматривать как кроссплатформенный эквивалент для performanceCounters , который поддерживается только в системах Windows.

Хотя пользователи могут публиковать любые настраиваемые счетчики событий в соответствии с потребностями, .NET публикует набор этих счетчиков по умолчанию. В этом документе описаны шаги, необходимые для сбора и просмотра счетчиков событий (определенных системой или пользователем) в Azure Application Insights.

Использование Application Insights для сбора событийCounters

Application Insights поддерживает сбор EventCounters с его EventCounterCollectionModuleпомощью, который является частью недавно выпущенного пакета NuGet Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule автоматически включается при использовании AspNetCore или WorkerService. EventCounterCollectionModule собирает счетчики с неконфигурируемой частотой сбора в 60 секунд. Для сбора eventCounters не требуются специальные разрешения. Для приложений ASP.NET Core вы также хотите добавить пакет Microsoft.ApplicationInsights.AspNetCore .

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Собранные счетчики по умолчанию

Начиная с версии 2.15.0 пакета SDK AspNetCore или пакета SDK WorkerService, счетчики по умолчанию не собираются. Сам модуль включен, чтобы пользователи могли добавлять нужные счетчики для их сбора.

Чтобы получить список известных счетчиков, опубликованных средой выполнения .NET, см. в документе "Доступные счетчики ".

Настройка счетчиков для сбора

В следующем примере показано, как добавить или удалить счетчики. Эта настройка будет выполнена как часть конфигурации службы приложений после включения сбора данных телеметрии Application Insights с помощью либо AddApplicationInsightsTelemetry()AddApplicationInsightsWorkerService(). Ниже приведен пример кода из приложения ASP.NET Core. Сведения о других типах приложений см. в разделе "Настройка модулей телеметрии".

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );

Отключение модуля коллекции EventCounter

EventCounterCollectionModule можно отключить с помощью ApplicationInsightsServiceOptions.

В следующем примере используется пакет SDK ASP.NET Core.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

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

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Запросы Log Analytics для счетчиков событий

Вы можете искать и отображать отчеты счетчиков событий в Log Analytics в таблице customMetrics .

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

customMetrics | summarize avg(value) by name

Чтобы получить диаграмму определенного счетчика (например: ThreadPool Completed Work Item Count) за последний период, выполните следующий запрос.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

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

Вопросы и ответы о счетчиках событий

Чтобы просмотреть часто задаваемые вопросы (часто задаваемые вопросы) см. ответы о счетчиках событий.

Фильтрация и обогащение телеметрии

В этом разделе

• Фильтрация и предварительная обработка телеметрии
• Инициализаторы телеметрии
• Обработчик телеметрии
• Выборка
• Обогащение данных через HTTP

Фильтрация и предварительная обработка телеметрии

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

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

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

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

Filtering

Этот метод обеспечивает прямой контроль над тем, что включается или исключается из потока телеметрии. Фильтрация может использоваться для исключения элементов телеметрии из передачи в Application Insights. Фильтрацию можно использовать с сэмплированием или отдельно.

Чтобы отфильтровать данные телеметрии, необходимо написать обработчик телеметрии и зарегистрировать его в TelemetryConfiguration. Все данные телеметрии проходят через процессор. Вы можете удалить его из потока или передать его следующему процессору в цепочке. Данные телеметрии из стандартных модулей, таких как сборщик HTTP-запросов и сборщик зависимостей, а также данные телеметрии, которые вы отслеживали самостоятельно. Например, можно отфильтровать данные телеметрии о запросах от роботов или успешных вызовов зависимостей.

ITelemetryProcessor и ITelemetryInitializer

Какова разница между процессорами телеметрии и инициализаторами телеметрии?

• Есть некоторые пересечения в том, что вы можете делать с ними. Их можно использовать для добавления или изменения свойств телеметрии, хотя мы рекомендуем использовать инициализаторы для этой цели.
• Инициализаторы телеметрии всегда выполняются перед процессорами телеметрии.
• Инициализаторы телеметрии могут вызываться несколько раз. По соглашению они не задают какое-либо свойство, которое уже было задано.
• Процессоры телеметрии позволяют полностью заменить или отменить элемент телеметрии.
• Все зарегистрированные инициализаторы телеметрии вызываются для каждого элемента телеметрии. Для процессоров телеметрии пакет SDK гарантирует вызов первого процессора телеметрии. Определение того, будут ли вызваны остальные процессоры, осуществляется предыдущими процессорами телеметрии.
• Инициализаторы телеметрии используются для обогащения телеметрии дополнительными свойствами или переопределения существующей. Используйте обработчик телеметрии для фильтрации телеметрии.

Добавление и изменение свойств

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

Например, Application Insights для веб-пакета собирает данные телеметрии о HTTP-запросах. По умолчанию он помечает любой запрос с кодом ответа >>=400 как неудачный. Если вместо этого вы хотите рассматривать 400 как успешный, можно предоставить инициализатор телеметрии, который задает свойство успешности.

Если вы предоставляете инициализатор телеметрии, он вызывается всякий раз, когда вызывается любой из методов Track*(). Этот инициализатор включает Track() методы, вызываемые стандартными модулями телеметрии. По соглашению эти модули не задают никаких свойств, которые уже были заданы инициализатором. Инициализаторы телеметрии вызываются перед вызовом процессоров телеметрии, поэтому любые обогащения, выполненные инициализаторами, видны процессорам.

Инициализаторы телеметрии

Чтобы дополнить данные телеметрии дополнительными сведениями или переопределить свойства телеметрии, заданные стандартными модулями телеметрии, используйте инициализаторы телеметрии.

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

Стандартные инициализаторы устанавливаются либо веб-пакетами NuGet, либо пакетами NuGet для WindowsServer.

Добавить ITelemetryInitializer

Этот блог описывает проект для диагностики проблем зависимости путем автоматической отправки регулярных пингов в зависимости.

1. Определение инициализатора

   using System;
   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.DataContracts;
   using Microsoft.ApplicationInsights.Extensibility;
   
   namespace MvcWebRole.Telemetry
   {
     /*
      * Custom TelemetryInitializer that overrides the default SDK
      * behavior of treating response codes >= 400 as failed requests
      *
      */
       public class MyTelemetryInitializer : ITelemetryInitializer
       {
           public void Initialize(ITelemetry telemetry)
           {
               var requestTelemetry = telemetry as RequestTelemetry;
               // Is this a TrackRequest() ?
               if (requestTelemetry == null) return;
               int code;
               bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
               if (!parsed) return;
               if (code >= 400 && code < 500)
               {
                   // If we set the Success property, the SDK won't change it:
                   requestTelemetry.Success = true;
   
                   // Allow us to filter these requests in the portal:
                   requestTelemetry.Properties["Overridden400s"] = "true";
               }
               // else leave the SDK to set the Success property
           }
       }
   }
   

2. Загрузка инициализатора

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

        // Remove all initializers.
        // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
        services.RemoveAll(typeof(ITelemetryInitializer));
   }

Примеры ITelemetryInitializers

Добавление настраиваемого свойства

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

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Добавление имени облачной роли

Следующий пример инициализатора задает имя облачной роли для каждой отслеживаемой телеметрии.

public void Initialize(ITelemetry telemetry)
{
    if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
    {
        telemetry.Context.Cloud.RoleName = "MyCloudRoleName";
    }
}

Управление IP-адресом клиента, используемым для сопоставления геолокаций

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

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

Обработчики данных телеметрии

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

1. Реализуйте расширение ITelemetryProcessor.

   Процессоры телеметрии создают цепочку обработки. При инстанцировании обработчика телеметрии вы получите ссылку на следующий процессор в цепочке. Когда точка данных телеметрии передается методу процесса, она выполняет свою работу, а затем вызывает (или не вызывает) следующий обработчик телеметрии в цепочке.

   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.Extensibility;
   using Microsoft.ApplicationInsights.DataContracts;
   
   public class SuccessfulDependencyFilter : ITelemetryProcessor
   {
       private ITelemetryProcessor Next { get; set; }
   
       // next will point to the next TelemetryProcessor in the chain.
       public SuccessfulDependencyFilter(ITelemetryProcessor next)
       {
           this.Next = next;
       }
   
       public void Process(ITelemetry item)
       {
           // To filter out an item, return without calling the next processor.
           if (!OKtoSend(item)) { return; }
   
           this.Next.Process(item);
       }
   
       // Example: replace with your own criteria.
       private bool OKtoSend (ITelemetry item)
       {
           var dependency = item as DependencyTelemetry;
           if (dependency == null) return true;
   
           return dependency.Success != true;
       }
   }
   

2. Добавьте процессор.

   • ASP.NET
   • ASP.NET Core
   • Рабочая служба

   Вставьте этот фрагмент кода в ApplicationInsights.config:

   <TelemetryProcessors>
     <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
       <!-- Set public property -->
       <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
     </Add>
   </TelemetryProcessors>
   

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

   Предупреждение

   Обратите внимание, что имя типа и все имена свойств в файле .config соответствуют именам классов и свойств в коде. Если файл .config ссылается на несуществующий тип или свойство, пакет SDK может автоматически не отправлять данные телеметрии.

   Кроме того, можно инициализировать фильтр в коде. Например, в подходящем классе инициализации, например, в AppStart, вставьте ваш процессор в Global.asax.cs цепочку.

   Замечание

   Следующий пример кода устарел, но доступен здесь для потомства. Попробуйте приступить к работе с OpenTelemetry или перейти на OpenTelemetry.

   var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
   builder.Use((next) => new SuccessfulDependencyFilter(next));
   
   // If you have more processors:
   builder.Use((next) => new AnotherProcessor(next));
   
   builder.Build();
   

   Клиенты телеметрии, созданные после этого момента, используют процессоры.

   Обработчик телеметрии адаптивной выборки (от 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>
   

Примеры фильтров

Искусственные запросы

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

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Сбой проверки подлинности

Отфильтровать запросы с помощью ответа "401".

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

Исключить быстрые удаленные вызовы зависимостей

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

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

Выборка

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Обогащение данных по протоколу HTTP

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Управление компонентами пакета SDK

В этом разделе

• Каналы телеметрии
• Модули телеметрии
• Отключение телеметрии
• Поставщик ApplicationId
• Коллекция моментальных снимков

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

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

Каналы телеметрии являются неотъемлемой частью пакетов SDK Application Insights. Они управляют буферизацией и передачей данных телеметрии в службу Application Insights. В версиях пакетов SDK для .NET и .NET Core есть два встроенных канала телеметрии: InMemoryChannel и ServerTelemetryChannel. В этом разделе описывается каждый канал и показано, как настроить поведение канала.

Что такое каналы телеметрии?

Каналы телеметрии отвечают за буферизацию элементов телеметрии и отправку их в службу Application Insights, где они хранятся для запроса и анализа. Канал телеметрии — это любой класс, реализующий Microsoft.ApplicationInsights.ITelemetryChannel интерфейс.

Метод Send(ITelemetry item) канала телеметрии вызывается после вызова всех инициализаторов телеметрии и процессоров телеметрии. Таким образом, все элементы, удаленные обработчиком телеметрии, не достигают канала. Метод Send() обычно не отправляет элементы в серверную часть мгновенно. Как правило, он буферизирует их в памяти и отправляет их в пакеты для эффективной передачи.

Flush() Избегайте вызовов, если не важно немедленно отправлять буферизованные данные телеметрии. Используйте его только в таких сценариях, как завершение работы приложения, обработка исключений или использование кратковременных процессов, таких как фоновые задания или средства командной строки. В веб-приложениях или длительных службах пакет SDK автоматически обрабатывает передачу данных телеметрии. Вызов Flush() ненужно может вызвать проблемы с производительностью.

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

Встроенные каналы телеметрии

Пакеты SDK для Application Insights .NET и .NET Core поставляется с двумя встроенными каналами:

• InMemoryChannel: Упрощенный канал, который буферизирует элементы в памяти, пока они не будут отправлены. Элементы буферизуются в памяти и сбрасываются каждые 30 секунд или каждый раз, когда буферизуются 500 элементов. Этот канал предлагает минимальные гарантии надежности, так как он не повторяет отправку данных телеметрии после сбоя. Этот канал также не хранит элементы на диске. Таким образом, любые неотступные элементы теряются окончательно после завершения работы приложения, будь то грациозно или нет. Этот канал реализует Flush() метод, который можно использовать для принудительной очистки любых элементов телеметрии в памяти синхронно. Этот канал хорошо подходит для коротких приложений, где синхронный сброс идеально подходит.

  Этот канал является частью более крупного пакета NuGet Microsoft.ApplicationInsights и является каналом по умолчанию, используемым пакетом SDK, если ничего другого не настроено.

• ServerTelemetryChannel: Более сложный канал с политиками повторных попыток и возможностью хранения данных на локальном диске. Этот канал повторяет отправку данных телеметрии при возникновении временных ошибок. Этот канал также использует локальное хранилище дисков для хранения элементов на диске во время сбоя сети или больших томов телеметрии. Из-за этих механизмов повторных попыток и локального дискового хранилища этот канал считается более надежным. Мы рекомендуем использовать его для всех рабочих сценариев. Этот канал используется по умолчанию для ASP.NET и ASP.NET основных приложений, настроенных в соответствии с официальной документацией. Этот канал оптимизирован для сценариев сервера с длительными процессами. Метод Flush() , реализованный этим каналом, не синхронный.

  Этот канал поставляется как пакет NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel NuGet и автоматически приобретается при использовании пакета NuGet Microsoft.ApplicationInsights.Web или Microsoft.ApplicationInsights.AspNetCore NuGet.

Настройка канала телеметрии

Канал телеметрии настраивается путем настройки активной конфигурации телеметрии. Для приложений ASP.NET конфигурация включает настройку экземпляра канала телеметрии или TelemetryConfiguration.Active изменения ApplicationInsights.config. Для приложений ASP.NET Core конфигурация включает добавление канала в контейнер внедрения зависимостей.

В следующих разделах показаны примеры настройки StorageFolder параметра для канала в различных типах приложений. StorageFolder — это только один из настраиваемых параметров. Полный список параметров конфигурации см. в разделе "Настраиваемые параметры" в разделе каналов далее в этой статье.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetryWorkerService();
    }

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

Для консольных приложений код совпадает как для .NET, так и для .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Операционные сведения о ServerTelemetryChannel

ServerTelemetryChannel сохраняет поступающие элементы в буфере в памяти. Элементы сериализуются, сжимаются и хранятся в Transmission экземпляре каждые 30 секунд или при буферизации 500 элементов. Один Transmission экземпляр содержит до 500 элементов и представляет пакет телеметрии, который отправляется через один вызов HTTPS в службу Application Insights.

По умолчанию можно отправлять не более 10 Transmission экземпляров параллельно. Если телеметрия поступает быстрее, или если сеть или серверная часть Application Insights медленно, Transmission экземпляры хранятся в памяти. Емкость этого буфера в памяти Transmission по умолчанию составляет 5 МБ. При превышении Transmission емкости в памяти экземпляры хранятся на локальном диске до предела 50 МБ.

Transmission экземпляры хранятся на локальном диске также при возникновении проблем с сетью. Только те элементы, которые хранятся на локальном диске, выживают сбой приложения. Они отправляются всякий раз, когда приложение запускается снова. Если проблемы с сетью сохраняются, ServerTelemetryChannel использует логику экспоненциальной обратной передачи от 10 секунд до 1 часа до повторных попыток отправки данных телеметрии.

Настраиваемые параметры в каналах

Полный список настраиваемых параметров для каждого канала см. в следующих статье:

• InMemoryChannel
• ServerTelemetryChannel

Ниже приведены наиболее часто используемые параметры для ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: максимальный объем памяти в байтах, используемый каналом для буферизации передач в памяти. После достижения этой емкости новые элементы хранятся непосредственно на локальном диске. Значение по умолчанию — 5 МБ. Установка более высокого значения приводит к меньшему использованию диска, но помните, что элементы в памяти теряются, если приложение завершает работу.

• MaxTransmissionSenderCapacity: максимальное количество экземпляров Transmission , отправляемых в Application Insights одновременно. Значение по умолчанию — 10. Этот параметр можно настроить на более высокое число, которое рекомендуется при создании огромного объема телеметрии. Высокий объем обычно возникает во время нагрузочного тестирования или при отключении выборки.

• StorageFolder: папка, используемая каналом для хранения элементов на диске по мере необходимости. В Windows %LOCALAPPDATA% или %TEMP% используется, если ни один другой путь не указан явным образом. В средах, отличных от Windows, по умолчанию используются следующие расположения (в порядке): %TMPDIR%, /var/tmp/ или /tmp/.

Какой канал следует использовать?

Для большинства рабочих сценариев рекомендуется использовать ServerTelemetryChannel длительные приложения. Дополнительные сведения об очистке телеметрии см. в статье об использовании Flush().

Когда следует использовать Flush()

Метод Flush() немедленно отправляет любые буферизованные данные телеметрии. Однако его следует использовать только в определенных сценариях.

Flush() следует использовать в следующих случаях:

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

Избегайте использования Flush() в длительных приложениях, таких как веб-службы. Пакет SDK автоматически управляет буферизацией и передачей. Вызов Flush() ненужно может вызвать проблемы с производительностью и не гарантирует отправку всех данных, особенно при использовании ServerTelemetryChannel, которая не синхронно очищает.

Модули телеметрии

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

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

Настройка модулей телеметрии

<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "keyhere";
            });

            // The following removes PerformanceCollectorModule to disable perf-counter collection.
            // Similarly, any other default modules can be removed.
            var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>
                                        (t => t.ImplementationType == typeof(PerformanceCollectorModule));
            if (performanceCounterService != null)
            {
                services.Remove(performanceCounterService);
            }
    }

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

Отключение телеметрии

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

Строка подключения

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

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

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

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        var telemetryClient = new TelemetryClient(configuration);

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

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

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";

app.Run();

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
tc.TrackEvent("myEvent");
// ...

Поставщик ApplicationId

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

Эта функция доступна по параметру TelemetryConfiguration.ApplicationIdProvider.

Интерфейс: IApplicationIdProvider

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

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

ApplicationInsightsApplicationIdProvider

Это оболочка для API профилей. Он регулирует запросы и кэширует результаты. Этот поставщик автоматически включается при установке Microsoft.ApplicationInsights.DependencyCollector или Microsoft.ApplicationInsights.Web.

Класс предоставляет необязательное свойство ProfileQueryEndpoint. По умолчанию для него задано значение https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Если необходимо настроить прокси-сервер, рекомендуется использовать базовый адрес и обеспечить включение /api/profiles/{0}/appIdпути. Во время выполнения {0} заменяется ключ инструментирования для каждого запроса.

<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();

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

DictionaryApplicationIdProvider

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

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

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

<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"}
    }
};

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "InstrumentationKey_1", "ApplicationId_1" },
            { "InstrumentationKey_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Настройка коллекции моментальных снимков

Сведения о настройке коллекции моментальных снимков для приложений ASP.NET и ASP.NET Core см. в статье "Включение отладчика моментальных снимков" для приложений .NET в Azure Service Fabric, облачных службах и виртуальных машинах.

Добавление наблюдения на стороне клиента

В предыдущих разделах приведено руководство по методам автоматической и ручной настройки наблюдения на стороне сервера. Чтобы добавить клиентский мониторинг, используйте клиентский пакет SDK JavaScript. Вы можете отслеживать клиентские транзакции любой веб-страницы, добавив скрипт загрузчика пакета SDK JavaScript (Web) перед закрывающим </head> тегом HTML страницы.

Хотя можно вручную добавить скрипт загрузчика пакета SDK JavaScript (Web) в заголовок каждой HTML-страницы, рекомендуется добавить скрипт загрузчика пакета SDK JavaScript (Web) на основную страницу. Это действие внедряет скрипт загрузчика пакета SDK JavaScript (Web) на все страницы сайта.

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

Примеры приложений

Консольное приложение .NET Core: используйте этот пример, если вы используете консольное приложение, написанное в .NET Core (2.0 или более поздней версии) или .NET Framework (4.7.2 или более поздней версии).

Фоновые задачи в ASP.NET Core с Hosted Services: используйте этот пример, если вы работаете с ASP.NET Core и создаете фоновые задачи согласно официальному руководству.

Фоновая служба .NET Core: используйте этот пример, если у вас есть приложение .NET фоновой службы в соответствии с официальным руководством.

Устранение неполадок

См. статью об устранении неполадок.

В Visual Studio 2019 возникла известная проблема: хранение ключа инструментирования или строка подключения в секрете пользователя нарушается для приложений на основе платформа .NET Framework. Ключ в конечном счете должен быть жестко закодирован в файл Applicationinsights.config , чтобы обойти эту ошибку. Эта статья позволит полностью устранить данную проблему за счет отказа от использования секретов пользователя.

Проверьте соединение между сервером вашего приложения и службой приема данных

Пакеты SDK и агенты Application Insights отправляют телеметрические данные, которые обрабатываются в виде вызовов REST на наших конечных точках приема. Вы можете протестировать подключение с веб-сервера или хост-компьютера приложения к конечным точкам службы приема, используя чистых REST-клиентов из PowerShell или из команд curl. См. Устранение неполадок с отсутствующей телеметрией приложений в Azure Monitor Application Insights.

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

Чтение и участие в коде.

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

Заметки о релизе

Для версии 2.12 и более поздних версий: пакеты SDK для .NET, включая ASP.NET, ASP.NET Core и адаптеры ведения журнала

Обновления службы также обобщают основные улучшения Application Insights.

Дальнейшие шаги

• Чтобы просмотреть часто задаваемые вопросы (вопросы и ответы), см. следующие сведения:
  • Часто задаваемые вопросы о Application Insights для ASP.NET
  • Вопросы и ответы по Application Insights для ASP.NET Core
  • Часто задаваемые вопросы о приложениях рабочей службы
• Убедитесь, что вы используете поддерживаемую версию пакета SDK Application Insights.
• См. модель данных для типов Application Insights и модели данных.
• Добавьте искусственные транзакции для проверки того, что веб-сайт доступен во всем мире с мониторингом доступности.
• Ознакомьтесь с руководством пользователя System.Diagnostics.Activity , чтобы узнать, как сопоставить данные телеметрии.
• Настройте коллекцию моментальных снимков для отображения состояния исходного кода и переменных в момент создания исключения.
• Для получения более четкого представления о производительности и использовании приложения используйте API для отправки собственных событий и метрик.

Справочная документация

• Справочник по типам данных для пакета SDK ASP.NET и пакета SDK для ASP.NET Core.
• Код пакета SDK для пакета SDK ASP.NET и пакета SDK для ASP.NET Core.