Usługa Application Insights dla aplikacji ASP.NET Core

Artykuł
05/03/2023

W tym artykule opisano sposób włączania i konfigurowania usługi Application Insights dla aplikacji ASP.NET Core.

Usługa Application Insights może zbierać następujące dane telemetryczne z aplikacji ASP.NET Core:

Żądania
Zależności
Wyjątki
Liczniki wydajności
Bicie serca
Dzienniki

Używamy przykładu aplikacji MVC . Jeśli używasz usługi Worker Service, skorzystaj z instrukcji w temacie Application Insights for Worker Service applications (Aplikacje usługi Procesu roboczego usługi Application Insights dla procesów roboczych).

Dostępna jest wersja zapoznawcza oferty platformy .NET opartej na technologii OpenTelemetry . Aby uzyskać więcej informacji, zobacz Omówienie technologii OpenTelemetry.

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pozyskiwanie klucza instrumentacji będzie nadal działać, ale nie będziemy już zapewniać aktualizacji ani obsługi funkcji. Przejście do parametrów połączenia w celu skorzystania z nowych możliwości.

Uwaga

Jeśli chcesz użyć autonomicznego dostawcy ILogger, użyj elementu Microsoft.Extensions.Logging.ApplicationInsight.

Obsługiwane scenariusze

Zestaw SDK usługi Application Insights dla ASP.NET Core może monitorować aplikacje niezależnie od tego, gdzie i jak działają. Jeśli aplikacja jest uruchomiona i ma łączność sieciową z platformą Azure, można zbierać dane telemetryczne. Monitorowanie usługi Application Insights jest obsługiwane wszędzie, gdzie platforma .NET Core jest obsługiwana i obejmuje następujące scenariusze:

System operacyjny: Windows, Linux lub Mac
Metoda hostingu: w procesie lub poza procesem
Metoda wdrażania: zależna od struktury lub samodzielna
Serwer sieci Web: Internet Information Server (IIS) lub Kestrel
Platforma hostingu: funkcja Web Apps Azure App Service, Azure Virtual Machines, Docker i Azure Kubernetes Service (AKS)
Wersja platformy .NET: wszystkie oficjalnie obsługiwane wersje platformy .NET , które nie są dostępne w wersji zapoznawczej
IDE: Visual Studio, Visual Studio Code lub wiersz polecenia

Wymagania wstępne

Potrzebne elementy:

Działająca aplikacja ASP.NET Core. Jeśli musisz utworzyć aplikację ASP.NET Core, wykonaj czynności opisane w tym samouczku ASP.NET Core.
Odwołanie do obsługiwanej wersji pakietu NuGet usługi Application Insights .
Prawidłowe parametry połączenia usługi Application Insights. Ten ciąg jest wymagany do wysyłania wszystkich danych telemetrycznych do usługi Application Insights. Jeśli musisz utworzyć nowy zasób usługi Application Insights, aby uzyskać parametry połączenia, zobacz Tworzenie zasobu usługi Application Insights.

Włączanie telemetrii po stronie serwera usługi Application Insights (Visual Studio)

Aby uzyskać Visual Studio dla komputerów Mac, skorzystaj z wskazówek ręcznych. Ta procedura jest obsługiwana tylko w wersji systemu Windows programu Visual Studio.

Otwórz projekt w programie Visual Studio.
Przejdź do pozycji ProjectAdd Application Insights Telemetry (Dodaj > telemetrię usługi Application Insights).
Wybierz pozycję aplikacja systemu Azure Insights>Next (Dalej).
Wybierz subskrypcję i wystąpienie usługi Application Insights. Możesz też utworzyć nowe wystąpienie za pomocą polecenia Utwórz nowe. Wybierz opcję Dalej.
Dodaj lub potwierdź parametry połączenia usługi Application Insights. Powinna zostać wstępnie wypełniona na podstawie wybranego elementu w poprzednim kroku. Wybierz pozycję Zakończ.
Po dodaniu usługi Application Insights do projektu sprawdź, czy używasz najnowszej stabilnej wersji zestawu SDK. Przejdź do pozycji ProjectManage NuGet PackagesMicrosoft.ApplicationInsights.AspNetCore (Zarządzanie pakietami>> NuGet Microsoft.ApplicationInsights.AspNetCore). Jeśli chcesz, wybierz pozycję Aktualizuj.

