Application Insights für Workerdienstanwendungen (Anwendungen ohne HTTP)

Artikel
01/31/2024

Das Application Insights SDK für Workerdienstanwendungen ist ein neues SDK, das sich perfekt für Workloads ohne HTTP eignet, z. B. Messaging, Hintergrundaufgaben und Konsolenanwendungen. Bei diesen Anwendungstypen gibt es keine eingehenden HTTP-Anforderungen wie bei einer herkömmlichen ASP.NET-/ASP.NET Core-Webanwendung. Aus diesem Grund wird die Verwendung von Application Insights-Paketen für ASP.NET- und ASP.NET Core-Anwendungen nicht unterstützt.

Hinweis

Die folgende Dokumentation basiert auf der klassischen Application Insights-API. Der langfristige Plan für Application Insights besteht darin, Daten mithilfe von OpenTelemetry zu sammeln. Weitere Informationen finden Sie unter Aktivieren von Azure Monitor OpenTelemetry für .NET-, Node.js-, Python- und Java-Anwendungen.

Das neue SDK sammelt keine Telemetriedaten von selbst. Stattdessen nutzt es andere bekannte automatische Application Insights-Collectors, z. B. DependencyCollector, PerfCounterCollector und ApplicationInsightsLoggingProvider. Dieses SDK macht Erweiterungsmethoden in IServiceCollection verfügbar, um die Erfassung von Telemetriedaten zu aktivieren und zu konfigurieren.

Unterstützte Szenarios

Das Application Insights SDK für Workerdienstanwendungen eignet sich perfekt für Anwendungen ohne HTTP, unabhängig davon, wo und wie sie ausgeführt werden. Wenn Ihre Anwendung ausgeführt wird und über eine Netzwerkverbindung mit Azure verfügt, können Telemetriedaten erfasst werden. Die Application Insights-Überwachung wird in allen Umgebungen unterstützt, in denen auch .NET Core unterstützt wird. Dieses Paket kann in den neu eingeführten .NET Core-Workerdienst, Hintergrundaufgaben in ASP.NET Core, Konsolen-Apps wie .NET Core und .NET Framework verwendet werden.

Voraussetzungen

Sie benötigen eine gültige Application Insights-Verbindungszeichenfolge. Diese Zeichenfolge ist erforderlich, um Telemetriedaten an Application Insights zu senden. Wenn Sie eine neue Application Insights-Ressource erstellen müssen, um eine Verbindungszeichenfolge abzurufen, finden Sie unter Erstellen einer Application Insights-Ressource weitere Informationen.

Hinweis

Am 31. März 2025 wird der Support für die auf Instrumentierungsschlüsseln basierende Erfassung eingestellt. Die Erfassung von Instrumentierungsschlüsseln funktioniert zwar weiterhin, wir stellen jedoch keine Updates und keinen Support mehr für das Feature bereit. Wechseln Sie zu Verbindungszeichenfolgen, damit Sie neue Funktionen nutzen können.

Verwenden des Application Insights SDK für Workerdienste

Installieren Sie das Paket Microsoft.ApplicationInsights.WorkerService für die Anwendung. Der folgende Codeausschnitt zeigt die Änderungen, die Sie der .csproj-Datei Ihres Projekts vornehmen müssen:
```
    <ItemGroup>
        <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    </ItemGroup>
```
Konfigurieren Sie die Verbindungszeichenfolge in der Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING oder in der Konfiguration (appsettings.json).
Rufen Sie eine ILogger-Instanz oder TelemetryClient-Instanz aus dem Abhängigkeitsinjektionscontainer (Dependency Injection, DI) ab, indem Sie serviceProvider.GetRequiredService<TelemetryClient>(); aufrufen oder die Konstruktorinjektion verwenden. Durch diesen Schritt wird das Einrichten des TelemetryConfiguration-Moduls und des Moduls für die automatische Sammlung ausgelöst.

Spezielle Anweisungen für die einzelnen Anwendungstypen finden Sie in den folgenden Abschnitten.

.NET Core-Workerdienstanwendung

Das vollständige Beispiel finden Sie auf der NuGet-Website.

Laden Sie das .NET SDK herunter, und installieren Sie es.
Erstellen Sie mit einer Visual Studio-Projektvorlage oder mit der Befehlszeile dotnet new worker ein neues Workerdienstprojekt.
Fügen Sie das Paket Microsoft.ApplicationInsights.WorkerService der Anwendung hinzu.

