Application Insights per le applicazioni del servizio Worker (applicazioni non HTTP)Application Insights for Worker Service applications (non-HTTP applications)

Application Insights sta rilasciando un nuovo SDK, denominato Microsoft.ApplicationInsights.WorkerService, ideale per carichi di lavoro non HTTP come la messaggistica, le attività in background, le applicazioni console e così via. Questi tipi di applicazioni non hanno la nozione di richiesta HTTP in ingresso come un'applicazione Web ASP.NET/ASP.NET Core tradizionale e pertanto l'uso di pacchetti di Application Insights per ASP.NET o le applicazioni ASP.NET Core non è supportato.Application Insights is releasing a new SDK, called Microsoft.ApplicationInsights.WorkerService, which is best suited for non-HTTP workloads like messaging, background tasks, console applications etc. These types of applications don't have the notion of an incoming HTTP request like a traditional ASP.NET/ASP.NET Core Web Application, and hence using Application Insights packages for ASP.NET or ASP.NET Core applications is not supported.

Il nuovo SDK non esegue alcuna raccolta di dati di telemetria.The new SDK does not do any telemetry collection by itself. Viene invece riportata in altri agenti di raccolta automatici Application Insights come DependencyCollector, PerfCounterCollector, ApplicationInsightsLoggingProvider e così via. Questo SDK espone i metodi di estensione su IServiceCollection per abilitare e configurare la raccolta di dati di telemetria.Instead, it brings in other well known Application Insights auto collectors like DependencyCollector, PerfCounterCollector, ApplicationInsightsLoggingProvider etc. This SDK exposes extension methods on IServiceCollection to enable and configure telemetry collection.

Scenari supportatiSupported scenarios

Il Application Insights SDK per il servizio Worker è ideale per le applicazioni non http, indipendentemente da dove o come vengono eseguite.The Application Insights SDK for Worker Service is best suited for non-HTTP applications no matter where or how they run. Se l'applicazione è in esecuzione e ha la connettività di rete ad Azure, è possibile raccogliere i dati di telemetria.If your application is running and has network connectivity to Azure, telemetry can be collected. Il monitoraggio Application Insights è supportato ovunque sia supportato .NET Core.Application Insights monitoring is supported everywhere .NET Core is supported. Questo pacchetto può essere usato nel servizio ruolo di lavoro .net core 3,0appena introdotto, attività in background in ASP.NET Core 2.1/2.2, app console (.NET Core/.NET Framework) e così via.This package can be used in the newly introduced .NET Core 3.0 Worker Service, background tasks in Asp.Net Core 2.1/2.2, Console apps (.NET Core/ .NET Framework), etc.

PrerequisitiPrerequisites

Chiave di strumentazione Application Insights valida.A valid Application Insights instrumentation key. Questa chiave è necessaria per inviare i dati di telemetria a Application Insights.This key is required to send any telemetry to Application Insights. Se è necessario creare una nuova risorsa Application Insights per ottenere una chiave di strumentazione, vedere creare una risorsa di Application Insights.If you need to create a new Application Insights resource to get an instrumentation key, see Create an Application Insights resource.

Uso di Application Insights SDK per i servizi del ruolo di lavoroUsing Application Insights SDK for Worker Services

  1. Installare il pacchetto Microsoft. ApplicationInsights. WorkerService nell'applicazione.Install the Microsoft.ApplicationInsights.WorkerService package to the application. Il frammento di codice seguente mostra le modifiche che devono essere aggiunte al file di .csproj del progetto.The following snippet shows the changes that need to be added to your project's .csproj file.
    <ItemGroup>
        <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.8.2" />
    </ItemGroup>
  1. Chiamare AddApplicationInsightsTelemetryWorkerService(string instrumentationKey) metodo di estensione su IServiceCollection, specificando la chiave di strumentazione.Call AddApplicationInsightsTelemetryWorkerService(string instrumentationKey) extension method on IServiceCollection, providing the instrumentation key. Questo metodo deve essere chiamato all'inizio dell'applicazione.This method should be called at the beginning of the application. Il percorso esatto dipende dal tipo di applicazione.The exact location depends on the type of application.

  2. Recuperare un'istanza di ILogger o un'istanza di TelemetryClient dal contenitore di inserimento delle dipendenze chiamando serviceProvider.GetRequiredService<TelemetryClient>(); o usando l'inserimento del costruttore.Retrieve an ILogger instance or TelemetryClient instance from the Dependency Injection (DI) container by calling serviceProvider.GetRequiredService<TelemetryClient>(); or using Constructor Injection. Questo passaggio attiverà la configurazione di TelemetryConfiguration e dei moduli di raccolta automatica.This step will trigger setting up of TelemetryConfiguration and auto collection modules.

