Usługa Application Insights dla aplikacji ASP.NET Core

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

Uwaga

Zalecamy wykorzystanie dystrybucji Azure Monitor OpenTelemetry dla nowych aplikacji lub klientów, aby wspierać działanie usługi Azure Monitor Application Insights. Dystrybucja OpenTelemetry usługi Azure Monitor zapewnia podobną funkcjonalność i doświadczenie jak 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 Application Insights dla aplikacji usługi Worker Service.

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. zakończy się obsługa przyjmowania klucza instrumentacji. Pobieranie klucza instrumentacji będzie nadal działać, ale nie będziemy już udostępniać aktualizacji ani wsparcia dla tej funkcji. Przejście na ciągi połączeń 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: zależność od frameworku lub samodzielna
• Serwer sieci Web: Internet Information Server (IIS) lub Kestrel
• Platforma hostingu: funkcja Web Apps usługi 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

• 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 Insights.
• Prawidłowy łańcuch 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.

1. Otwórz projekt w programie Visual Studio.

2. Przejdź do Project>Dodaj telemetrię Application Insights.

3. Wybierz pozycję Azure Application Insights>Dalej.

4. Wybierz subskrypcję i wystąpienie usługi Application Insights. Możesz też utworzyć nowe wystąpienie za pomocą polecenia Utwórz nowe. Wybierz Dalej.

5. Dodaj lub potwierdź parametry połączenia usługi Application Insights. Powinna zostać wstępnie wypełniona na podstawie Twojego wyboru w poprzednim kroku. Wybierz Zakończ.

6. Po dodaniu usługi Application Insights do projektu sprawdź, czy używasz najnowszej stabilnej wersji zestawu SDK. Przejdź do Projekt>Zarządzaj 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)

1. Zainstaluj pakiet NuGet dla zestawu SDK usługi Application Insights na platformę 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>
   

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

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

     Ciąg połączenia określony w kodzie ma priorytet nad zmienną środowiskową APPLICATIONINSIGHTS_CONNECTION_STRING, która ma priorytet nad innymi opcjami.

   • Ustaw parametry połączenia w kodzie.

     Podaj łańcuch połączenia jako część argumentu ApplicationInsightsServiceOptions do AddApplicationInsightsTelemetry w klasie program.cs.

Wpisy tajne użytkownika i inni dostawcy konfiguracji

Jeśli chcesz przechowywać ciąg połączeń w tajnych użytkownika ASP.NET Core 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 załadował konfigurację z wielu dostawców, to services.AddApplicationInsightsTelemetry określa priorytety konfiguracji z appsettings.json, niezależnie od kolejności dodawania dostawców. Użyj metody services.AddApplicationInsightsTelemetry(IConfiguration) do odczytu konfiguracji 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 aplikacji za pomocą usługi Application Insights jest poprawnie skonfigurowane. Dane telemetryczne mogą pojawić się w portalu Azure, ale okienko metryk na żywo pokazuje użycie procesora działającego 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 wdrażania przy użyciu zalecanych instrukcji dla aplikacji .NET.

Aby ręcznie skonfigurować metryki na żywo:

1. Zainstaluj pakiet NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. 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 ILogger

Domyślna konfiguracja zbiera ILoggerWarning dzienniki oraz dzienniki o wyższym poziomie ważności. 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).
• Wersje SDK 2.7.1 i nowsze zbierają liczniki wydajności, jeśli aplikacja jest uruchomiona w systemie Windows i obsługuje netstandard2.0 lub nowsze.
• W przypadku aplikacji przeznaczonych dla platformy .NET Framework wszystkie wersje zestawu SDK obsługują liczniki wydajności.
• Wersje SDK 2.8.0 i nowsze obsługują licznik 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.

