Konfigurowanie zestawu SDK Szczegółowe informacje aplikacji przy użyciu polecenia Application Szczegółowe informacje.config lub .xml

  • Artykuł

Zestaw SDK platformy .NET aplikacji Szczegółowe informacje składa się z wielu pakietów NuGet. Pakiet podstawowy udostępnia interfejs API do wysyłania danych telemetrycznych do Szczegółowe informacje aplikacji. Więcej pakietów udostępnia 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 telemetrii i inicjatory. Można również ustawić parametry dla niektórych z nich.

Uwaga

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

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

Nie ma równoważnego pliku do kontrolowania zestawu SDK na stronie internetowej.

W tym artykule opisano sekcje widoczne w pliku konfiguracji, sposób kontrolowania składników zestawu SDK oraz ładowania tych składników przez pakiety NuGet.

Uwaga

Instrukcje ApplicationInsights.config i .xml nie mają zastosowania do zestawu .NET Core SDK. Aby skonfigurować aplikacje platformy .NET Core, postępuj zgodnie z instrukcjami w temacie Application Szczegółowe informacje for ASP.NET Core applications (Aplikacje ASP.NET Core).

Moduły telemetrii (ASP.NET)

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

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

Śledzenie zależności

Funkcja śledzenia zależności zbiera dane telemetryczne dotyczące wywołań aplikacji do baz danych i usług zewnętrznych i baz danych. Aby umożliwić działanie tego modułu na serwerze usług IIS, należy zainstalować program Application Szczegółowe informacje Agent.

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