Fügen Sie wie im folgenden Beispiel dargestellt services.AddApplicationInsightsTelemetryWorkerService(); der CreateHostBuilder()-Methode in Ihrer Program.cs-Klasse hinzu:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
                services.AddApplicationInsightsTelemetryWorkerService();
            });

Ändern Sie Ihre Datei Worker.cs wie im folgenden Beispiel:

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;

    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;
        private static HttpClient _httpClient = new HttpClient();

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

                using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
                {
                    _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                    _logger.LogInformation("Calling bing.com");
                    var res = await _httpClient.GetAsync("https://bing.com");
                    _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                    _telemetryClient.TrackEvent("Bing call event completed");
                }

                await Task.Delay(1000, stoppingToken);
            }
        }
    }

Richten Sie die Verbindungszeichenfolge ein.

Hinweis

Es wird empfohlen, die Verbindungszeichenfolge in der Konfiguration anzugeben. Im folgenden Beispielcode wird veranschaulicht, wie Sie in appsettings.json eine Verbindungszeichenfolge angeben. Stellen Sie sicher, dass appsettings.json während der Veröffentlichung in den Stammordner der Anwendung kopiert wird.
```
    {
        "ApplicationInsights":
        {
            "ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
        },
        "Logging":
        {
            "LogLevel":
            {
                "Default": "Warning"
            }
        }
    }
```

Konfigurieren Sie die Verbindungszeichenfolge in der APPLICATIONINSIGHTS_CONNECTION_STRING-Umgebungsvariable.

In der Regel wird mit APPLICATIONINSIGHTS_CONNECTION_STRING die Verbindungszeichenfolge für Anwendungen festgelegt, die in Web-Apps als Webaufträge bereitgestellt werden.

Hinweis

Eine im Code angegebene Verbindungszeichenfolge hat Vorrang vor der Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING, die Vorrang vor anderen Optionen hat.

ASP.NET Core-Hintergrundaufgaben mit gehosteten Diensten

In diesem Dokument wird das Erstellen von Hintergrundaufgaben in einer ASP.NET Core-Anwendung beschrieben.

Das vollständige Beispiel finden Sie auf dieser GitHub-Seite.

Installieren Sie das Paket Microsoft.ApplicationInsights.WorkerService für die Anwendung.

Fügen Sie wie im folgenden Beispiel dargestellt services.AddApplicationInsightsTelemetryWorkerService(); der ConfigureServices()-Methode hinzu:

    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .ConfigureAppConfiguration((hostContext, config) =>
            {
                config.AddJsonFile("appsettings.json", optional: true);
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddLogging();
                services.AddHostedService<TimedHostedService>();

                // connection string is read automatically from appsettings.json
                services.AddApplicationInsightsTelemetryWorkerService();
            })
            .UseConsoleLifetime()
            .Build();

        using (host)
        {
            // Start the host
            await host.StartAsync();

            // Wait for the host to shutdown
            await host.WaitForShutdownAsync();
        }
    }

Der folgende Code gilt für TimedHostedService, wo sich die Logik für die Hintergrundaufgabe befindet:

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;

    public class TimedHostedService : IHostedService, IDisposable
    {
        private readonly ILogger _logger;
        private Timer _timer;
        private TelemetryClient _telemetryClient;
        private static HttpClient httpClient = new HttpClient();

        public TimedHostedService(ILogger<TimedHostedService> logger, TelemetryClient tc)
        {
            _logger = logger;
            this._telemetryClient = tc;
        }

        public Task StartAsync(CancellationToken cancellationToken)
        {
            _logger.LogInformation("Timed Background Service is starting.");

            _timer = new Timer(DoWork, null, TimeSpan.Zero,
                TimeSpan.FromSeconds(1));

            return Task.CompletedTask;
        }

        private void DoWork(object state)
        {
            _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

            using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
            {
                _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                _logger.LogInformation("Calling bing.com");
                var res = httpClient.GetAsync("https://bing.com").GetAwaiter().GetResult();
                _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                _telemetryClient.TrackEvent("Bing call event completed");
            }
        }
    }