Nelle sezioni seguenti vengono descritte le istruzioni specifiche per ogni tipo di applicazione.Specific instructions for each type of application is described in the following sections.

Applicazione del servizio ruolo di lavoro .NET Core 3,0.NET Core 3.0 worker service application

L'esempio completo è condiviso quiFull example is shared here

  1. Scaricare e installare .NET Core 3,0Download and install .NET Core 3.0

  2. Creare un nuovo progetto di servizio di lavoro usando il nuovo modello di progetto o la riga di comando di Visual Studio dotnet new workerCreate a new Worker Service project either by using Visual Studio new project template or command line dotnet new worker

  3. Installare il pacchetto Microsoft. ApplicationInsights. WorkerService nell'applicazione.Install the Microsoft.ApplicationInsights.WorkerService package to the application.

  4. Aggiungere services.AddApplicationInsightsTelemetryWorkerService(); al metodo CreateHostBuilder() nella classe Program.cs, come nell'esempio seguente:Add services.AddApplicationInsightsTelemetryWorkerService(); to the CreateHostBuilder() method in your Program.cs class, as in this example:

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
                services.AddApplicationInsightsTelemetryWorkerService();
            });
  1. Modificare il Worker.cs come nell'esempio riportato di seguito.Modify your Worker.cs as per below example.
    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);
            }
        }
    }
  1. Configurare la chiave di strumentazione.Set up the instrumentation key.

    Sebbene sia possibile fornire la chiave di strumentazione come argomento per AddApplicationInsightsTelemetryWorkerService, è consigliabile specificare la chiave di strumentazione nella configurazione.Although you can provide the instrumentation key as an argument to AddApplicationInsightsTelemetryWorkerService, we recommend that you specify the instrumentation key in configuration. Nell'esempio di codice seguente viene illustrato come specificare una chiave di strumentazione in appsettings.json.The following code sample shows how to specify an instrumentation key in appsettings.json. Assicurarsi che appsettings.json venga copiato nella cartella radice dell'applicazione durante la pubblicazione.Make sure appsettings.json is copied to the application root folder during publishing.

    {
        "ApplicationInsights":
            {
            "InstrumentationKey": "putinstrumentationkeyhere"
            },
        "Logging":
        {
            "LogLevel":
            {
                "Default": "Warning"
            }
        }
    }

In alternativa, specificare la chiave di strumentazione in una delle variabili di ambiente seguenti.Alternatively, specify the instrumentation key in either of the following environment variables. APPINSIGHTS_INSTRUMENTATIONKEY oppure ApplicationInsights:InstrumentationKeyAPPINSIGHTS_INSTRUMENTATIONKEY or ApplicationInsights:InstrumentationKey

Ad esempio: SET ApplicationInsights:InstrumentationKey=putinstrumentationkeyhereFor example: SET ApplicationInsights:InstrumentationKey=putinstrumentationkeyhere O SET APPINSIGHTS_INSTRUMENTATIONKEY=putinstrumentationkeyhereOR SET APPINSIGHTS_INSTRUMENTATIONKEY=putinstrumentationkeyhere

In genere, APPINSIGHTS_INSTRUMENTATIONKEY specifica la chiave di strumentazione per le applicazioni distribuite nelle app Web come processi Web.Typically, APPINSIGHTS_INSTRUMENTATIONKEY specifies the instrumentation key for applications deployed to Web Apps as Web Jobs.

Nota

Una chiave di strumentazione specificata nel codice prevale sulla variabile di ambiente APPINSIGHTS_INSTRUMENTATIONKEY, che prevale su altre opzioni.An instrumentation key specified in code wins over the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, which wins over other options.

ASP.NET Core attività in background con servizi ospitatiASP.NET Core background tasks with hosted services

In questo documento viene descritto come creare attività di background nell'applicazione ASP.NET Core 2.1/2.2.This document describes how to create backgrounds tasks in ASP.NET Core 2.1/2.2 application.

