Konfigurowanie zestawu SDK usługi Application Insights za pomocą pliku ApplicationInsights.config lub xml

Zestaw SDK Szczegółowe informacje platformy .NET składa się z NuGet pakietów. Pakiet podstawowy udostępnia interfejs API do wysyłania danych telemetrycznych do usługi Application Szczegółowe informacje. Dodatkowe pakiety zapewniają moduły telemetrii i inicjatory do automatycznego śledzenia danych telemetrycznych z aplikacji i jej kontekstu. Dostosowując plik konfiguracji, można włączyć lub wyłączyć moduły i inicjatory telemetrii oraz ustawić parametry dla niektórych z nich.

Plik konfiguracji ma nazwę ApplicationInsights.config lub , w zależności od typu ApplicationInsights.xml aplikacji. Jest on automatycznie dodawany do projektu podczas instalowania większości wersji zestawu SDK. Domyślnie w przypadku korzystania ze zautomatyzowanego obsługi z projektów szablonów usługi Visual Studio, które obsługują dodawanie telemetrii usługi Application Szczegółowe informacje,plik ApplicationInsights.config jest tworzony w folderze głównym projektu, a po skompilowaniu jest kopiowany do folderu bin. Jest on również dodawany do aplikacji internetowej przez monitor stanu na serwerze usług IIS. Plik konfiguracji jest ignorowany, jeśli używane jest rozszerzenie dla witryny internetowej platformy Azure lub rozszerzenie dla maszyny wirtualnej platformy Azure i zestawu skalowania maszyn wirtualnych.

Na stronie internetowej nie ma równoważnego pliku służącego do kontrolowania zestawu SDK.

W tym dokumencie opisano sekcje, które są dostępne w pliku konfiguracji, sposób kontrolowania składników zestawu SDK oraz NuGet ładowania tych składników.

Uwaga

ApplicationInsights.config i .xml nie mają zastosowania do zestaw .NET Core SDK. Aby skonfigurować aplikacje .NET Core, postępuj zgodnie z tym przewodnikiem.

Moduły telemetrii (ASP.NET)

Każdy moduł telemetrii zbiera dane określonego typu i używa podstawowego interfejsu API do wysyłania danych. Moduły są instalowane przez różne pakiety NuGet, które dodają również wymagane wiersze do .config plików.

W pliku konfiguracji znajduje się węzeł dla każdego modułu. Aby wyłączyć moduł, usuń węzeł lub zakłoń go w komentarz.

Śledzenie zależności

Śledzenie zależności zbiera dane telemetryczne dotyczące wywołań, które aplikacja wykonuje do baz danych oraz usług zewnętrznych i baz danych. Aby umożliwić pracę tego modułu na serwerze usług IIS, należy zainstalować program monitor stanu.

Możesz również napisać własny kod śledzenia zależności przy użyciu interfejsu API TrackDependency.

Zależności można zbierać automatycznie bez modyfikowania kodu przy użyciu dołączania opartego na agentach (bez kodu). Aby używać go w aplikacjach internetowych platformy Azure, włącz rozszerzenie Application Szczegółowe informacje. Aby używać go na maszynie wirtualnej platformy Azure lub w zestawie skalowania maszyn wirtualnych platformy Azure, włącz rozszerzenie monitorowania aplikacji dla maszyny wirtualnej i zestawu skalowania maszyn wirtualnych.

Moduł zbierający wydajność

Zbiera liczniki wydajności systemu, takie jak procesor CPU, pamięć i obciążenie sieci, z instalacji usług IIS. Możesz określić, które liczniki mają być zbierane, w tym liczniki wydajności, które zostały samodzielnie ustawione.

Telemetria diagnostyki Szczegółowe informacje aplikacji

Raporty DiagnosticsTelemetryModule błędów w aplikacji Szczegółowe informacje instrumentacji. Na przykład jeśli kod nie może uzyskać dostępu do liczników wydajności lub jeśli zgłasza ITelemetryInitializer wyjątek. Telemetria śledzenia śledzona przez ten moduł jest wyświetlana w wyszukiwaniu diagnostycznym.