Richten Sie die Verbindungszeichenfolge ein. Verwenden Sie dieselbe Datei appsettings.json aus dem obigen Beispiel für den .NET-Workerdienst.

.NET Core-/.NET Framework-Konsolenanwendung

Wie am Anfang dieses Artikels erwähnt, kann das neue Paket verwendet werden, um Application Insights-Telemetrie sogar aus einer regulären Konsolenanwendung zu aktivieren. Dieses Paket ist für netstandard2.0 vorgesehen und kann daher für Konsolenanwendungen in .NET Core oder höher und .NET Framework oder höher verwendet werden.

Das vollständige Beispiel finden Sie auf dieser GitHub-Seite.

Installieren Sie das Paket Microsoft.ApplicationInsights.WorkerService für die Anwendung.

Ändern Sie die Datei Program.cs wie im folgenden Beispiel gezeigt:

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;
    using Microsoft.ApplicationInsights.WorkerService;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Logging;
    using System;
    using System.Net.Http;
    using System.Threading.Tasks;

    namespace WorkerSDKOnConsole
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                // Create the DI container.
                IServiceCollection services = new ServiceCollection();

                // Being a regular console app, there is no appsettings.json or configuration providers enabled by default.
                // Hence instrumentation key/ connection string and any changes to default logging level must be specified here.
                services.AddLogging(loggingBuilder => loggingBuilder.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("Category", LogLevel.Information));
                services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = "InstrumentationKey=<instrumentation key here>");

                // To pass a connection string
                // - aiserviceoptions must be created
                // - set connectionstring on it
                // - pass it to AddApplicationInsightsTelemetryWorkerService()

                // Build ServiceProvider.
                IServiceProvider serviceProvider = services.BuildServiceProvider();

                // Obtain logger instance from DI.
                ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

                // Obtain TelemetryClient instance from DI, for additional manual tracking or to flush.
                var telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

                var httpClient = new HttpClient();

                while (true) // This app runs indefinitely. Replace with actual application termination logic.
                {
                    logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

                    // Replace with a name which makes sense for this operation.
                    using (telemetryClient.StartOperation<RequestTelemetry>("operation"))
                    {
                        logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                        logger.LogInformation("Calling bing.com");                    
                        var res = await httpClient.GetAsync("https://bing.com");
                        logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                        telemetryClient.TrackEvent("Bing call event completed");
                    }

                    await Task.Delay(1000);
                }

                // Explicitly call Flush() followed by sleep is required in console apps.
                // This is to ensure that even if application terminates, telemetry is sent to the back-end.
                telemetryClient.Flush();
                Task.Delay(5000).Wait();
            }
        }
    }

Diese Konsolenanwendung verwendet ebenfalls die gleiche Standard-TelemetryConfiguration. Sie kann auf die gleiche Weise wie die Beispiele in früheren Abschnitten angepasst werden.

Ausführen der Anwendung

Führen Sie Ihre Anwendung aus. Die Worker aus allen vorherigen Beispielen führen jede Sekunde einen HTTP-Aufruf an bing.com durch und geben auch einige Protokolle mithilfe von ILogger aus. Diese Zeilen sind im StartOperation-Aufruf von TelemetryClient enthalten, der zum Erstellen eines Vorgangs verwendet wird. In diesem Beispiel ist dies RequestTelemetry mit dem Namen „operation“.

Application Insights sammelt diese ILogger-Protokolle mit dem Schweregrad Warnung oder höher standardmäßig und außerdem alle Abhängigkeiten. Sie werden in einer hierarchischen Beziehung mit RequestTelemetry korreliert. Die Korrelation kann auch prozessübergreifend und über Netzwerkgrenzen hinweg erfolgen. Wenn der Aufruf z. B. für eine andere überwachte Komponente erfolgt ist, wird sie ebenfalls mit dem übergeordneten Element korreliert.

Dieser benutzerdefinierte RequestTelemetry-Vorgang entspricht einer eingehenden Webanforderung in einer typischen Webanwendung. Es ist nicht erforderlich, einen Vorgang zu verwenden, dies entspricht aber am besten dem Application Insights-Korrelationsdatenmodell. RequestTelemetry fungiert als übergeordneter Vorgang, und alle in der Workeriteration generierten Telemetriedaten werden als logisch zu demselben Vorgang gehörend behandelt.