Włączanie telemetrii po stronie serwera usługi Application Insights (bez programu Visual Studio)

Zainstaluj pakiet NuGet zestawu SDK usługi Application Insights dla ASP.NET Core.

Zalecamy, aby zawsze używać najnowszej stabilnej wersji. Znajdź pełne informacje o wersji zestawu SDK w repozytorium GitHub typu open source.

Poniższy przykładowy kod przedstawia zmiany, które należy dodać do pliku projektu .csproj :
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

Dodaj AddApplicationInsightsTelemetry() element do klasy startup.cs lub program.cs . Wybór zależy od wersji platformy .NET Core.

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

Dodaj builder.Services.AddApplicationInsightsTelemetry(); po metodzie WebApplication.CreateBuilder() w Program klasie, jak w tym przykładzie:

// This method gets called by the runtime. Use this method to add services to the container.
var builder = WebApplication.CreateBuilder(args);

// The following line enables Application Insights telemetry collection.
builder.Services.AddApplicationInsightsTelemetry();

// This code adds other services for your application.
builder.Services.AddMvc();

var app = builder.Build();

Dodaj services.AddApplicationInsightsTelemetry(); do ConfigureServices() metody w Startup klasie, jak w tym przykładzie:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // The following line enables Application Insights telemetry collection.
    services.AddApplicationInsightsTelemetry();

    // This code adds other services for your application.
    services.AddMvc();
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

Skonfiguruj parametry połączenia.