* `Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule`
* [Microsoft.ApplicationInsights](https://www.nuget.org/packages/Microsoft.ApplicationInsights) NuGet package. If you only install this package, the ApplicationInsights.config file is not automatically created.

Tryb dewelopera

DeveloperModeWithDebuggerAttachedTelemetryModuleWymusza, aby Szczegółowe informacje aplikacji natychmiast wysyłały dane, po jednym elementze telemetrii na raz, gdy debuger jest TelemetryChannel dołączony do procesu aplikacji. Pozwala to skrócić czas między śledzeniem telemetrii przez aplikację i pojawiania się jej w portalu Szczegółowe informacje Aplikacji. Powoduje to znaczne obciążenie procesora CPU i przepustowości sieci.

Śledzenie żądań internetowych

Raportuje czas odpowiedzi i kod wyniku żądań HTTP.

Śledzenie wyjątków

ExceptionTrackingTelemetryModule śledzi nieobsługiwane wyjątki w aplikacji internetowej. Zobacz Błędy i wyjątki.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
  • Pakiet microsoft.ApplicationInsights.Web NuGet pakietu
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule — śledzi nieobserwowane wyjątki zadań
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule— śledzi nieobsługiwane wyjątki dla ról procesów roboczych, Windows usług i aplikacji konsoli.
  • Pakiet Szczegółowe informacje Windows Server NuGet Server.

Śledzenie w usłudze EventSource

EventSourceTelemetryModuleUmożliwia skonfigurowanie zdarzeń EventSource, które mają być wysyłane do usługi Application Szczegółowe informacje jako ślady. Aby uzyskać informacje na temat śledzenia zdarzeń eventSource, zobacz Using EventSource Events (Używanie zdarzeń EventSource).

Śledzenie zdarzeń ETW

EtwCollectorTelemetryModuleUmożliwia skonfigurowanie zdarzeń od dostawców ETW, które mają być wysyłane do usługi Application Szczegółowe informacje jako ślady. Aby uzyskać informacje na temat śledzenia zdarzeń ETW, zobacz Using ETW Events (Używanie zdarzeń ETW).

Microsoft.ApplicationInsights

Pakiet Microsoft.ApplicationInsights udostępnia podstawowy interfejs API zestawu SDK. Inne moduły telemetrii używają tej funkcji i można jej również używać do definiowania własnych danych telemetrycznych.

Kanał telemetrii

Kanał telemetrii zarządza buforowaniem i przesyłaniem danych telemetrycznych do usługi Application Szczegółowe informacje Service.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel jest domyślnym kanałem dla aplikacji internetowych. Buforuje dane w pamięci i wykorzystuje mechanizmy ponawiania prób oraz magazyn dysków lokalnych w celu bardziej niezawodnego dostarczania danych telemetrycznych.
  • Microsoft.ApplicationInsights.InMemoryChannel to lekki kanał telemetrii, który jest używany, jeśli nie skonfigurowano żadnego innego kanału.

Inicjatory telemetrii (ASP.NET)

Inicjatory telemetrii ustawiają właściwości kontekstu, które są wysyłane wraz z każdym elementem telemetrii.

Możesz napisać własne inicjatory, aby ustawić właściwości kontekstu.

Wszystkie standardowe inicjatory są ustawiane przez pakiety internetowe lub pakiety NuGet WindowsServer:

  • AccountIdTelemetryInitializer Ustawia właściwość AccountId.

  • AuthenticatedUserIdTelemetryInitializer Ustawia właściwość AuthenticatedUserId zgodnie z ustawieniem zestawu SDK języka JavaScript.

  • AzureRoleEnvironmentTelemetryInitializer aktualizuje właściwości RoleName i kontekstu dla wszystkich elementów RoleInstanceDevice telemetrii przy użyciu informacji wyodrębnianych ze środowiska uruchomieniowego platformy Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializer aktualizuje właściwość kontekstu dla wszystkich elementów telemetrii przy użyciu wartości VersionComponent wyodrębnianej z BuildInfo.config pliku produkowanego przez kompilację MS.

  • ClientIpHeaderTelemetryInitializer właściwość Ip updates kontekstu wszystkich elementów Location telemetrii na podstawie X-Forwarded-For nagłówka HTTP żądania.

  • DeviceTelemetryInitializer aktualizuje następujące właściwości kontekstu Device dla wszystkich elementów telemetrii.

    • Type jest ustawiona na wartość "PC"
    • Id jest ustawiona na nazwę domeny komputera, na którym jest uruchomiona aplikacja internetowa.
    • OemName jest ustawiona na wartość wyodrębnianą z Win32_ComputerSystem.Manufacturer pola przy użyciu usługi WMI.
    • Model jest ustawiona na wartość wyodrębnianą z Win32_ComputerSystem.Model pola przy użyciu usługi WMI.
    • NetworkType jest ustawiona na wartość wyodrębnianą z NetworkInterface .
    • Language Jest ustawiona na nazwę CurrentCulture .
  • DomainNameRoleInstanceTelemetryInitializer aktualizuje właściwość kontekstu dla wszystkich elementów telemetrii przy użyciu nazwy domeny komputera, na RoleInstance którym jest uruchomiona aplikacja Device internetowa.

  • OperationNameTelemetryInitializerAktualizuje właściwość i właściwości kontekstu wszystkich elementów telemetrii na podstawie metody HTTP, a także nazwy kontrolera ASP.NET MVC i akcji wywoływanej w celu przetwarzania NameRequestTelemetryNameOperation żądania.

  • OperationIdTelemetryInitializer lub OperationCorrelationTelemetryInitializer aktualizuje właściwość kontekstu wszystkich elementów Operation.Id telemetrii śledzone podczas obsługi żądania za pomocą automatycznie wygenerowanego obiektu RequestTelemetry.Id .

  • SessionTelemetryInitializer aktualizuje właściwość kontekstu dla wszystkich elementów telemetrii z wartością wyodrębnioną z pliku cookie wygenerowanego przez kod IdSessionai_session instrumentacji JavaScript usługi ApplicationInsights uruchomiony w przeglądarce użytkownika.

  • SyntheticTelemetryInitializer lub aktualizuje właściwości , i kontekstów wszystkich elementów telemetrii śledzone podczas obsługi żądania ze źródła syntetycznego, takiego jak test dostępności lub SyntheticUserAgentTelemetryInitializerUser bot SessionOperation wyszukiwarki. Domyślnie program Eksplorator metryk nie wyświetla syntetycznej telemetrii.

    Zestaw <Filters> identyfikujący właściwości żądań.

  • UserTelemetryInitializeraktualizuje właściwości i kontekstu dla wszystkich elementów telemetrii przy użyciu wartości wyodrębnianych z pliku cookie wygenerowanego przez kod instrumentacji JavaScript usługi Application Szczegółowe informacje uruchomiony w przeglądarce IdAcquisitionDateUserai_user użytkownika.

  • WebTestTelemetryInitializer Ustawia identyfikator użytkownika, identyfikator sesji i syntetyczne właściwości źródła dla żądań HTTP, które pochodzą z WebTestTelemetryInitializer. Zestaw <Filters> identyfikujący właściwości żądań.

W przypadku aplikacji .NET uruchomionych Service Fabric programie można dołączyć Microsoft.ApplicationInsights.ServiceFabric NuGet pakiet. Ten pakiet zawiera FabricTelemetryInitializer element , który Service Fabric właściwości do elementów telemetrii. Aby uzyskać więcej informacji, zobacz GitHub o właściwościach dodanych przez ten NuGet pakietu.

Procesory telemetrii (ASP.NET)

Procesory telemetrii mogą filtrować i modyfikować poszczególne elementy telemetrii tuż przed ich wysłaniem z zestawu SDK do portalu.

Możesz napisać własne procesory telemetrii.

Procesor telemetrii próbkowania adaptacyjnego (z wersji 2.0.0-beta3)

Ta opcja jest domyślnie włączona. Jeśli aplikacja wysyła dużą część danych telemetrycznych, ten procesor usunie niektóre z nich.


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

Parametr udostępnia obiekt docelowy, który algorytm próbuje osiągnąć. Każde wystąpienie zestawu SDK działa niezależnie, więc jeśli serwer jest klastrem kilku maszyn, rzeczywista ilość danych telemetrycznych zostanie odpowiednio pomnożona.

Dowiedz się więcej o próbkowaniu.

Procesor telemetrii próbkowania o stałej szybkości (z wersji 2.0.0-beta1)

Istnieje również standardowy procesor telemetrii próbkowania (z wersji 2.0.1):


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

InstrumentationKey

To określa zasób Szczegółowe informacje aplikacji, w którym są wyświetlane dane. Zazwyczaj tworzy się oddzielny zasób z oddzielnym kluczem dla każdej aplikacji.

Jeśli chcesz ustawić klucz dynamicznie — na przykład jeśli chcesz wysyłać wyniki z aplikacji do różnych zasobów — możesz pominąć klucz z pliku konfiguracji i zamiast tego ustawić go w kodzie.

Aby ustawić klucz dla wszystkich wystąpień klasy TelemetryClient, w tym standardowych modułów telemetrii. Zrób to w metodzie inicjowania, takiej jak global.aspx.cs, w ASP.NET usługi:

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Jeśli chcesz tylko wysłać określony zestaw zdarzeń do innego zasobu, możesz ustawić klucz dla określonego klienta TelemetryClient:


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Aby uzyskać nowy klucz, utwórz nowy zasób w witrynie Application Szczegółowe informacje Portal.

Dostawca ApplicationId

Dostępne od wersji 2.6.0

Celem tego dostawcy jest wyszukiwania identyfikatora aplikacji na podstawie klucza instrumentacji. Identyfikator aplikacji jest zawarty w requestTelemetry i DependencyTelemetry i używany do określania korelacji w portalu.

Jest to dostępne przez ustawienie TelemetryConfiguration.ApplicationIdProvider w kodzie lub w konfiguracji.

Interfejs: IApplicationIdProvider

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

W zestawie Sdk Microsoft.ApplicationInsights są dostępne dwie implementacje: i DictionaryApplicationIdProvider .

ApplicationInsightsApplicationIdProvider

Jest to otoka naszego interfejsu API profilu. Spowoduje to ograniczenie żądań i buforowanie wyników.

Ten dostawca jest dodawany do pliku konfiguracji podczas instalowania pliku Microsoft.ApplicationInsights.DependencyCollector lub Microsoft.ApplicationInsights.Web

Ta klasa ma opcjonalną właściwość ProfileQueryEndpoint . Domyślnie jest to wartość https://dc.services.visualstudio.com/api/profiles/{0}/appId . Jeśli musisz skonfigurować serwer proxy dla tej konfiguracji, zalecamy użycie serwera proxy dla adresu podstawowego i uwzględnienia opcji "/api/profiles/ {0} /appId". Należy pamiętać, {0} że element " " jest zastępowany w czasie wykonywania dla każdego żądania kluczem instrumentacji.

Przykładowa konfiguracja za pośrednictwem ApplicationInsights.config:

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Przykładowa konfiguracja za pośrednictwem kodu:

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Jest to dostawca statyczny, który będzie polegać na skonfigurowanych parach klucz instrumentacji/identyfikator aplikacji.

Ta klasa ma właściwość Defined , która jest ciągiem słownika, <> ciągiem klucza instrumentacji do par identyfikatorów aplikacji.

Ta klasa ma opcjonalną właściwość, która może służyć do konfigurowania innego dostawcy do użycia w przypadku zażądania klucza instrumentacji, który Next nie istnieje w konfiguracji.

Przykładowa konfiguracja za pośrednictwem ApplicationInsights.config:

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Przykładowa konfiguracja za pośrednictwem kodu:

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Następne kroki

Dowiedz się więcej o interfejsie API.