Mit diesem Ansatz wird auch sichergestellt, dass alle (automatisch und manuell) generierten Telemetriedaten dieselbe operation_id aufweisen. Da die Stichprobenentnahme auf der operation_id basiert, werden alle Telemetriedaten aus einer einzelnen Iteration entweder beibehalten oder gelöscht.

In den folgenden Abschnitten werden alle automatisch von Application Insights erfassten Telemetriedaten aufgeführt.

Livemetriken

Mit Livemetriken kann schnell überprüft werden, ob die Application Insights-Überwachung ordnungsgemäß konfiguriert ist. Es kann zwar einige Minuten dauern, bis Telemetriedaten im Portal und in der Analyse angezeigt werden. Livemetriken zeigen die CPU-Auslastung des laufenden Prozesses jedoch in Quasi-Echtzeit an. Außerdem können andere Telemetriedaten wie z. B. Anforderungen, Abhängigkeiten und Ablaufverfolgungen angezeigt werden.

ILogger-Protokolle

Protokolle, die über ILogger mit dem Schweregrad „Warnung“ oder höher ausgegeben wurden, werden automatisch erfasst. Um dieses Verhalten zu ändern, überschreiben Sie explizit die Protokollierungskonfiguration für den Anbieter ApplicationInsights, wie im Code unten gezeigt. Mit der folgenden Konfiguration kann Application Insights alle Protokolle mit dem Schweregrad Information und höher sammeln.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Beachten Sie unbedingt, dass das folgende Beispiel nicht dazu führt, dass der Application Insights-Anbieter Information-Protokolle sammelt. Sie werden nicht gesammelt, da das SDK einen Standardprotokollierungsfilter hinzufügt, der ApplicationInsights anweist, nur Protokolle mit dem Schweregrad Warning und höher zu sammeln. Application Insights erfordert eine explizite Überschreibung.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Weitere Informationen zur Anpassung der in Application Insights erfassten Protokollebenen finden Sie in der Dokumentation zu ILogger.

Abhängigkeiten

Die Abhängigkeitssammlung ist standardmäßig aktiviert. Im Artikel Abhängigkeitsnachverfolgung in Application Insights werden die Abhängigkeiten erläutert, die automatisch erfasst werden. Außerdem finden Sie dort Schritte zur manuellen Nachverfolgung.

EventCounter

EventCounterCollectionModule ist standardmäßig aktiviert und sammelt einen Standardsatz von Leistungsindikatoren von .NET-Apps. Im Tutorial zu EventCounter ist der Standardsatz der gesammelten Leistungsindikatoren aufgeführt. Er enthält auch Anweisungen zum Anpassen der Liste.

Manuelles Nachverfolgen anderer Telemetriedaten

Obwohl das SDK wie oben erläutert automatisch Telemetriedaten erfasst, müssen Sie in den meisten Fällen noch andere Telemetriedaten an Application Insights senden. Die empfohlene Methode zum Nachverfolgen zusätzlicher Telemetriedaten besteht darin, eine Instanz von TelemetryClient aus der Abhängigkeitsinjektion abzurufen und dann eine der unterstützten TrackXXX()API-Methoden in dieser aufzurufen. Ein weiterer typischer Anwendungsfall ist das benutzerdefinierte Nachverfolgen von Vorgängen. Diese Vorgehensweise wird in den obigen Workerbeispielen veranschaulicht.

Konfigurieren des Application Insights SDK

Die vom Workerdienst SDK verwendete Standard-TelemetryConfiguration ähnelt der automatischen Konfiguration in einer ASP.NET- oder ASP.NET Core-Anwendung, sie verfügt jedoch nicht über die Telemetrieinitialisierer, die zum Anreichern von Telemetriedaten aus HttpContext verwendet werden.

Sie können das Application Insights SDK für Workerdienstanwendungen anpassen, um die Standardkonfiguration zu ändern. Benutzer des ASP.NET Core SDK für Application Insights wissen möglicherweise, wie sie die Konfiguration mit der in ASP.NET Core integrierten Abhängigkeitsinjektion anpassen. Das Workerdienst SDK basiert auf ähnlichen Prinzipien. Führen Sie nahezu alle Änderungen im Abschnitt ConfigureServices() durch, indem Sie die entsprechenden Methoden in IServiceCollection aufrufen, wie im nächsten Abschnitt beschrieben.