Mimo że parametry połączenia można podać jako część argumentu ApplicationInsightsServiceOptions , AddApplicationInsightsTelemetryzalecamy określenie parametrów połączenia w konfiguracji. Poniższy przykładowy kod pokazuje, jak określić parametry połączenia w pliku appsettings.json. Podczas publikowania upewnij się, że appsettings.json plik został skopiowany do folderu głównego aplikacji.
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}
```
Alternatywnie określ parametry połączenia w zmiennej APPLICATIONINSIGHTS_CONNECTION_STRING środowiskowej lub ApplicationInsights:ConnectionString w pliku konfiguracji JSON.

Na przykład:
- SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
- SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
- APPLICATIONINSIGHTS_CONNECTION_STRING Zazwyczaj jest używany w Web Apps. Można go również używać we wszystkich miejscach, w których jest obsługiwany ten zestaw SDK.
Uwaga

Parametry połączenia określone w kodzie wygrywają za pomocą zmiennej środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING, która wygrywa z innymi opcjami.

Wpisy tajne użytkownika i inni dostawcy konfiguracji

Jeśli chcesz przechowywać parametry połączenia w ASP.NET Core wpisach tajnych użytkownika lub pobrać je z innego dostawcy konfiguracji, możesz użyć przeciążenia z parametrem Microsoft.Extensions.Configuration.IConfiguration . Przykładowy parametr to services.AddApplicationInsightsTelemetry(Configuration);.

W Microsoft.ApplicationInsights.AspNetCore wersji 2.15.0 lub nowszej wywołanie services.AddApplicationInsightsTelemetry() automatycznie odczytuje parametry połączenia z Microsoft.Extensions.Configuration.IConfiguration aplikacji. Nie ma potrzeby jawnego podawania IConfiguration.

Jeśli IConfiguration konfiguracja została załadowana od wielu dostawców, services.AddApplicationInsightsTelemetry określa priorytety konfiguracji od appsettings.json, niezależnie od kolejności dodawania dostawców. services.AddApplicationInsightsTelemetry(IConfiguration) Użyj metody , aby odczytać konfigurację z IConfiguration bez tego preferencyjnego traktowania dla appsettings.json.

Uruchamianie aplikacji

Uruchom aplikację i wysyłaj do niej żądania. Dane telemetryczne powinny teraz przepływać do usługi Application Insights. Zestaw SDK usługi Application Insights automatycznie zbiera przychodzące żądania internetowe do aplikacji wraz z następującymi danymi telemetrycznymi.

Metryki na żywo

Metryki na żywo mogą służyć do szybkiego sprawdzania, czy monitorowanie usługi Application Insights jest poprawnie skonfigurowane. Wyświetlenie danych telemetrycznych w portalu i analizie może potrwać kilka minut, ale metryki na żywo pokazują użycie procesora CPU uruchomionego procesu niemal w czasie rzeczywistym. Może również wyświetlać inne dane telemetryczne, takie jak żądania, zależności i ślady.

Dzienniki ILogger

Domyślna konfiguracja zbiera ILoggerWarning dzienniki i poważniejsze dzienniki. Aby uzyskać więcej informacji, zobacz Jak mogę dostosować kolekcję dzienników ILogger?.

Zależności

Kolekcja zależności jest domyślnie włączona. Funkcja śledzenia zależności w usłudze Application Insights wyjaśnia zależności, które są automatycznie zbierane, a także zawiera kroki umożliwiające ręczne śledzenie.

Liczniki wydajności

Obsługa liczników wydajności w ASP.NET Core jest ograniczona:

Zestaw SDK w wersji 2.4.1 lub nowszej zbiera liczniki wydajności, jeśli aplikacja jest uruchomiona w systemie Web Apps (Windows).
Zestaw SDK w wersji 2.7.1 lub nowszej zbiera liczniki wydajności, jeśli aplikacja jest uruchomiona w systemie Windows i jest przeznaczona dla użytkowników docelowych netstandard2.0 lub nowszych.
W przypadku aplikacji przeznaczonych dla .NET Framework wszystkie wersje zestawu SDK obsługują liczniki wydajności.
Zestaw SDK w wersji 2.8.0 lub nowszej obsługuje licznik procesora CPU/pamięci w systemie Linux. Żaden inny licznik nie jest obsługiwany w systemie Linux. Aby uzyskać liczniki systemowe w systemach Linux i innych środowiskach innych niż Windows, użyj funkcji EventCounters.

EventCounter

Domyślnie EventCounterCollectionModule jest włączona. Aby dowiedzieć się, jak skonfigurować listę liczników do zbierania, zobacz Wprowadzenie do funkcji EventCounters.

Wzbogacanie danych za pośrednictwem protokołu HTTP

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

Włączanie telemetrii po stronie klienta dla aplikacji internetowych

Powyższe kroki są wystarczające, aby ułatwić rozpoczęcie zbierania danych telemetrycznych po stronie serwera. Jeśli aplikacja ma składniki po stronie klienta, wykonaj następne kroki, aby rozpocząć zbieranie danych telemetrycznych zestawu SDK modułu ładującego użycie przez konfigurację skryptu modułu ładującego.

W pliku _ViewImports.cshtmldodaj iniekcję:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

W _Layout.cshtmlpliku wstaw HtmlHelper na końcu <head> sekcji , ale przed innym skryptem. Jeśli chcesz zgłosić dowolną niestandardową telemetrię języka JavaScript ze strony, wprowadź ją po tym fragmencie kodu:
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

Alternatywą dla używania usługi FullScriptjest użycie programu , ScriptBody które można uruchomić w zestawie SDK usługi Application Insights dla ASP.NET Core w wersji 2.14. Użyj polecenia ScriptBody , jeśli musisz kontrolować tag, <script> aby ustawić zasady zabezpieczeń zawartości:

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

Nazwy .cshtml plików, do których odwołuje się wcześniej, pochodzą z domyślnego szablonu aplikacji MVC. Ostatecznie, jeśli chcesz prawidłowo włączyć monitorowanie po stronie klienta dla aplikacji, skrypt modułu ładującego zestawu SDK języka JavaScript musi zostać wyświetlony w <head> sekcji każdej strony aplikacji, którą chcesz monitorować. Dodaj skrypt modułu ładującego zestawu SDK języka JavaScript do _Layout.cshtml elementu w szablonie aplikacji, aby włączyć monitorowanie po stronie klienta.

Jeśli projekt nie zawiera _Layout.cshtmlelementu , nadal możesz dodać monitorowanie po stronie klienta , dodając skrypt modułu ładującego sdk języka JavaScript do równoważnego pliku, który kontroluje <head> wszystkie strony w aplikacji. Alternatywnie można dodać skrypt modułu ładującego zestawu SDK do wielu stron, ale nie zalecamy go.

Uwaga

Iniekcja języka JavaScript zapewnia domyślne środowisko konfiguracji. Jeśli potrzebujesz konfiguracji poza ustawieniem parametrów połączenia, musisz usunąć automatyczne wstrzyknięcie zgodnie z opisem i ręcznie dodać zestaw SDK języka JavaScript.

Konfigurowanie zestawu SDK usługi Application Insights

Aby zmienić konfigurację domyślną, można dostosować zestaw SDK usługi Application Insights dla ASP.NET Core. Użytkownicy zestawu SDK usługi Application Insights ASP.NET mogą znać zmianę konfiguracji przy użyciu polecenia ApplicationInsights.config lub przez zmodyfikowanie elementu TelemetryConfiguration.Active. W przypadku ASP.NET Core wprowadź prawie wszystkie zmiany konfiguracji w ConfigureServices() metodzie Startup.cs klasy, chyba że zostanie inaczej przekierowana. Poniższe sekcje zawierają więcej informacji.

Uwaga

W ASP.NET Core aplikacjach zmiana konfiguracji przez modyfikowanie TelemetryConfiguration.Active nie jest obsługiwana.

Korzystanie z usługi ApplicationInsightsServiceOptions

Możesz zmodyfikować kilka typowych ustawień, przekazując ApplicationInsightsServiceOptions element do AddApplicationInsightsTelemetryelementu , jak w tym przykładzie:

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

var builder = WebApplication.CreateBuilder(args);

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

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

// Disables QuickPulse (Live Metrics stream).
aiOptions.EnableQuickPulseMetricStream = false;

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

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

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

Ta tabela zawiera pełną listę ApplicationInsightsServiceOptions ustawień:

Ustawienie	Opis	Domyślny
EnablePerformanceCounterCollectionModule	Włącz/wyłącz `PerformanceCounterCollectionModule`.	Prawda
EnableRequestTrackingTelemetryModule	Włącz/wyłącz `RequestTrackingTelemetryModule`.	Prawda
EnableEventCounterCollectionModule	Włącz/wyłącz `EventCounterCollectionModule`.	Prawda
EnableDependencyTrackingTelemetryModule	Włącz/wyłącz `DependencyTrackingTelemetryModule`.	Prawda
EnableAppServicesHeartbeatTelemetryModule	Włącz/wyłącz `AppServicesHeartbeatTelemetryModule`.	Prawda
EnableAzureInstanceMetadataTelemetryModule	Włącz/wyłącz `AzureInstanceMetadataTelemetryModule`.	Prawda
EnableQuickPulseMetricStream	Włącz/wyłącz funkcję LiveMetrics.	Prawda
EnableAdaptiveSampling	Włącz/wyłącz próbkowanie adaptacyjne.	Prawda
EnableHeartbeat	Włącz/wyłącz funkcję pulsów. Okresowo (domyślna 15 minut) wysyła niestandardową metrykę o nazwie z `HeartbeatState` informacjami o środowisku uruchomieniowym, takimi jak wersja platformy .NET i informacje o środowisku platformy Azure, jeśli ma to zastosowanie.	Prawda
AddAutoCollectedMetricExtractor	Włącz/wyłącz element `AutoCollectedMetrics extractor`. Ten procesor telemetrii wysyła wstępnie zagregowane metryki dotyczące żądań/zależności przed rozpoczęciem próbkowania.	Prawda
RequestCollectionOptions.TrackExceptions	Włączanie/wyłączanie raportowania nieobsługiwanego śledzenia wyjątków przez moduł zbierania żądań.	Wartość false w `netstandard2.0` pliku (ponieważ wyjątki są śledzone za pomocą polecenia `ApplicationInsightsLoggerProvider`). Prawda w przeciwnym razie.
EnableDiagnosticsTelemetryModule	Włącz/wyłącz `DiagnosticsTelemetryModule`. Wyłączenie powoduje ignorowanie następujących ustawień: `EnableHeartbeat`, `EnableAzureInstanceMetadataTelemetryModule`i `EnableAppServicesHeartbeatTelemetryModule`.	Prawda

Aby uzyskać najbardziej aktualną listę, zobacz konfigurowalne ustawienia w programie ApplicationInsightsServiceOptions.

Zalecenie dotyczące konfiguracji dla zestawu Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 i nowszych

W zestawie Microsoft.ApplicationInsights.AspNetCore SDK w wersji 2.15.0 lub nowszej skonfiguruj każde ustawienie dostępne w programie , w ApplicationInsightsServiceOptionstym ConnectionString. Użyj wystąpienia aplikacji IConfiguration . Ustawienia muszą znajdować się w sekcji ApplicationInsights, jak pokazano w poniższym przykładzie. Poniższa sekcja z pliku appsettings.json konfiguruje parametry połączenia i wyłącza zbieranie próbek adaptacyjnych i liczników wydajności.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Jeśli builder.Services.AddApplicationInsightsTelemetry(aiOptions) dla ASP.NET Core 6.0 lub services.AddApplicationInsightsTelemetry(aiOptions) ASP.NET Core 3.1 i starszych jest używany, zastępuje ustawienia z Microsoft.Extensions.Configuration.IConfiguration.

Próbkowanie

Zestaw SDK usługi Application Insights dla ASP.NET Core obsługuje zarówno próbkowanie o stałej szybkości, jak i adaptacyjne. Domyślnie próbkowanie adaptacyjne jest włączone.

Aby uzyskać więcej informacji, zobacz Konfigurowanie próbkowania adaptacyjnego dla aplikacji ASP.NET Core.

Dodawanie telemetriiInitializers

Jeśli chcesz wzbogacić dane telemetryczne o więcej informacji, użyj inicjatorów telemetrii.

Dodaj dowolną nową TelemetryInitializer do kontenera DependencyInjection , jak pokazano w poniższym kodzie. Zestaw SDK automatycznie pobiera wszystkie TelemetryInitializer dodane do kontenera DependencyInjection .

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Uwaga

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); działa w przypadku prostych inicjatorów. W przypadku innych builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); użytkowników jest wymagany.

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

Uwaga

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); działa w przypadku prostych inicjatorów. W przypadku innych services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); użytkowników jest wymagany. Ta wersja platformy .NET nie jest już obsługiwana.

Usuwanie telemetriiInitializers

Domyślnie inicjatory telemetrii są obecne. Aby usunąć wszystkie lub określone inicjatory telemetrii, użyj następującego przykładowego kodu po wywołaniu metody AddApplicationInsightsTelemetry().

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

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

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

    // 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));
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

Dodawanie procesorów telemetrii

Niestandardowe procesory telemetryczne można dodać do TelemetryConfiguration programu przy użyciu metody AddApplicationInsightsTelemetryProcessor rozszerzenia w systemie IServiceCollection. Procesory telemetryczne są używane w zaawansowanych scenariuszach filtrowania. Skorzystaj z następującego przykładu:

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

Konfigurowanie lub usuwanie domyślnych modułów telemetrii

Usługa Application Insights automatycznie zbiera dane telemetryczne dotyczące określonych obciążeń bez konieczności ręcznego śledzenia przez użytkownika.

Domyślnie są włączone następujące moduły automatycznej kolekcji. Te moduły są odpowiedzialne za automatyczne zbieranie danych telemetrycznych. Można je wyłączyć lub skonfigurować w celu zmiany ich domyślnego zachowania.

RequestTrackingTelemetryModule: zbiera wartość RequestTelemetry z przychodzących żądań internetowych.
DependencyTrackingTelemetryModule: zbiera wartość DependencyTelemetry z wychodzących wywołań HTTP i wywołań SQL.
PerformanceCollectorModule: zbiera liczniki wydajności systemu Windows.
QuickPulseTelemetryModule: zbiera dane telemetryczne, które mają być wyświetlane w portalu metryk na żywo.
AppServicesHeartbeatTelemetryModule: zbiera pulsy (wysyłane jako metryki niestandardowe) dotyczące środowiska App Service, w którym jest hostowana aplikacja.
AzureInstanceMetadataTelemetryModule: zbiera pulsy (wysyłane jako metryki niestandardowe) dotyczące środowiska maszyny wirtualnej platformy Azure, w którym jest hostowana aplikacja.
EventCounterCollectionModule: zbiera zdarzenia. Ten moduł jest nową funkcją i jest dostępny w zestawie SDK w wersji 2.8.0 lub nowszej.

Aby skonfigurować dowolną domyślną metodę TelemetryModule, użyj metody ConfigureTelemetryModule<T> rozszerzenia w systemie IServiceCollection, jak pokazano w poniższym przykładzie:

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

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

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

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

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

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    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 = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

W wersjach 2.12.2 lub nowszych ApplicationInsightsServiceOptions dostępna jest łatwa opcja wyłączania dowolnych modułów domyślnych.

Konfigurowanie kanału telemetrii

Domyślnym kanałem telemetrii jest ServerTelemetryChannel. W poniższym przykładzie pokazano, jak go zastąpić.

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

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.AddApplicationInsightsTelemetry();
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

Uwaga

Jeśli chcesz opróżnić bufor, zobacz Opróżnianie danych. Na przykład może być konieczne opróżnienie buforu, jeśli używasz zestawu SDK w aplikacji, która zostanie zamknięta.

Dynamiczne wyłączanie telemetrii

Jeśli chcesz wyłączyć telemetrię warunkowo i dynamicznie, możesz rozpoznać TelemetryConfiguration wystąpienie za pomocą kontenera iniekcji zależności ASP.NET Core w dowolnym miejscu w kodzie i ustawić flagę DisableTelemetry na nim.

ASP.NET Core 6 i nowszych
ASP.NET Core 5 i starszych

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.AddApplicationInsightsTelemetry();
}

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

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

Poprzedni przykładowy kod uniemożliwia wysyłanie danych telemetrycznych do usługi Application Insights. Nie uniemożliwia ona zbierania danych telemetrycznych przez żadne moduły kolekcji automatycznej. Jeśli chcesz usunąć konkretny moduł autocollection, zobacz Usuwanie modułu telemetrii.

Często zadawane pytania

Ta sekcja zawiera odpowiedzi na często zadawane pytania.

Czy usługa Application Insights obsługuje ASP.NET Core 3.1?

ASP.NET Core 3.1 nie jest już obsługiwana przez firmę Microsoft.

Zestaw SDK usługi Application Insights dla ASP.NET Core w wersji 2.8.0 i Visual Studio 2019 lub nowszej może być używany z aplikacjami ASP.NET Core 3.1.

Jak mogę śledzić dane telemetryczne, które nie są zbierane automatycznie?

Pobierz wystąpienie TelemetryClient przy użyciu iniekcji konstruktora i wywołaj wymaganą TrackXXX() metodę. Nie zalecamy tworzenia nowych TelemetryClient lub TelemetryConfiguration wystąpień w aplikacji ASP.NET Core. Pojedyncze wystąpienie obiektu TelemetryClient jest już zarejestrowane w kontenerze DependencyInjection , które współudzieli TelemetryConfiguration pozostałe dane telemetryczne. Utwórz nowe TelemetryClient wystąpienie tylko wtedy, gdy wymaga konfiguracji, która jest oddzielona od pozostałej części telemetrii.

W poniższym przykładzie pokazano, jak śledzić więcej danych telemetrycznych z kontrolera.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

Aby uzyskać więcej informacji na temat niestandardowego raportowania danych w usłudze Application Insights, zobacz Dokumentacja interfejsu API metryk niestandardowych usługi Application Insights. Podobne podejście może służyć do wysyłania metryk niestandardowych do usługi Application Insights przy użyciu interfejsu API GetMetric.

Jak mogę dostosować kolekcję dzienników ILogger?

Ustawieniem domyślnym usługi Application Insights jest przechwytywanie tylko ostrzeżeń i bardziej poważnych dzienników.

Przechwyć informacje i bardziej poważne dzienniki, zmieniając konfigurację rejestrowania dostawcy usługi Application Insights w następujący sposób.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

Należy pamiętać, że poniższy przykład nie powoduje przechwycenia Information dzienników przez dostawcę usługi Application Insights. Nie przechwytuje go, ponieważ zestaw SDK dodaje domyślny filtr rejestrowania, który nakazuje przechwytywanie ApplicationInsights tylko Warning dzienników i bardziej poważnych dzienników. Usługa Application Insights wymaga jawnego zastąpienia.

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

Aby uzyskać więcej informacji, zobacz ILogger configuration (Konfiguracja ILogger).

Niektóre szablony programu Visual Studio używały metody rozszerzenia UseApplicationInsights() w programie IWebHostBuilder w celu włączenia usługi Application Insights. Czy to użycie jest nadal prawidłowe?

Metoda UseApplicationInsights() rozszerzenia jest nadal obsługiwana, ale jest oznaczona jako przestarzała w zestawie SDK usługi Application Insights w wersji 2.8.0 lub nowszej. Zostanie ona usunięta w następnej głównej wersji zestawu SDK. Aby włączyć telemetrię usługi Application Insights, użyj AddApplicationInsightsTelemetry() polecenia , ponieważ zapewnia przeciążenia w celu kontrolowania niektórych konfiguracji. Ponadto w aplikacjach services.AddApplicationInsightsTelemetry() ASP.NET Core 3.X jest jedynym sposobem włączenia usługi Application Insights.

Wdrażam aplikację ASP.NET Core w Web Apps. Czy nadal należy włączyć rozszerzenie usługi Application Insights z poziomu Web Apps?

Jeśli zestaw SDK jest zainstalowany w czasie kompilacji, jak pokazano w tym artykule, nie musisz włączać rozszerzenia usługi Application Insights z portalu App Service. Jeśli rozszerzenie jest zainstalowane, zostanie ono wycofane po wykryciu, że zestaw SDK został już dodany. Jeśli włączysz usługę Application Insights z rozszerzenia, nie musisz instalować i aktualizować zestawu SDK. Jeśli jednak włączysz usługę Application Insights, postępując zgodnie z instrukcjami w tym artykule, masz większą elastyczność, ponieważ:

Dane telemetryczne usługi Application Insights nadal działają w:
- Wszystkie systemy operacyjne, w tym Windows, Linux i Mac.
- Wszystkie tryby publikowania, w tym zależne od siebie lub struktury.
- Wszystkie platformy docelowe, w tym pełna .NET Framework.
- Wszystkie opcje hostingu, w tym Web Apps, maszyny wirtualne, linux, kontenery, AKS i hosting inny niż platforma Azure.
- Wszystkie wersje platformy .NET Core, w tym wersje zapoznawcza.
Dane telemetryczne są wyświetlane lokalnie podczas debugowania z poziomu programu Visual Studio.
Więcej niestandardowych danych telemetrycznych można śledzić przy użyciu interfejsu TrackXXX() API.
Masz pełną kontrolę nad konfiguracją.

Czy mogę włączyć monitorowanie usługi Application Insights przy użyciu narzędzi, takich jak agent usługi Azure Monitor Application Insights (dawniej Monitor stanu w wersji 2)?

Tak. W programie Application Insights Agent 2.0.0-beta1 lub nowszym obsługiwane są aplikacje ASP.NET Core hostowane w usługach IIS.

Czy wszystkie funkcje są obsługiwane, jeśli uruchamiam aplikację w systemie Linux?

Tak. Obsługa funkcji zestawu SDK jest taka sama na wszystkich platformach z następującymi wyjątkami:

Zestaw SDK zbiera liczniki zdarzeń w systemie Linux, ponieważ liczniki wydajności są obsługiwane tylko w systemie Windows. Większość metryk jest taka sama.
Mimo ServerTelemetryChannel że jest domyślnie włączona, jeśli aplikacja jest uruchomiona w systemie Linux lub macOS, kanał nie tworzy automatycznie lokalnego folderu magazynu, aby tymczasowo przechowywać dane telemetryczne, jeśli występują problemy z siecią. Z powodu tego ograniczenia dane telemetryczne zostaną utracone, gdy występują tymczasowe problemy z siecią lub serwerem. Aby obejść ten problem, skonfiguruj folder lokalny dla kanału.

ASP.NET Core 6.0
ASP.NET Core 3.1

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

var builder = WebApplication.CreateBuilder(args);

// The following will configure the channel to use the given folder to temporarily
// store telemetry items during network or Application Insights server issues.
// User should ensure that the given folder already exists
// and that the application has read/write permissions.
builder.Services.AddSingleton(typeof(ITelemetryChannel),
                        new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

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

public void ConfigureServices(IServiceCollection services)
{
    // The following will configure the channel to use the given folder to temporarily
    // store telemetry items during network or Application Insights server issues.
    // User should ensure that the given folder already exists
    // and that the application has read/write permissions.
    services.AddSingleton(typeof(ITelemetryChannel),
                            new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
    services.AddApplicationInsightsTelemetry();
}

Uwaga

Ta wersja platformy .NET nie jest już obsługiwana.

To ograniczenie nie ma zastosowania w wersji 2.15.0 lub nowszej.

Czy ten zestaw SDK jest obsługiwany dla nowych aplikacji szablonów usługi procesu roboczego platformy .NET Core 3.X?

Ten zestaw SDK wymaga HttpContext. Nie działa w żadnych aplikacjach innych niż HTTP, w tym w aplikacjach usługi roboczej .NET Core 3.X. Aby włączyć usługę Application Insights w takich aplikacjach przy użyciu nowo wydanego zestawu MICROSOFT.ApplicationInsights.WorkerService SDK, zobacz Application Insights for Worker Service applications (aplikacje inne niż HTTP).

Rozwiązywanie problemów

Testowanie łączności między hostem aplikacji a usługą pozyskiwania

Zestawy SDK usługi Application Insights i agenci wysyłają dane telemetryczne, aby uzyskać pozyskane jako wywołania REST do naszych punktów końcowych pozyskiwania. Możesz przetestować łączność z serwera internetowego lub maszyny hosta aplikacji do punktów końcowych usługi pozyskiwania przy użyciu nieprzetworzonych klientów REST z poziomu programu PowerShell lub poleceń curl. Zobacz Rozwiązywanie problemów z brakującą telemetrią aplikacji w usłudze Azure Monitor Application Insights.

Zestaw SDK typu open source

Odczytywanie i współtworzenie kodu.

Najnowsze aktualizacje i poprawki błędów można znaleźć w informacjach o wersji.

Uwagi do wersji

W przypadku wersji 2.12 i nowszej: zestawy SDK platformy .NET (w tym ASP.NET, ASP.NET Core i adaptery rejestrowania)

Nasza usługa Aktualizacje również podsumować główne ulepszenia usługi Application Insights.

Następne kroki

Zapoznaj się z przepływami użytkowników , aby dowiedzieć się, jak użytkownicy przechodzą przez aplikację.
Skonfiguruj kolekcję migawek , aby zobaczyć stan kodu źródłowego i zmiennych w chwili wystąpienia wyjątku.
Użyj interfejsu API , aby wysłać własne zdarzenia i metryki, aby uzyskać szczegółowy widok wydajności i użycia aplikacji.
Użyj testów dostępności , aby stale sprawdzać aplikację z całego świata.
Dowiedz się więcej o iniekcji zależności w ASP.NET Core.

Usługa Application Insights dla aplikacji ASP.NET Core

Obsługiwane scenariusze

Wymagania wstępne

Włączanie telemetrii po stronie serwera usługi Application Insights (Visual Studio)

Włączanie telemetrii po stronie serwera usługi Application Insights (bez programu Visual Studio)

Wpisy tajne użytkownika i inni dostawcy konfiguracji

Uruchamianie aplikacji

Metryki na żywo

Dzienniki ILogger

Zależności

Liczniki wydajności

EventCounter

Wzbogacanie danych za pośrednictwem protokołu HTTP

Włączanie telemetrii po stronie klienta dla aplikacji internetowych

Konfigurowanie zestawu SDK usługi Application Insights

Korzystanie z usługi ApplicationInsightsServiceOptions

Zalecenie dotyczące konfiguracji dla zestawu Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 i nowszych

Próbkowanie

Dodawanie telemetriiInitializers

Usuwanie telemetriiInitializers

Dodawanie procesorów telemetrii

Konfigurowanie lub usuwanie domyślnych modułów telemetrii

Konfigurowanie kanału telemetrii

Dynamiczne wyłączanie telemetrii

Często zadawane pytania

Czy usługa Application Insights obsługuje ASP.NET Core 3.1?

Jak mogę śledzić dane telemetryczne, które nie są zbierane automatycznie?

Jak mogę dostosować kolekcję dzienników ILogger?

Niektóre szablony programu Visual Studio używały metody rozszerzenia UseApplicationInsights() w programie IWebHostBuilder w celu włączenia usługi Application Insights. Czy to użycie jest nadal prawidłowe?

Wdrażam aplikację ASP.NET Core w Web Apps. Czy nadal należy włączyć rozszerzenie usługi Application Insights z poziomu Web Apps?

Czy mogę włączyć monitorowanie usługi Application Insights przy użyciu narzędzi, takich jak agent usługi Azure Monitor Application Insights (dawniej Monitor stanu w wersji 2)?

Czy wszystkie funkcje są obsługiwane, jeśli uruchamiam aplikację w systemie Linux?

Czy ten zestaw SDK jest obsługiwany dla nowych aplikacji szablonów usługi procesu roboczego platformy .NET Core 3.X?

Rozwiązywanie problemów

Testowanie łączności między hostem aplikacji a usługą pozyskiwania

Zestaw SDK typu open source

Uwagi do wersji

Następne kroki

Dodatkowe zasoby

Dodatkowe zasoby