1. W pliku _ViewImports.cshtml dodaj iniekcję:

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. 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 używania FullScript jest dostępność ScriptBody począwszy od wersji 2.14 SDK Application Insights dla platformy ASP.NET Core. Użyj ScriptBody, jeśli musisz kontrolować znacznik <script>, aby ustawić Politykę Zabezpieczeń Treś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 ciągu połączenia, musisz usunąć automatyczne wstrzykiwanie zgodnie z opisem i ręcznie dodać JavaScript SDK.

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 metodzie klasy Startup.cs, chyba że zostaniesz poinstruowany 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 do AddApplicationInsightsTelemetry, 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
WłączEnablePerformanceCounterCollectionModule	Włącz/wyłącz PerformanceCounterCollectionModule.	Prawda
WłączModułTelemetriiŚledzeniaŻądań	Włącz/wyłącz RequestTrackingTelemetryModule.	Prawda
WłączModułZbieraniaLicznikówZdarzeń	Włącz/wyłącz EventCounterCollectionModule.	Prawda
WłączModułTelemetriiŚledzeniaZależności	Włącz/wyłącz DependencyTrackingTelemetryModule.	Prawda
EnableAppServicesHeartbeatTelemetryModule	Włącz/wyłącz AppServicesHeartbeatTelemetryModule.	Prawda
WłączAzureInstanceMetadataTelemetryModule	Włącz/wyłącz AzureInstanceMetadataTelemetryModule.	Prawda
Włącz Strumień Szybkiego Pulsu Metrycznego	Włącz/wyłącz funkcję LiveMetrics.	Prawda
Włącz adaptacyjne próbkowanie	Włączanie/wyłączanie próbkowania adaptacyjnego.	Prawda
Włącz bicie serca	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
OpcjeZbieraniaŻądań.ŚledzenieWyjątków	Włącz/wyłącz raportowanie śledzenia nieobsługiwanych wyjątków przez moduł zbierania żądań.	Fałsz w netstandard2.0 (ponieważ wyjątki są śledzone za pomocą ApplicationInsightsLoggerProvider). W przeciwnym razie jest prawdą.
EnableDiagnosticsTelemetryModule	Włącz/wyłącz DiagnosticsTelemetryModule. Wyłączenie powoduje ignorowanie następujących ustawień: EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModulei EnableAppServicesHeartbeatTelemetryModule.	Prawda

Aby uzyskać najbardziej aktualną listę, zobacz ustawienia konfigurowalne w 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 dostępne ustawienie 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.

Dodaj inicjalizatory telemetrii

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 przechwytuje wszystkie TelemetryInitializer, które są 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.

Usuń TelemetryInitializers

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 przy użyciu metody rozszerzającej AddApplicationInsightsTelemetryProcessor na 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();

Konfiguruj lub usuwaj domyślne moduły 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 automatycznego zbierania danych. 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 RequestTelemetry z przychodzących żądań sieciowych.
• 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 pulsów (które są wysyłane jako metryki niestandardowe) dotyczących środowiska usługi App Service, w którym aplikacja jest hostowana.
• AzureInstanceMetadataTelemetryModule: zbiera sygnały serca (które są przesyłane jako metryki niestandardowe) ze środowiska maszyny wirtualnej platformy Azure, gdzie jest hostowana aplikacja.
• EventCounterCollectionModule: zbiera EventCounters. Ten moduł jest nową funkcją i jest dostępny w zestawie SDK w wersji 2.8.0 lub nowszej.

Aby skonfigurować dowolny domyślny TelemetryModule, użyj metody rozszerzenia ConfigureTelemetryModule<T> na 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 wywołać wystąpienie TelemetryConfiguration przy użyciu kontenera do 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 Usuń moduł 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 narazić na ujawnienie danych osobowych (PII) w telemetrii i spowodować znaczący wzrost kosztów (kosztów wydajności oraz rozliczeń w usłudze Application Insights), dlatego dokładnie oszacuj ryzyko przed skorzystaniem z tej funkcji.

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 logi o mniejszym znaczeniu, zmieniając konfigurację rejestrowania dostawcy 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 rozszerzenia UseApplicationInsights() jest nadal obsługiwana, ale w wersji 2.8.0 i nowszych zestawu SDK usługi Application Insights jest oznaczona jako przestarzała. 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 ASP.NET Core 3.X services.AddApplicationInsightsTelemetry() jest jedynym sposobem włączenia 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 autonomiczne lub zależne od środowiska.
  • 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.
• Możesz śledzić więcej niestandardowych danych telemetrycznych, korzystając z interfejsu API TrackXXX().
• 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 pracowniczych?

Nr. Zamiast tego użyj Application Insights dla aplikacji Worker Service (aplikacji nieopartych na HTTP) w przypadku usług worker.

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

1. Odinstaluj pakiet Microsoft.ApplicationInsights.AspNetCore przy użyciu Menedżer pakietów NuGet.
2. 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ą przyjmowania danych

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 sieciowego lub maszyny hosta aplikacji do punktów końcowych usługi odbierania danych za pomocą podstawowych klientów REST z poziomu programu PowerShell lub polecenia 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 adaptery 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 przeglądać stan kodu źródłowego i zmiennych w momencie wystąpienia 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 aplikacji, aby stale sprawdzać swoją aplikację na całym świecie.
• Dowiedz się więcej o iniekcji zależności w programie ASP.NET Core.