Hinweis

Wenn Sie dieses SDK verwenden, wird das Ändern der Konfiguration durch Anpassen von TelemetryConfiguration.Active nicht unterstützt, und die Änderungen haben keine Auswirkungen.

Verwenden von ApplicationInsightsServiceOptions

Sie können wie im folgenden Beispiel einige allgemeine Einstellungen ändern, indem Sie der AddApplicationInsightsTelemetryWorkerService-Methode ApplicationInsightsServiceOptions übergeben:

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

Beachten Sie, dass sich ApplicationInsightsServiceOptions in diesem SDK im Namespace Microsoft.ApplicationInsights.WorkerService befindet, während es sich im ASP.NET Core SDK im Namespace Microsoft.ApplicationInsights.AspNetCore.Extensions befindet.

In der folgenden Tabelle werden häufig verwendete Einstellungen in ApplicationInsightsServiceOptions aufgelistet.

Einstellung	BESCHREIBUNG	Standard
EnableQuickPulseMetricStream	Aktivieren/Deaktivieren des Features für Livemetriken	Richtig
EnableAdaptiveSampling	Aktivieren/Deaktivieren der adaptiven Stichprobenerstellung	True
EnableHeartbeat	Aktivieren/Deaktivieren des Heartbeatfeatures, das in regelmäßigen Abständen (Standardwert: 15 Minuten) eine benutzerdefinierte Metrik namens „HeartBeatState“ mit Informationen zur Runtime wie .NET-Version und ggf. zur Azure-Umgebung sendet.	True
AddAutoCollectedMetricExtractor	Aktivieren/Deaktivieren des AutoCollectedMetrics-Extraktors, bei dem es sich um einen Telemetrieprozessor handelt, der vorab aggregierte Metriken zu Anforderungen/Abhängigkeiten sendet, bevor die Stichprobenerstellung erfolgt.	True
EnableDiagnosticsTelemetryModule	`DiagnosticsTelemetryModule` aktivieren/deaktivieren. Wenn Sie diese Einstellungen deaktivieren, werden die folgenden Einstellungen ignoriert: `EnableHeartbeat`, `EnableAzureInstanceMetadataTelemetryModule` und `EnableAppServicesHeartbeatTelemetryModule`.	True

Die aktuelle Liste finden Sie unter den konfigurierbaren Einstellungen in ApplicationInsightsServiceOptions.

Stichproben

Das Application Insights SDK für den Workerdienst unterstützt sowohl die feste als auch die adaptive Stichprobenerstellung. Die adaptive Stichprobenerstellung ist standardmäßig aktiviert. Die Stichprobenentnahme kann über die Option EnableAdaptiveSampling in ApplicationInsightsServiceOptions deaktiviert werden.

Anhand des folgenden Beispiels können Sie zusätzliche Einstellungen für die Stichprobenentnahme zu konfigurieren:

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetry(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Weitere Informationen finden Sie im Dokument zur Stichprobenentnahme.

Hinzufügen von Telemetrieinitialisierern

Mit Telemetrieinitialisierern legen Sie die Eigenschaften fest, die zusammen mit allen Telemetriedaten gesendet werden.

Fügen Sie neue Telemetrieinitialisierer im Container DependencyInjection hinzu, dann fügt das SDK sie automatisch der TelemetryConfiguration hinzu.

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

Entfernen von Telemetrieinitialisierern

Telemetrieinitialisierer sind standardmäßig vorhanden. Wenn Sie alle oder nur bestimmte Telemetrieinitialisierer entfernen möchten, können Sie den folgenden Beispielcode nach dem Aufrufen von AddApplicationInsightsTelemetryWorkerService() verwenden.

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

        // Remove all initializers.
        // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
        services.RemoveAll(typeof(ITelemetryInitializer));
   }

Hinzufügen Telemetrieprozessoren

Sie können TelemetryConfiguration benutzerdefinierte Telemetrieprozessoren hinzufügen, indem Sie die Erweiterungsmethode AddApplicationInsightsTelemetryProcessor in IServiceCollection verwenden. Mit Telemetrieprozessoren können Sie in komplexen Filterszenarien genauer steuern, welche Informationen in die Telemetriedaten, die an Application Insights gesendet werden, einbezogen oder daraus ausgeschlossen werden. Nehmen Sie das folgende Beispiel:

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();
        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
    }

