Usługa Application Insights dla aplikacji ASP.NET Core

Artykuł
12/16/2024

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

Uwaga

Zalecamy dystrybucję OpenTelemetry usługi Azure Monitor dla nowych aplikacji lub klientów, aby umożliwić usłudze Azure Monitor Application Insights. Dystrybucja OpenTelemetry usługi Azure Monitor zapewnia podobną funkcjonalność i środowisko jako zestaw SDK usługi Application Insights. Migracja z zestawu SDK usługi Application Insights jest możliwa przy użyciu przewodników migracji dla platformy .NET, Node.js i języka Python, ale nadal pracujemy nad dodaniem kilku dodatkowych funkcji w celu zapewnienia zgodności z poprzednimi wersjami.

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 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 usługi Application Insights 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 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: 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

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łowa parametry połączenia usługi Application Insights. Ten ciąg jest wymagany do wysyłania wszelkich 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)

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 Insights Telemetry (Dodawanie>telemetrii 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 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 Zakończ.
Po dodaniu usługi Application Insights do projektu sprawdź, czy używasz najnowszej stabilnej wersji zestawu SDK. Przejdź do pozycji Project Manage NuGet Packages Microsoft.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 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 csproj projektu:
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

Dodaj AddApplicationInsightsTelemetry() do klasy program.cs .

Dodaj builder.Services.AddApplicationInsightsTelemetry(); po metodzie WebApplication.CreateBuilder() , 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 parametry połączenia, które można wykonać na trzy sposoby:
- (Zalecane) Ustaw parametry połączenia w konfiguracji.
  
  Ustaw parametry połączenia w appsettings.json i upewnij się, że plik konfiguracji został skopiowany do folderu głównego aplikacji podczas publikowania.
```
{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "ApplicationInsights": {
        "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
    }
}
```
- Ustaw 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.
- Ustaw parametry połączenia w kodzie.
  
  Podaj parametry połączenia jako część argumentu ApplicationInsightsServiceOptions AddApplicationInsightsTelemetry w klasie program.cs.

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 od wielu dostawców, określa priorytety services.AddApplicationInsightsTelemetry konfiguracji z appsettings.json, niezależnie od kolejności dodawania dostawców. Użyj metody , aby odczytać konfigurację services.AddApplicationInsightsTelemetry(IConfiguration) bez IConfiguration tego preferencyjnego traktowania 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 aplikacji za pomocą usługi Application Insights jest poprawnie skonfigurowane. Dane telemetryczne mogą pojawić się w witrynie Azure Portal, ale okienko metryk na żywo pokazuje 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.

Włączanie metryk na żywo przy użyciu kodu dla dowolnej aplikacji .NET

Uwaga

Metryki na żywo są domyślnie włączone podczas dołączania, korzystając z zalecanych instrukcji dotyczących aplikacji platformy .NET.

Aby ręcznie skonfigurować metryki na żywo:

Zainstaluj pakiet NuGet Microsoft.ApplicationInsights.PerfCounterCollector.
Poniższy przykładowy kod aplikacji konsoli przedstawia konfigurowanie metryk na żywo:

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

Powyższy przykład dotyczy aplikacji konsolowej, ale ten sam kod może być używany w dowolnych aplikacjach platformy .NET. Jeśli jakiekolwiek inne moduły telemetryczne są włączone do automatycznego generowania danych telemetrycznych, ważne jest, aby upewnić się, że ta sama konfiguracja używana do inicjowania tych modułów jest używana dla modułu metryk na żywo.

Dzienniki protokołu ILogger

Domyślna konfiguracja zbiera ILogger Warning 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ą 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.cshtml dodaj iniekcję:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

W pliku _Layout.cshtml 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 Insights 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 plików cshtml , 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 (Web) musi zostać wyświetlony w <head> sekcji każdej strony aplikacji, którą chcesz monitorować. Dodaj skrypt modułu ładującego zestawu JAVAScript (Web) SDK do pliku _Layout.cshtml w szablonie aplikacji, aby umożliwić monitorowanie po stronie klienta.

Jeśli projekt nie zawiera pliku _Layout.cshtml, nadal możesz dodać monitorowanie po stronie klienta, dodając skrypt modułu ładującego zestawu 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 Insights

Aby zmienić konfigurację domyślną, można dostosować zestaw SDK usługi Application Insights dla platformy ASP.NET Core. Użytkownicy zestawu SDK usługi Application Insights ASP.NET mogą znać zmianę konfiguracji przy użyciu pliku ApplicationInsights.config lub przez zmodyfikowanie elementu TelemetryConfiguration.Active. W przypadku ASP.NET Core wprowadź prawie wszystkie zmiany konfiguracji w ConfigureServices() metodzie klasy Startup.cs , chyba że zostanie przekierowana 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 usługi ApplicationInsightsServiceOptions

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

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

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 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 appsettings.json konfiguruje parametry połączenia i wyłącza zbieranie próbkowania adaptacyjnego i licznika wydajności.

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "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 usługi Application Insights dla platformy ASP.NET Core obsługuje próbkowanie o stałej szybkości i adaptacyjne. 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 .

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.

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

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

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:

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

Konfigurowanie lub usuwanie domyślnych trybó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 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 okienku 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:

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

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ć.

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

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 .

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

Powyższy przykładowy kod uniemożliwia wysyłanie danych telemetrycznych do usługi Application Insights. 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 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 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 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ę 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. Może to potencjalnie spowodować znaczne zwiększenie kosztów (kosztów wydajności i rozliczeń usługi Application Insights), co może spowodować znaczne zwiększenie danych osobowych (piI) i dokładne oszacowanie ryzyka przed użyciem tego problemu.

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

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

Przechwyć informacje i mniej 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 ApplicationInsights przechwycenie tylko Warning dzienników i poważniejszych 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 narzędziu 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 on usunięty w następnej wersji głównej zestawu SDK. Aby włączyć telemetrię usługi Application Insights, 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 usługi Application Insights.

Wdrażam moją aplikację ASP.NET Core w usłudze Web Apps. Czy nadal należy włączyć rozszerzenie usługi Application Insights 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 usługi Application Insights 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 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 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 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 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. Zamiast tego użyj usługi Application Insights dla aplikacji usługi Procesu roboczego (aplikacji innych niż HTTP) dla usług procesów roboczych.

Jak mogę odinstalować zestaw SDK?

Aby usunąć usługę Application Insights, 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 pakiet Microsoft.ApplicationInsights.AspNetCore przy użyciu Menedżer pakietów NuGet.
Aby w pełni usunąć usługę Application Insights, sprawdź i ręcznie usuń dodany kod lub pliki wraz z wszystkimi wywołaniami interfejsu API dodanymi w projekcie. Aby uzyskać więcej informacji, zobacz Co zostało utworzone podczas dodawania zestawu SDK usługi Application Insights?.

Co zostało utworzone podczas dodawania zestawu SDK usługi Application Insights?

Po dodaniu usługi Application Insights 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ąć usługę Application Insights, należy sprawdzić i ręcznie usunąć dodany kod lub pliki wraz z wszystkimi wywołaniami interfejsu API dodanymi w projekcie.

Po dodaniu telemetrii usługi Application Insights 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}

ConnectedService.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
    }

Jak wyłączyć korelację telemetrii?

Aby wyłączyć korelację telemetrii w kodzie, zobacz <ExcludeComponentCorrelationHttpHeadersOnDomains> w temacie Application Insights for console applications (Usługa Application Insights dla aplikacji konsolowych).

Rozwiązywanie problemów

Zobacz dedykowany artykuł dotyczący rozwiązywania 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 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 Insights.

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)

Nasze aktualizacje usługi również podsumowują 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 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.

Udostępnij za pośrednictwem

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

Włączanie metryk na żywo przy użyciu kodu dla dowolnej aplikacji .NET

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 Insights

Korzystanie z usługi ApplicationInsightsServiceOptions

Zalecenie dotyczące konfiguracji 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 trybó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ę 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 UseApplicationInsights() w narzędziu IWebHostBuilder w celu włączenia usługi Application Insights. 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 usługi Application Insights z poziomu usługi 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 w przypadku usług roboczych?

Jak mogę odinstalować zestaw SDK?

Co zostało utworzone podczas dodawania zestawu SDK usługi Application Insights?

Jak wyłączyć korelację telemetrii?

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

Opinia

Dodatkowe zasoby