Szczegółowe informacje aplikacji dla aplikacji ASP.NET Core

Artykuł
01/31/2024

W tym artykule opisano sposób włączania i konfigurowania Szczegółowe informacje aplikacji dla aplikacji ASP.NET Core.

Uwaga

Poniższa dokumentacja opiera się na klasycznym interfejsie API usługi Application Szczegółowe informacje. Długoterminowy plan Szczegółowe informacje aplikacji polega na zbieraniu danych przy użyciu biblioteki OpenTelemetry. Aby uzyskać więcej informacji, zobacz Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications (Włączanie usługi Azure Monitor OpenTelemetry dla platformy .NET, Node.js, Python i Java applications).

Aplikacja Szczegółowe informacje 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 Procesu roboczego, skorzystaj z instrukcji w temacie Application Szczegółowe informacje for Worker Service applications (Aplikacja Szczegółowe informacje dla aplikacji usługi procesu roboczego).

Dostępna jest oferta platformy .NET oparta na technologii OpenTelemetry. Aby uzyskać więcej informacji, zobacz OpenTelemetry overview (Omówienie funkcji 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 udostępnimy już aktualizacji ani obsługi funkcji. Przejście do parametry połączenia w celu skorzystania z nowych funkcji.

Uwaga

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

Obsługiwane scenariusze

Zestaw SDK Szczegółowe informacje aplikacji dla platformy 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 Szczegółowe informacje aplikacji 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: struktura zależna lub samodzielna
Serwer sieci Web: Internet Information Server (IIS) lub Kestrel
Platforma hostingu: funkcja Web Apps usługi aplikacja systemu Azure 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

Należy wykonać:

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 application Szczegółowe informacje.
Prawidłowa Szczegółowe informacje parametry połączenia aplikacji. Ten ciąg jest wymagany do wysyłania wszelkich danych telemetrycznych do aplikacji Szczegółowe informacje. Jeśli musisz utworzyć nowy zasób usługi Application Szczegółowe informacje, aby uzyskać parametry połączenia, zobacz Tworzenie zasobu Szczegółowe informacje aplikacji.

Włączanie telemetrii po stronie serwera (Visual Studio) Szczegółowe informacje aplikacji

W przypadku 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 Project Add Application Szczegółowe informacje Telemetry (Dodawanie>aplikacji Szczegółowe informacje telemetrii).
Wybierz pozycję aplikacja systemu Azure Szczegółowe informacje> Dalej.
Wybierz swoją subskrypcję i wystąpienie Szczegółowe informacje aplikacji. Możesz też utworzyć nowe wystąpienie za pomocą polecenia Utwórz nowe. Wybierz Dalej.
Dodaj lub potwierdź Szczegółowe informacje parametry połączenia aplikacji. Powinna zostać wstępnie wypełniona na podstawie wybranego elementu w poprzednim kroku. Wybierz Zakończ.
Po dodaniu Szczegółowe informacje aplikacji do projektu sprawdź, czy używasz najnowszej stabilnej wersji zestawu SDK. Przejdź do pozycji Project Manage NuGet Packages Microsoft.Application Szczegółowe informacje (Zarządzanie>pakietami>NuGet Microsoft.Application Szczegółowe informacje. AspNetCore. Jeśli chcesz, wybierz pozycję Aktualizuj.

Włączanie telemetrii po stronie serwera Szczegółowe informacje aplikacji (bez programu Visual Studio)

Zainstaluj pakiet NuGet zestawu SDK Szczegółowe informacje aplikacji dla platformy 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 mają zostać dodane do pliku projektu .csproj :
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

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

ASP.NET Core 6 lub nowszym
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 można podać parametry połączenia jako część argumentu ApplicationInsightsServiceOptions , AddApplicationInsightsTelemetryzalecamy określenie parametry 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 środowiskowej APPLICATIONINSIGHTS_CONNECTION_STRING 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>
- Zazwyczaj jest używany w usłudze APPLICATIONINSIGHTS_CONNECTION_STRING Web Apps. Można go również używać we wszystkich miejscach, w których ten zestaw SDK jest obsługiwany.
Uwaga

Parametry połączenia określony w kodzie wygrywa zmienną środowiskową 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 wpisach tajnych użytkownika platformy ASP.NET Core lub pobrać go 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 z wielu dostawców, services.AddApplicationInsightsTelemetry określa priorytety konfiguracji z appsettings.json, niezależnie od kolejności, w jakiej dostawcy są dodawani. Użyj metody , aby odczytać konfigurację services.AddApplicationInsightsTelemetry(IConfiguration) 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 Szczegółowe informacje aplikacji. Zestaw SDK usługi Application Szczegółowe informacje 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 aplikacji Szczegółowe informacje jest skonfigurowane poprawnie. 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 protokołu 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 Szczegółowe informacje wyjaśnia zależności, które są zbierane automatycznie, 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 usłudze 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 elementy docelowe netstandard2.0 lub nowsze.
W przypadku aplikacji przeznaczonych dla platformy .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 usługi EventCounters.

EventCounter

Domyślnie funkcja EventCounterCollectionModule jest włączona. Aby dowiedzieć się, jak skonfigurować listę liczników do zebrania, zobacz Wprowadzenie do usługi 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 użycia przy użyciu iniekcji skryptu modułu ładującego zestawu SDK języka JavaScript (Web) według konfiguracji.

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, wstrzykuj ją po tym fragmencie kodu:
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

Alternatywą dla korzystania z programu FullScriptScriptBody jest uruchamianie zestawu SDK usługi Application Szczegółowe informacje dla platformy ASP.NET Core w wersji 2.14. Użyj ScriptBody polecenia , 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 JavaScript (Web) sdk języka JavaScript (Web) musi zostać wyświetlony w <head> sekcji każdej strony aplikacji, którą chcesz monitorować. Dodaj skrypt modułu ładującego javaScript javaScript (Web) sdk do _Layout.cshtml elementu w szablonie aplikacji, aby umożliwić 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 JavaScript (Web) JavaScript (Web) sdk do równoważnego pliku, który kontroluje <head> wszystkie strony w aplikacji. Alternatywnie można dodać skrypt modułu ładującego zestawu JAVAScript (Web) SDK do wielu stron, ale nie zalecamy go.

Uwaga

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

Konfigurowanie zestawu SDK usługi Application Szczegółowe informacje

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

Uwaga

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

Korzystanie z aplikacji Szczegółowe informacje ServiceOptions

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

ASP.NET Core 6 lub nowszym
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	Wartość domyślna
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
WłączAzureInstanceMetadataTelemetryModule	Włącz/wyłącz `AzureInstanceMetadataTelemetryModule`.	Prawda
EnableQuickPulseMetricStream	Włącz/wyłącz funkcję LiveMetrics.	Prawda
EnableAdaptiveSampling	Włączanie/wyłączanie próbkowania adaptacyjnego.	Prawda
WłączHeartbeat	Włącz/wyłącz funkcję pulsów. Okresowo (15-minutowa wartość domyślna) wysyła niestandardową metrykę o nazwie o nazwie `HeartbeatState` z 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łącz/wyłącz raportowanie nieobsługiwanego śledzenia wyjątków przez moduł zbierania żądań.	Fałsz w `netstandard2.0` (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 aplikacji Microsoft.Application Szczegółowe informacje. Zestaw ASPNetCore SDK 2.15.0 lub nowszy

W aplikacji Microsoft.Application Szczegółowe informacje. Zestaw ASPNetCore SDK w wersji 2.15.0 lub nowszej konfiguruje 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 appsettings.json konfiguruje parametry połączenia i wyłącza zbieranie próbkowania adaptacyjnego i licznika wydajności.

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

Jeśli builder.Services.AddApplicationInsightsTelemetry(aiOptions) w przypadku 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 Szczegółowe informacje aplikacji dla platformy ASP.NET Core obsługuje próbkowanie o stałym tempie i adaptacyjnym. Domyślnie jest włączone próbkowanie adaptacyjne.

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 lub nowszym
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 jest builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); 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 jest services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); wymagany. Ta wersja platformy .NET nie jest już obsługiwana.

Usuwanie telemetriiInitializers

Domyślnie są obecne inicjatory telemetrii. 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 lub nowszym
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 lub nowszym
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 trybów telemetrii

Aplikacja Szczegółowe informacje 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 dane 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 (które są wysyłane jako metryki niestandardowe), o środowisku usługi App Service, w którym jest hostowana aplikacja.
AzureInstanceMetadataTelemetryModule: zbiera pulsy (które są 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ą TelemetryModulemetodę , użyj metody ConfigureTelemetryModule<T> rozszerzenia w metodzie IServiceCollection, jak pokazano w poniższym przykładzie:

ASP.NET Core 6 lub nowszym
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 i nowszych ApplicationInsightsServiceOptions zawiera łatwą opcję wyłączenia dowolnego z domyślnych modułów.

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 lub nowszym
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ć na nim flagę DisableTelemetry .

ASP.NET Core 6 lub nowszym
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 Szczegółowe informacje aplikacji. Nie zapobiega to zbieraniu danych telemetrycznych przez żadne moduły automatycznej kolekcji. Jeśli chcesz usunąć konkretny moduł autocollection, zobacz Usuwanie modułu telemetrii.

Często zadawane pytania

Ta sekcja zawiera odpowiedzi na typowe pytania.

Czy usługa Application Szczegółowe informacje obsługuje ASP.NET Core 3.1?

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

Zestaw SDK Szczegółowe informacje aplikacji 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 TelemetryClient klasy jest już zarejestrowane w kontenerze DependencyInjection , które współudzieli TelemetryConfiguration resztę danych telemetrycznych. Utwórz nowe TelemetryClient wystąpienie tylko wtedy, gdy potrzebuje 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 raportowania danych niestandardowych w usłudze Application Szczegółowe informacje, zobacz Application Szczegółowe informacje custom metrics API reference (Dokumentacja interfejsu API metryk niestandardowych w usłudze Application Szczegółowe informacje). Podobne podejście może służyć do wysyłania metryk niestandardowych do usługi Application Szczegółowe informacje przy użyciu interfejsu API GetMetric.

Jak mogę przechwytywać treść żądania i odpowiedzi w telemetrii?

ASP.NET Core ma wbudowaną obsługę rejestrowania informacji żądania/odpowiedzi HTTP (w tym treści) za pośrednictwem polecenia ILogger. Zaleca się korzystanie z tego celu. Może to potencjalnie uwidocznić dane osobowe w telemetrii i spowodować znaczne zwiększenie kosztów (kosztów wydajności i rozliczeń aplikacji Szczegółowe informacje aplikacji), dlatego należy dokładnie ocenić ryzyko przed użyciem tego.

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

Ustawieniem domyślnym dla Szczegółowe informacje aplikacji jest przechwytywanie tylko ostrzeżeń i poważniejszych dzienników.

Przechwyć informacje i mniej poważne dzienniki, zmieniając konfigurację rejestrowania dla dostawcy aplikacji Szczegółowe informacje 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ę application Szczegółowe informacje. Nie przechwytuje go, ponieważ zestaw SDK dodaje domyślny filtr rejestrowania, który nakazuje ApplicationInsights przechwycenie tylko Warning dzienników i poważniejszych dzienników. Szczegółowe informacje aplikacji 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 UseApplication Szczegółowe informacje() w programie IWebHostBuilder w celu włączenia Szczegółowe informacje aplikacji. Czy to użycie jest nadal prawidłowe?

Metoda UseApplicationInsights() rozszerzenia jest nadal obsługiwana, ale jest oznaczona jako przestarzała w aplikacji Szczegółowe informacje SDK w wersji 2.8.0 lub nowszej. Zostanie on usunięty w następnej wersji głównej zestawu SDK. Aby włączyć telemetrię Szczegółowe informacje aplikacji, użyj funkcji AddApplicationInsightsTelemetry() , ponieważ zapewnia przeciążenia do kontrolowania niektórych konfiguracji. Ponadto w aplikacjach services.AddApplicationInsightsTelemetry() ASP.NET Core 3.X jest jedynym sposobem włączenia Szczegółowe informacje aplikacji.

Wdrażam moją aplikację ASP.NET Core w usłudze Web Apps. Czy nadal należy włączyć rozszerzenie Application Szczegółowe informacje z poziomu usługi Web Apps?

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

Dane telemetryczne Szczegółowe informacje aplikacji 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 platforma .NET Framework.
- Wszystkie opcje hostingu, w tym aplikacje internetowe, maszyny wirtualne, linux, kontenery, usługa AKS i hosting spoza platformy Azure.
- Wszystkie wersje platformy .NET Core, w tym wersje zapoznawcza.
Dane telemetryczne są widoczne 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 Szczegółowe informacje aplikacji przy użyciu narzędzi, takich jak agent Szczegółowe informacje aplikacji usługi Azure Monitor (wcześniej Monitor stanu w wersji 2)?

Tak. W programie Application Szczegółowe informacje 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 dla 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.

Czy ten zestaw SDK jest obsługiwany w przypadku usług roboczych?

L.p. W przypadku usług roboczych użyj Szczegółowe informacje aplikacji usługi procesu roboczego (aplikacji innych niż HTTP).

Jak mogę odinstalować zestaw SDK?

Aby usunąć Szczegółowe informacje aplikacji, należy usunąć pakiety NuGet i odwołania z interfejsu API w aplikacji. Pakiety NuGet można odinstalować przy użyciu Menedżer pakietów NuGet w programie Visual Studio.

Uwaga

Te instrukcje dotyczą odinstalowywania zestawu ASP.NET Core SDK. Jeśli musisz odinstalować zestaw SDK ASP.NET, zobacz Jak mogę odinstalować zestaw SDK ASP.NET?.

Odinstaluj aplikację Microsoft.Application Szczegółowe informacje. Pakiet AspNetCore przy użyciu Menedżer pakietów NuGet.
Aby w pełni usunąć Szczegółowe informacje aplikacji, sprawdź i ręcznie usuń dodany kod lub pliki wraz z dowolnymi wywołaniami interfejsu API dodanymi w projekcie. Aby uzyskać więcej informacji, zobacz Co zostało utworzone podczas dodawania zestawu SDK usługi Application Szczegółowe informacje?.

Co zostało utworzone podczas dodawania zestawu SDK usługi Application Szczegółowe informacje?

Po dodaniu Szczegółowe informacje aplikacji do projektu program tworzy pliki i dodaje kod do niektórych plików. Wyłącznie odinstalowywanie pakietów NuGet nie zawsze odrzuca pliki i kod. Aby w pełni usunąć Szczegółowe informacje aplikacji, należy sprawdzić i ręcznie usunąć dodany kod lub pliki wraz z dowolnymi wywołaniami interfejsu API dodanymi w projekcie.

Podczas dodawania telemetrii Szczegółowe informacje aplikacji do projektu szablonu programu Visual Studio ASP.NET Core dodaje on następujący kod:

[Nazwa projektu].csproj

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
  </ItemGroup>

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

Appsettings.json:

"ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

Połączenie edService.json

{
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

Startup.cs

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

Rozwiązywanie problemów

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

Zestawy SDK Szczegółowe informacje aplikacji 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 pierwotnych 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 Szczegółowe informacje.

Zestaw SDK typu open source

Odczytywanie i współtworzenie kodu.

Aby uzyskać najnowsze aktualizacje i poprawki błędów, zobacz informacje o wersji.

Informacje o wersji

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

Nasza usługa Aktualizacje również podsumować główne ulepszenia Szczegółowe informacje aplikacji.

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 momencie zgłoszenia wyjątku.
Użyj interfejsu API , aby wysył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 programie ASP.NET Core.

Szczegółowe informacje aplikacji dla aplikacji ASP.NET Core

Obsługiwane scenariusze

Wymagania wstępne

Włączanie telemetrii po stronie serwera (Visual Studio) Szczegółowe informacje aplikacji

Włączanie telemetrii po stronie serwera Szczegółowe informacje aplikacji (bez programu Visual Studio)

Wpisy tajne użytkownika i inni dostawcy konfiguracji

Uruchamianie aplikacji

Metryki na żywo

Dzienniki protokołu 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 Szczegółowe informacje

Korzystanie z aplikacji Szczegółowe informacje ServiceOptions

Zalecenie dotyczące konfiguracji aplikacji Microsoft.Application Szczegółowe informacje. Zestaw ASPNetCore SDK 2.15.0 lub nowszy

Próbkowanie

Dodawanie telemetriiInitializers

Usuwanie telemetriiInitializers

Dodawanie procesorów telemetrii

Konfigurowanie lub usuwanie domyślnych trybów telemetrii

Konfigurowanie kanału telemetrii

Dynamiczne wyłączanie telemetrii

Często zadawane pytania

Czy usługa Application Szczegółowe informacje obsługuje ASP.NET Core 3.1?

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

Jak mogę przechwytywać treść żądania i odpowiedzi w telemetrii?

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

Niektóre szablony programu Visual Studio używały metody rozszerzenia UseApplication Szczegółowe informacje() w programie IWebHostBuilder w celu włączenia Szczegółowe informacje aplikacji. Czy to użycie jest nadal prawidłowe?

Wdrażam moją aplikację ASP.NET Core w usłudze Web Apps. Czy nadal należy włączyć rozszerzenie Application Szczegółowe informacje z poziomu usługi Web Apps?

Czy mogę włączyć monitorowanie Szczegółowe informacje aplikacji przy użyciu narzędzi, takich jak agent Szczegółowe informacje aplikacji usługi Azure Monitor (wcześniej 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 w przypadku usług roboczych?

Jak mogę odinstalować zestaw SDK?

Co zostało utworzone podczas dodawania zestawu SDK usługi Application Szczegółowe informacje?

Rozwiązywanie problemów

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

Zestaw SDK typu open source

Informacje o wersji

Następne kroki

Dodatkowe zasoby