L'esempio completo è condiviso quiFull example is shared here

  1. Installare Microsoft. ApplicationInsights. WorkerService (https://www.nuget.org/packages/Microsoft.ApplicationInsights.WorkerService) pacchetto nell'applicazione.Install the Microsoft.ApplicationInsights.WorkerService(https://www.nuget.org/packages/Microsoft.ApplicationInsights.WorkerService) package to the application.
  2. Aggiungere services.AddApplicationInsightsTelemetryWorkerService(); al metodo ConfigureServices(), come nell'esempio seguente:Add services.AddApplicationInsightsTelemetryWorkerService(); to the ConfigureServices() method, as in this example:
    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>();

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

Di seguito è riportato il codice per TimedHostedService in cui risiede la logica dell'attività in background.Following is the code for TimedHostedService where the background task logic resides.

    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 = await httpClient.GetAsync("https://bing.com");
                _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                telemetryClient.TrackEvent("Bing call event completed");
            }
        }
    }
  1. Configurare la chiave di strumentazione.Set up the instrumentation key. Usare la stessa appsettings.json dall'esempio di servizio di lavoro .NET Core 3,0 precedente.Use the same appsettings.json from the .NET Core 3.0 Worker Service example above.

Applicazione console .NET Core/. NET Framework.NET Core/.NET Framework Console application

Come indicato all'inizio di questo articolo, è possibile usare il nuovo pacchetto per abilitare Application Insights Telemetry anche da un'applicazione console normale.As mentioned in the beginning of this article, the new package can be used to enable Application Insights Telemetry from even a regular console application. Questo pacchetto è destinato NetStandard2.0, quindi può essere usato per le app console in .net core 2,0 o versione successiva e .NET Framework 4.7.2 o versione successiva.This package targets NetStandard2.0, and hence can be used for console apps in .NET Core 2.0 or higher, and .NET Framework 4.7.2 or higher.