Zależności można automatycznie modyfikować bez modyfikowania kodu przy użyciu dołączania opartego na agencie (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 Application Monitoring dla maszyn wirtualnych i zestawów skalowania maszyn wirtualnych.

Moduł zbierający wydajność

Moduł zbierający wydajność zbiera liczniki wydajności systemu, takie jak procesor CPU, pamięć i obciążenie sieciowe z instalacji usług IIS. Możesz określić liczniki do zebrania, w tym liczniki wydajności skonfigurowane samodzielnie.

Telemetria diagnostyki Szczegółowe informacje aplikacji

Klasa DiagnosticsTelemetryModule zgłasza błędy w kodzie instrumentacji aplikacji Szczegółowe informacje. Przykłady to, jeśli kod nie może uzyskać dostępu do liczników wydajności lub zgłasza ITelemetryInitializer wyjątek. Śledzenie danych telemetrycznych śledzonych przez ten moduł jest wyświetlane w wyszukiwaniu diagnostycznym.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.Application Szczegółowe informacje pakiet NuGet. Jeśli zainstalujesz tylko ten pakiet, plik Application Szczegółowe informacje.config nie zostanie automatycznie utworzony.

Tryb dewelopera

Klasa DeveloperModeWithDebuggerAttachedTelemetryModule wymusza, aby aplikacja Szczegółowe informacje TelemetryChannel wysyłała dane natychmiast, jeden element telemetrii w danym momencie, gdy debuger jest dołączony do procesu aplikacji. Ten projekt skraca czas między momentem, w którym aplikacja śledzi dane telemetryczne, a kiedy pojawia się w portalu Application Szczegółowe informacje. Powoduje to znaczne obciążenie procesora CPU i przepustowości sieci.

Śledzenie żądań internetowych

Śledzenie żądań internetowych zgłasza czas odpowiedzi i kod wyniku żądań HTTP.

Śledzenie wyjątków

Klasa ExceptionTrackingTelemetryModule śledzi nieobsługiwane wyjątki w aplikacji internetowej. Aby uzyskać więcej informacji, zobacz Błędy i wyjątki.

Śledzenie źródła zdarzeń

Klasa EventSourceTelemetryModule umożliwia skonfigurowanie zdarzeń eventsource do wysyłania do aplikacji Szczegółowe informacje jako śladów. Aby uzyskać informacje na temat śledzenia zdarzeń eventsource, zobacz Using EventSource events (Używanie zdarzeń eventsource).

Śledzenie zdarzeń ETW

Klasa EtwCollectorTelemetryModule umożliwia skonfigurowanie zdarzeń od dostawców ETW do wysyłania do aplikacji Szczegółowe informacje jako śladów. Aby uzyskać informacje na temat śledzenia zdarzeń ETW, zobacz Using ETW events (Używanie zdarzeń ETW).

Microsoft.Application Szczegółowe informacje

Pakiet Microsoft.ApplicationInsights udostępnia podstawowy interfejs API zestawu SDK. Inne moduły telemetrii używają tego interfejsu API. Można go również użyć do zdefiniowania własnych danych telemetrycznych.

Kanał telemetrii

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

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

Inicjatory telemetrii (ASP.NET)

Inicjatory telemetrii ustawiają właściwości kontekstu 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 NuGet web lub WindowsServer:

  • AccountIdTelemetryInitializerAccountId ustawia właściwość .

  • AuthenticatedUserIdTelemetryInitializer Ustawia właściwość ustawioną AuthenticatedUserId przez zestaw SDK języka JavaScript.

  • AzureRoleEnvironmentTelemetryInitializerRoleName aktualizuje właściwości Device i RoleInstance kontekstu dla wszystkich elementów telemetrii z informacjami wyodrębnianymi ze środowiska uruchomieniowego platformy Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializerVersion aktualizuje właściwość Component kontekstu dla wszystkich elementów telemetrii z wartością wyodrębnianą z pliku utworzonego BuildInfo.config przez program MS Build.

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

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

    • Type jest ustawiona na PCwartość .
    • Id jest ustawiona na nazwę domeny komputera, na którym działa aplikacja internetowa.
    • OemName parametr jest ustawiany na wartość wyodrębnianą z Win32_ComputerSystem.Manufacturer pola przy użyciu usługi WMI.
    • Model parametr jest ustawiany na wartość wyodrębnianą z Win32_ComputerSystem.Model pola przy użyciu usługi WMI.
    • NetworkType jest ustawiona na wartość wyodrębnianą z NetworkInterface właściwości .
    • Language jest ustawiona na nazwę CurrentCulture właściwości.

  • DomainNameRoleInstanceTelemetryInitializerRoleInstance aktualizuje właściwość Device kontekstu dla wszystkich elementów telemetrii o nazwie domeny komputera, na którym działa aplikacja internetowa.

  • OperationNameTelemetryInitializerName aktualizuje właściwość i Name właściwość RequestTelemetryOperation kontekstu wszystkich elementów telemetrii na podstawie metody HTTP oraz nazwy kontrolera ASP.NET MVC i akcji wywoływanej w celu przetworzenia żądania.

  • OperationIdTelemetryInitializer lub OperationCorrelationTelemetryInitializer aktualizuje Operation.Id właściwość kontekstu wszystkich elementów telemetrii śledzonych podczas obsługi żądania przy użyciu automatycznie wygenerowanego RequestTelemetry.Idelementu .

  • SessionTelemetryInitializerId Aktualizuje właściwość Session kontekstu dla wszystkich elementów telemetrii z wartością wyodrębnianą z ai_session pliku cookie wygenerowanego przez ApplicationInsights kod instrumentacji JavaScript uruchomiony w przeglądarce użytkownika.

  • SyntheticTelemetryInitializer lub SyntheticUserAgentTelemetryInitializer aktualizuje Userwłaściwości kontekstu , Sessioni Operation wszystkich elementów telemetrii śledzonych podczas obsługi żądania ze źródła syntetycznego, takiego jak test dostępności lub bot wyszukiwarki. Domyślnie eksplorator metryk nie wyświetla syntetycznych danych telemetrycznych.

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

  • UserTelemetryInitializerId Aktualizuje właściwości User i AcquisitionDate kontekstu dla wszystkich elementów telemetrii z wartościami wyodrębnianymi z ai_user pliku cookie wygenerowanego przez kod instrumentacji JavaScript aplikacji Szczegółowe informacje uruchomiony w przeglądarce użytkownika.

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

W przypadku aplikacji platformy .NET działających w usłudze Azure Service Fabric można uwzględnić Microsoft.ApplicationInsights.ServiceFabric pakiet NuGet. Ten pakiet zawiera FabricTelemetryInitializer właściwość, która dodaje właściwości usługi Service Fabric do elementów telemetrii. Aby uzyskać więcej informacji, zobacz stronę usługi GitHub na temat właściwości dodanych przez ten pakiet NuGet.

Procesory telemetryczne (ASP.NET)

Procesory telemetryczne mogą filtrować i modyfikować każdy element telemetrii przed wysłaniem go z zestawu SDK do portalu.

Możesz napisać własne procesory telemetryczne.

Adaptacyjny procesor telemetrii próbkowania (z wersji 2.0.0-beta3)

Ta funkcja jest domyślnie włączona. Jeśli aplikacja wysyła znaczną ilość 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 element docelowy, który algorytm próbuje osiągnąć. Każde wystąpienie zestawu SDK działa niezależnie. W związku z tym, 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>

ConnectionString

Zobacz parametry połączenia przykłady kodu.

InstrumentationKey

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.

To ustawienie określa zasób aplikacji Szczegółowe informacje, w którym są wyświetlane dane. Zazwyczaj należy utworzyć oddzielny zasób z oddzielnym kluczem dla każdej z 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 ustawić go w kodzie.

Aby ustawić klucz dla wszystkich wystąpień programu , w tym standardowych modułów telemetrycznych TelemetryClient, wykonaj ten krok w metodzie inicjowania, takiej jak global.aspx.cs w usłudze ASP.NET:

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 wysłać określony zestaw zdarzeń do innego zasobu, możesz ustawić klucz dla określonego klienta telemetrii:


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

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

Dostawca identyfikatora aplikacji

Dostawca jest dostępny od wersji 2.6.0.

Celem tego dostawcy jest wyszukanie identyfikatora aplikacji na podstawie klucza instrumentacji. Identyfikator aplikacji jest uwzględniony i RequestTelemetryDependencyTelemetry służy do określania korelacji w portalu.

Ta funkcja jest dostępna przez ustawienie TelemetryConfiguration.ApplicationIdProvider w kodzie lub w pliku konfiguracji.

Interfejs: IApplicationIdProvider

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

Udostępniamy dwie implementacje w zestawie Microsoft.Application Szczegółowe informacje SDK: ApplicationInsightsApplicationIdProvider i DictionaryApplicationIdProvider.

Application Szczegółowe informacje ApplicationIdProvider

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

Ten dostawca jest dodawany do pliku konfiguracji podczas instalowania aplikacji Microsoft.Application Szczegółowe informacje. DependencyCollector lub Microsoft.Application Szczegółowe informacje. Sieć Web.

Ta klasa ma opcjonalną właściwość ProfileQueryEndpoint. Domyślnie jest ustawiona wartość https://dc.services.visualstudio.com/api/profiles/{0}/appId. Jeśli musisz skonfigurować serwer proxy dla tej konfiguracji, zalecamy użycie serwera proxy adresu podstawowego i dołączenie "/api/profiles/{0}/appId"elementu . Element {0} jest zastępowany w czasie wykonywania na żądanie za pomocą klucza instrumentacji.

Przykładowa konfiguracja za pośrednictwem aplikacji Szczegółowe informacje.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 pomocą kodu

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Ten statyczny dostawca korzysta ze skonfigurowanych par klucz instrumentacji/identyfikator aplikacji.

Ta klasa ma Defined właściwość , która jest parami Dictionary<string,string> klucza instrumentacji/identyfikatora aplikacji.

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

Przykładowa konfiguracja za pośrednictwem aplikacji Szczegółowe informacje.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 pomocą kodu

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

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET

Konfigurowanie kolekcji migawek dla aplikacji ASP.NET.

Następne kroki

Dowiedz się więcej o interfejsie API