Konfigurieren oder Entfernen von Standardtelemetriemodulen

Application Insights verwendet Telemetriemodule, um automatisch Telemetriedaten zu bestimmten Workloads zu erfassen, ohne dass eine manuelle Nachverfolgung erforderlich ist.

Die unten aufgeführten Module zur automatischen Erfassung sind standardmäßig aktiviert. Diese sind verantwortlich für die automatische Erfassung von Telemetriedaten. Sie können sie deaktivieren oder ihr Standardverhalten anpassen.

DependencyTrackingTelemetryModule
PerformanceCollectorModule
QuickPulseTelemetryModule
AppServicesHeartbeatTelemetryModule: (Derzeit liegt ein Problem mit diesem Telemetriemodul vor. Eine vorübergehende Problemumgehung finden Sie unter GitHub-Problem 1689.)
AzureInstanceMetadataTelemetryModule

Verwenden Sie zum Konfigurieren von Standardtelemetriemodulen die Erweiterungsmethode ConfigureTelemetryModule<T> in IServiceCollection, wie im folgenden Beispiel dargestellt:

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "keyhere";
            });

            // The following removes PerformanceCollectorModule to disable perf-counter collection.
            // Similarly, any other default modules can be removed.
            var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>
                                        (t => t.ImplementationType == typeof(PerformanceCollectorModule));
            if (performanceCounterService != null)
            {
                services.Remove(performanceCounterService);
            }
    }

Konfigurieren des Telemetriekanals

Der Standardkanal ist ServerTelemetryChannel. Sie können diesen wie im folgenden Beispiel dargestellt überschreiben:

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetryWorkerService();
    }

Dynamisches Deaktivieren von Telemetrie

Wenn Sie Telemetriedaten bedingt und dynamisch deaktivieren möchten, können Sie eine TelemetryConfiguration-Instanz mit einem ASP.NET Core-Abhängigkeitseinschleusungscontainer an einer beliebigen Stelle im Code auflösen und ein DisableTelemetry-Flag dafür festlegen.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

Häufig gestellte Fragen

Dieser Abschnitt enthält Antworten auf häufig gestellte Fragen.

Welches Paket sollte ich verwenden?

Szenario für .NET Core-Apps	Paket
Ohne HostedServices	WorkerService
Mit HostedServices	AspNetCore (nicht WorkerService)
Mit HostedServices, nur Überwachung von HostedServices	WorkerService (seltenes Szenario)

Kann in HostedServices in einer .NET Core-App mit dem AspNetCore-Paket TelemetryClient eingeschleust werden?

Ja. Die Konfiguration wird für den Rest der Webanwendung freigegeben.

Wie kann ich Telemetriedaten nachverfolgen, die nicht automatisch erfasst werden?

Rufen Sie eine Instanz von TelemetryClient ab. Verwenden Sie dazu die Konstruktorinjektion, und rufen Sie die erforderliche TrackXXX()-Methode auf. Es wird nicht empfohlen, neue TelemetryClient-Instanzen zu erstellen. Eine Singletoninstanz von TelemetryClient ist bereits im Container DependencyInjection registriert, der TelemetryConfiguration für alle sonstigen Telemetriedaten verwendet. Sie sollten nur dann eine neue TelemetryClient-Instanz erstellen, wenn für diese eine Konfiguration erforderlich ist, die sich von der für die sonstigen Telemetriedaten unterscheidet.

Kann ich die Visual Studio-IDE für das Onboarding von Application Insights in ein Workerdienstprojekt verwenden?

Das Onboarding mit der Visual Studio-IDE wird derzeit nur für ASP.NET-/ASP.NET Core-Anwendungen unterstützt. Dieses Dokument wird aktualisiert, wenn Visual Studio das Onboarding von Workerdienstanwendungen unterstützt.

Kann ich die Application Insights-Überwachung mithilfe von Tools wie Azure Monitor Application Insights-Agent (früher Statusmonitor v2) aktivieren?

Nein. Der Azure Monitor Application Insights-Agent unterstützt derzeit nur .NET.

Werden alle Features unterstützt, wenn ich meine Anwendung unter Linux ausführe?