L'esempio completo è condiviso quiFull example is shared here

  1. Installare Microsoft. ApplicationInsights. WorkerService (https://www.nuget.org/packages/Microsoft.ApplicationInsights.WorkerService) pacchetto nell'applicazione.Install the Microsoft.ApplicationInsights.WorkerService(https://www.nuget.org/packages/Microsoft.ApplicationInsights.WorkerService) package to the application.

  2. Modificare Program.cs come riportato di seguito.Modify Program.cs as below example.

    using Microsoft.ApplicationInsights;
    using Microsoft.ApplicationInsights.DataContracts;
    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 must be specified here.
                services.AddApplicationInsightsTelemetryWorkerService("instrumentationkeyhere");

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

Questa applicazione console usa anche lo stesso TelemetryConfigurationpredefinito e può essere personalizzato nello stesso modo degli esempi nella sezione precedente.This console application also uses the same default TelemetryConfiguration, and it can be customized in the same way as the examples in earlier section.

Eseguire l'applicazioneRun your application

Eseguire l'applicazione.Run your application. I ruoli di lavoro di esempio di tutti gli esempi precedenti effettuano una chiamata http ogni secondo a bing.com e generano anche alcuni log con ILogger.The example workers from all of the above above makes an http call every second to bing.com, and also emits few logs using ILogger. Queste righe vengono incapsulate all'interno StartOperation chiamata di TelemetryClient, che viene usata per creare un'operazione (in questo esempio RequestTelemetry denominato "Operation").These lines are wrapped inside StartOperation call of TelemetryClient, which is used to create an operation (in this example RequestTelemetry named "operation"). Application Insights raccoglierà i log ILogger (avviso o superiore per impostazione predefinita) e le dipendenze, che verranno correlati al RequestTelemetry con la relazione padre-figlio.Application Insights will collect these ILogger logs (warning or above by default) and dependencies, and they will be correlated to the RequestTelemetry with parent-child relationship. La correlazione funziona anche tra processo/limite di rete.The correlation also works cross process/network boundary. Ad esempio, se la chiamata è stata effettuata a un altro componente monitorato, sarà correlato anche a questo elemento padre.For example, if the call was made to another monitored component, then it will be correlated to this parent as well.

Questa operazione personalizzata di RequestTelemetry può essere considerata come l'equivalente di una richiesta Web in ingresso in una tipica applicazione Web.This custom operation of RequestTelemetry can be thought of as the equivalent of an incoming web request in a typical Web Application. Sebbene non sia necessario usare un'operazione, si adatta al modello di dati di correlazione Application Insights , con RequestTelemetry che funge da operazione padre, e ogni telemetria generata all'interno dell'iterazione di lavoro viene considerata logicamente appartenente alla stessa operazione.While it is not necessary to use an Operation, it fits best with the Application Insights correlation data model - with RequestTelemetry acting as the parent operation, and every telemetry generated inside the worker iteration being treated as logically belonging to the same operation. Questo approccio assicura anche che tutti i dati di telemetria generati (automatici e manuali) avranno lo stesso operation_id.This approach also ensures all the telemetry generated (automatic and manual) will have the same operation_id. Poiché il campionamento è basato su operation_id, l'algoritmo di campionamento mantiene o Elimina tutti i dati di telemetria da un'unica iterazione.As sampling is based on operation_id, sampling algorithm either keeps or drops all of the telemetry from a single iteration.

Di seguito sono elencati i dati di telemetria completi raccolti automaticamente da Application Insights.The following lists the full telemetry automatically collected by Application Insights.

Metriche attiveLive Metrics

È possibile usare le metriche in tempo reale per verificare rapidamente se Application Insights il monitoraggio è configurato correttamente.Live Metrics can be used to quickly verify if Application Insights monitoring is configured correctly. Sebbene potrebbero essere necessari alcuni minuti prima che i dati di telemetria inizino a essere visualizzati nel portale e nelle analisi, le metriche attive indicheranno l'utilizzo della CPU del processo in esecuzione quasi in tempo reale.While it might take a few minutes before telemetry starts appearing in the portal and analytics, Live Metrics would show CPU usage of the running process in near real-time. Può anche visualizzare altri dati di telemetria, ad esempio richieste, dipendenze, tracce e così via.It can also show other telemetry like Requests, Dependencies, Traces etc.

Log ILoggerILogger logs

I log emessi tramite ILogger di gravità Warning o superiore vengono acquisiti automaticamente.Logs emitted via ILogger of severity Warning or greater are automatically captured. Seguire i documenti di ILogger per personalizzare i livelli di log acquisiti da Application Insights.Follow ILogger docs to customize which log levels are captured by Application Insights.

DipendenzeDependencies

La raccolta delle dipendenze è abilitata per impostazione predefinita.Dependency collection is enabled by default. Questo articolo illustra le dipendenze che vengono raccolte automaticamente e contiene anche i passaggi per eseguire il rilevamento manuale.This article explains the dependencies that are automatically collected, and also contain steps to do manual tracking.

EventCounterEventCounter

EventCounterCollectionModule è abilitato per impostazione predefinita e verrà raccolto un set predefinito di contatori dalle app .NET Core 3,0.EventCounterCollectionModule is enabled by default, and it will collect a default set of counters from .NET Core 3.0 apps. L'esercitazione EventCounter elenca il set predefinito di contatori raccolti.The EventCounter tutorial lists the default set of counters collected. Sono inoltre disponibili istruzioni per la personalizzazione dell'elenco.It also has instructions on customizing the list.

Rilevamento manuale di dati di telemetria aggiuntiviManually tracking additional telemetry

Mentre l'SDK raccoglie automaticamente i dati di telemetria come spiegato in precedenza, nella maggior parte dei casi l'utente dovrà inviare dati di telemetria aggiuntivi al servizio Application Insights.While the SDK automatically collects telemetry as explained above, in most cases user will need to send additional telemetry to Application Insights service. Il modo consigliato per tenere traccia dei dati di telemetria aggiuntivi consiste nel ottenere un'istanza di TelemetryClient dall'inserimento delle dipendenze e quindi chiamare uno dei metodi API TrackXXX() supportati.The recommended way to track additional telemetry is by obtaining an instance of TelemetryClient from Dependency Injection, and then calling one of the supported TrackXXX() API methods on it. Un altro caso d'uso tipico è il rilevamento personalizzato delle operazioni.Another typical use case is custom tracking of operations. Questo approccio viene illustrato negli esempi di lavoro precedenti.This approach is demonstrated in the Worker examples above.

Configurare il Application Insights SDKConfigure the Application Insights SDK

Il TelemetryConfiguration predefinito usato dall'SDK del servizio Worker è simile alla configurazione automatica usata in un'applicazione ASP.NET o ASP.NET Core, meno il TelemetryInitializers usato per arricchire i dati di telemetria da HttpContext.The default TelemetryConfiguration used by the worker service SDK is similar to the automatic configuration used in a ASP.NET or ASP.NET Core application, minus the TelemetryInitializers used to enrich telemetry from HttpContext.

Per modificare la configurazione predefinita, è possibile personalizzare il servizio Application Insights SDK per il ruolo di lavoro.You can customize the Application Insights SDK for Worker Service to change the default configuration. Gli utenti del Application Insights ASP.NET Core SDK potrebbero avere familiarità con la modifica della configurazione tramite ASP.NET Core inserimento di dipendenzepredefinito.Users of the Application Insights ASP.NET Core SDK might be familiar with changing configuration by using ASP.NET Core built-in dependency injection. WorkerService SDK si basa anche su principi simili.The WorkerService SDK is also based on similar principles. Apportare quasi tutte le modifiche alla configurazione nella sezione ConfigureServices() chiamando i metodi appropriati su IServiceCollection, come descritto di seguito.Make almost all configuration changes in the ConfigureServices() section by calling appropriate methods on IServiceCollection, as detailed below.

Nota

Quando si usa questo SDK, la modifica della configurazione modificando TelemetryConfiguration.Active non è supportata e le modifiche non vengono riflesse.While using this SDK, changing configuration by modifying TelemetryConfiguration.Active isn't supported, and changes will not be reflected.

Uso di ApplicationInsightsServiceOptionsUsing ApplicationInsightsServiceOptions

È possibile modificare alcune impostazioni comuni passando ApplicationInsightsServiceOptions al AddApplicationInsightsTelemetryWorkerService, come nell'esempio seguente:You can modify a few common settings by passing ApplicationInsightsServiceOptions to AddApplicationInsightsTelemetryWorkerService, as in this example:

    using Microsoft.ApplicationInsights.WorkerService;

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

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

Si noti che ApplicationInsightsServiceOptions in questo SDK si trova nello spazio dei nomi Microsoft.ApplicationInsights.WorkerService invece che Microsoft.ApplicationInsights.AspNetCore.Extensions in ASP.NET Core SDK.Note that ApplicationInsightsServiceOptions in this SDK is in the namespace Microsoft.ApplicationInsights.WorkerService as opposed to Microsoft.ApplicationInsights.AspNetCore.Extensions in the ASP.NET Core SDK.

Impostazioni utilizzate comunemente in ApplicationInsightsServiceOptionsCommonly used settings in ApplicationInsightsServiceOptions

ImpostazioneSetting DescriptionDescription PredefinitoDefault
EnableQuickPulseMetricStreamEnableQuickPulseMetricStream Abilita/Disabilita la funzionalità LiveMetricsEnable/Disable LiveMetrics feature truetrue
EnableAdaptiveSamplingEnableAdaptiveSampling Abilita/Disabilita il campionamento adattivoEnable/Disable Adaptive Sampling truetrue
EnableHeartbeatEnableHeartbeat Abilita/Disabilita la funzionalità heartbeat, che periodicamente (15 minuti per impostazione predefinita) Invia una metrica personalizzata denominata ' HeartBeatState ' con informazioni sul runtime come la versione .NET, le informazioni sull'ambiente di Azure, se applicabile e così via.Enable/Disable Heartbeats feature, which periodically (15-min default) sends a custom metric named 'HeartBeatState' with information about the runtime like .NET Version, Azure Environment information, if applicable, etc. truetrue
AddAutoCollectedMetricExtractorAddAutoCollectedMetricExtractor Abilita/Disabilita AutoCollectedMetrics Extractor, ovvero un TelemetryProcessor che invia metriche pre-aggregate relative a richieste/dipendenze prima che venga eseguita il campionamento.Enable/Disable AutoCollectedMetrics extractor, which is a TelemetryProcessor that sends pre-aggregated metrics about Requests/Dependencies before sampling takes place. truetrue

Per l'elenco più aggiornato, vedere le impostazioni configurabili in ApplicationInsightsServiceOptions .See the configurable settings in ApplicationInsightsServiceOptions for the most up-to-date list.

campionamentoSampling

Il Application Insights SDK per il servizio Worker supporta sia il campionamento a frequenza fissa che quello adattivo.The Application Insights SDK for Worker Service supports both fixed-rate and adaptive sampling. Il campionamento adattivo è abilitato per impostazione predefinita.Adaptive sampling is enabled by default. La configurazione del campionamento per il servizio worker viene eseguita nello stesso modo delle applicazioni ASP.NET Core.Configuring sampling for Worker Service is done the same way as for ASP.NET Core Applications.

Aggiunta di TelemetryInitializersAdding TelemetryInitializers

Usare gli inizializzatori di telemetria quando si desidera definire le proprietà che vengono inviate con tutti i dati di telemetria.Use telemetry initializers when you want to define properties that are sent with all telemetry.

Aggiungere nuovi TelemetryInitializer al contenitore di DependencyInjection e l'SDK li aggiungerà automaticamente al TelemetryConfiguration.Add any new TelemetryInitializer to the DependencyInjection container and SDK will automatically add them to the TelemetryConfiguration.

    using Microsoft.ApplicationInsights.Extensibility;

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

Rimozione di TelemetryInitializersRemoving TelemetryInitializers

Gli inizializzatori di telemetria sono presenti per impostazione predefinita.Telemetry initializers are present by default. Per rimuovere tutti gli inizializzatori di telemetria o specifici, usare il codice di esempio seguente dopo avere chiamato AddApplicationInsightsTelemetryWorkerService().To remove all or specific telemetry initializers, use the following sample code after you call AddApplicationInsightsTelemetryWorkerService().

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

Aggiunta di processori di telemetriaAdding telemetry processors

È possibile aggiungere processori di telemetria personalizzati a TelemetryConfiguration usando il metodo di estensione AddApplicationInsightsTelemetryProcessor in IServiceCollection.You can add custom telemetry processors to TelemetryConfiguration by using the extension method AddApplicationInsightsTelemetryProcessor on IServiceCollection. I processori di telemetria vengono usati in scenari di filtro avanzati per consentire un controllo più diretto sugli elementi inclusi o esclusi dai dati di telemetria inviati al servizio Application Insights.You use telemetry processors in advanced filtering scenarios to allow for more direct control over what's included or excluded from the telemetry you send to the Application Insights service. Usare l'esempio seguente.Use the following example.

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

Configurazione o rimozione di TelemetryModules predefinitiConfiguring or removing default TelemetryModules

Application Insights USA moduli di telemetria per raccogliere automaticamente i dati di telemetria relativi a carichi di lavoro specifici senza richiedere il rilevamento manuale.Application Insights uses telemetry modules to automatically collect telemetry about specific workloads without requiring manual tracking.

I moduli di raccolta automatica seguenti sono abilitati per impostazione predefinita.The following automatic-collection modules are enabled by default. Questi moduli sono responsabili della raccolta automatica dei dati di telemetria.These modules are responsible for automatically collecting telemetry. È possibile disabilitarle o configurarle per modificarne il comportamento predefinito.You can disable or configure them to alter their default behavior.

  • DependencyTrackingTelemetryModule
  • PerformanceCollectorModule
  • QuickPulseTelemetryModule
  • AppServicesHeartbeatTelemetryModule
  • AzureInstanceMetadataTelemetryModule

Per configurare qualsiasi TelemetryModulepredefinita, usare il metodo di estensione ConfigureTelemetryModule<T> su IServiceCollection, come illustrato nell'esempio seguente.To configure any default TelemetryModule, use the extension method ConfigureTelemetryModule<T> on IServiceCollection, as shown in the following example.

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

Configurazione del canale di telemetriaConfiguring telemetry channel

Il canale predefinito è ServerTelemetryChannel.The default channel is ServerTelemetryChannel. È possibile eseguirne l'override come illustrato nell'esempio riportato di seguito.You can override it as the following example shows.

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

Disabilitare la telemetria in modo dinamicoDisable telemetry dynamically

Se si vuole disabilitare la telemetria in modo condizionale e dinamico, è possibile risolvere TelemetryConfiguration istanza con ASP.NET Core contenitore di inserimento delle dipendenze in qualsiasi punto del codice e impostare DisableTelemetry flag.If you want to disable telemetry conditionally and dynamically, you may resolve TelemetryConfiguration instance with ASP.NET Core dependency injection container anywhere in your code and set DisableTelemetry flag on it.

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

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

Domande frequentiFrequently asked questions

Come è possibile tenere traccia dei dati di telemetria che non vengono raccolti automaticamente?How can I track telemetry that's not automatically collected?

Ottenere un'istanza di TelemetryClient usando l'inserimento del costruttore e chiamare il metodo TrackXXX() obbligatorio.Get an instance of TelemetryClient by using constructor injection, and call the required TrackXXX() method on it. Non è consigliabile creare nuove istanze di TelemetryClient.We don't recommend creating new TelemetryClient instances. Un'istanza singleton di TelemetryClient è già registrata nel contenitore DependencyInjection, che condivide TelemetryConfiguration con il resto dei dati di telemetria.A singleton instance of TelemetryClient is already registered in the DependencyInjection container, which shares TelemetryConfiguration with rest of the telemetry. La creazione di una nuova istanza di TelemetryClient è consigliata solo se è necessaria una configurazione separata dal resto dei dati di telemetria.Creating a new TelemetryClient instance is recommended only if it needs a configuration that's separate from the rest of the telemetry.

È possibile usare l'IDE di Visual Studio per caricare Application Insights in un progetto di servizio del ruolo di lavoro?Can I use Visual Studio IDE to onboard Application Insights to a Worker Service project?

Il caricamento dell'IDE di Visual Studio è attualmente supportato solo per le applicazioni ASP.NET/ASP.NET Core.Visual Studio IDE onboarding is currently supported only for ASP.NET/ASP.NET Core Applications. Questo documento verrà aggiornato quando Visual Studio fornisce il supporto per le applicazioni del servizio di lavoro di onboarding.This document will be updated when Visual Studio ships support for onboarding Worker service applications.

È possibile abilitare il monitoraggio Application Insights usando strumenti come Status Monitor?Can I enable Application Insights monitoring by using tools like Status Monitor?

No.No. Status Monitor e Status Monitor V2 attualmente supportano solo ASP.NET 4. x.Status Monitor and Status Monitor v2 currently support ASP.NET 4.x only.

Se eseguo l'applicazione in Linux, tutte le funzionalità sono supportate?If I run my application in Linux, are all features supported?

Sì.Yes. Il supporto delle funzionalità per questo SDK è lo stesso in tutte le piattaforme, con le eccezioni seguenti:Feature support for this SDK is the same in all platforms, with the following exceptions:

  • I contatori delle prestazioni sono supportati solo in Windows, ad eccezione della CPU/memoria del processo visualizzata in metriche attive.Performance counters are supported only in Windows with the exception of Process CPU/Memory shown in Live Metrics.
  • Anche se ServerTelemetryChannel è abilitato per impostazione predefinita, se l'applicazione è in esecuzione in Linux o MacOS, il canale non crea automaticamente una cartella di archiviazione locale per conservare temporaneamente la telemetria in caso di problemi di rete.Even though ServerTelemetryChannel is enabled by default, if the application is running in Linux or MacOS, the channel doesn't automatically create a local storage folder to keep telemetry temporarily if there are network issues. A causa di questa limitazione, i dati di telemetria vengono persi in caso di problemi di rete o del server temporanei.Because of this limitation, telemetry is lost when there are temporary network or server issues. Per risolvere questo problema, configurare una cartella locale per il canale:To work around this issue, configure a local folder for the channel:
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();
    }

Applicazioni di esempioSample applications

Applicazione console .NET Core Usare questo esempio se si usa un'applicazione console scritta in .NET Core (2,0 o versione successiva) o .NET Framework (4.7.2 o versione successiva).NET Core Console Application Use this sample if you are using a Console Application written in either .NET Core (2.0 or higher) or .NET Framework (4.7.2 or higher)

Attività in background ASP .NET Core con HostedServices Usare questo esempio se ci si trova in Asp.Net Core 2.1/2.2 e si creano attività in background in base alle linee guida ufficiali quiASP .NET Core background tasks with HostedServices Use this sample if you are in Asp.Net Core 2.1/2.2, and creating background tasks as per official guidance here

Servizio ruolo di lavoro .NET Core 3,0 Usare questo esempio se si dispone di un'applicazione di servizio di lavoro .NET Core 3,0 in base a una guida ufficiale qui.NET Core 3.0 Worker Service Use this sample if you have a .NET Core 3.0 Worker Service application as per official guidance here

SDK open sourceOpen-source SDK

Leggere e contribuire al codice.Read and contribute to the code.

Passaggi successiviNext steps