Ja. Die Featureunterstützung für dieses SDK ist auf allen Plattformen gleich. Es gelten jedoch die folgenden Ausnahmen:

Leistungsindikatoren werden nur unter Windows unterstützt, mit Ausnahme der Anzeige von Prozess-CPU/Arbeitsspeicher in Live-Metriken.

Auch wenn ServerTelemetryChannel standardmäßig aktiviert ist, wird über den Kanal bei der Anwendungsausführung unter Linux oder macOS nicht automatisch ein lokaler Speicherordner erstellt, um die Telemetriedaten bei Netzwerkproblemen vorübergehend zu speichern. Aufgrund dieser Einschränkung gehen Telemetriedaten verloren, wenn vorübergehende Netzwerk- oder Serverprobleme auftreten. Sie können das Problem umgehen, indem Sie einen lokalen Ordner für den Kanal konfigurieren:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

    public void ConfigureServices(IServiceCollection services)
    {
        // The following will configure the channel to use the given folder to temporarily
        // store telemetry items during network or Application Insights server issues.
        // User should ensure that the given folder already exists
        // and that the application has read/write permissions.
        services.AddSingleton(typeof(ITelemetryChannel),
                                new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
        services.AddApplicationInsightsTelemetryWorkerService();
    }

Beispielanwendungen

.NET Core-Konsolenanwendung: Verwenden Sie dieses Beispiel, wenn Sie eine Konsolenanwendung verwenden, die in .NET Core (2.0 oder höher) oder .NET Framework (4.7.2 oder höher) geschrieben ist.

ASP.NET Core-Hintergrundaufgaben mit gehosteten Diensten: Verwenden Sie dieses Beispiel, wenn Sie in ASP.NET Core Hintergrundaufgaben gemäß dem offiziellen Leitfaden erstellen.

.NET Core-Workerdienst: Verwenden Sie dieses Beispiel, wenn Sie über eine .NET-Workerdienstanwendung gemäß dem offiziellen Leitfaden verfügen.

Open Source SDK

Lesen und Hinzufügen von Code.

Informationen zu den neuesten Updates und Fehlerbehebungen finden Sie in den Versionshinweisen.

Nächste Schritte

Verwenden Sie die API, um Ihre eigenen Ereignisse und Metriken für eine detaillierte Ansicht der Leistung und Nutzung Ihrer App zu senden.
Nachverfolgen zusätzlicher Abhängigkeiten, die nicht automatisch nachverfolgt werden
Anreichern oder Filtern automatisch erfasster Telemetriedaten
Dependency Injection in ASP.NET Core

Application Insights für Workerdienstanwendungen (Anwendungen ohne HTTP)

Unterstützte Szenarios

Voraussetzungen

Verwenden des Application Insights SDK für Workerdienste

.NET Core-Workerdienstanwendung

ASP.NET Core-Hintergrundaufgaben mit gehosteten Diensten

.NET Core-/.NET Framework-Konsolenanwendung

Ausführen der Anwendung

Livemetriken

ILogger-Protokolle

Abhängigkeiten

EventCounter

Manuelles Nachverfolgen anderer Telemetriedaten

Konfigurieren des Application Insights SDK

Verwenden von ApplicationInsightsServiceOptions

Stichproben

Hinzufügen von Telemetrieinitialisierern

Entfernen von Telemetrieinitialisierern

Hinzufügen Telemetrieprozessoren

Konfigurieren oder Entfernen von Standardtelemetriemodulen

Konfigurieren des Telemetriekanals

Dynamisches Deaktivieren von Telemetrie

Häufig gestellte Fragen

Welches Paket sollte ich verwenden?

Kann in HostedServices in einer .NET Core-App mit dem AspNetCore-Paket TelemetryClient eingeschleust werden?

Wie kann ich Telemetriedaten nachverfolgen, die nicht automatisch erfasst werden?

Kann ich die Visual Studio-IDE für das Onboarding von Application Insights in ein Workerdienstprojekt verwenden?

Kann ich die Application Insights-Überwachung mithilfe von Tools wie Azure Monitor Application Insights-Agent (früher Statusmonitor v2) aktivieren?

Werden alle Features unterstützt, wenn ich meine Anwendung unter Linux ausführe?

Beispielanwendungen

Open Source SDK

Nächste Schritte

Zusätzliche Ressourcen