Monitorare .NET e applicazioni Node.js con Application Insights (API classica)

Annotazioni

Consultare le linee guida per il supporto di Application Insights SDK per la nostra politica di supporto SDK per le API classiche.

Attenzione

È consigliabile usare Azure Monitor OpenTelemetry Distro per consentire ai nuovi clienti o alle applicazioni di usare Azure Monitor Application Insights. La distribuzione Azure Monitor OpenTelemetry offre funzionalità ed esperienze simili come Application Insights SDK. È possibile eseguire la migrazione da Application Insights SDK usando le guide alla migrazione per .NET, Node.js e Python, ma stiamo ancora lavorando per aggiungere un few altre funzionalità per garantire la compatibilità con le versioni precedenti.

Questo articolo illustra come abilitare e configurare Application Insights per .NET (ASP.NET, ASP.NET Core e il servizio di lavoro) e Node.js applicazioni. Application Insights può raccogliere dalle app i dati di telemetria seguenti:

• Requests
• Dipendenze
• Exceptions
• Contatori delle prestazioni
• Tracce (registri)
• Battiti cardiaci
• Eventi e metriche personalizzati (richiede strumentazione manuale)
• Visualizzazioni pagina (richiede JavaScript SDK per le pagine Web)
• Test di disponibilità (richiede la configurazione manuale dei test di disponibilità)

Scenari supportati

.NET

Sostenuto	ASP.NET	ASP.NET Core	Servizio del ruolo di lavoro
Sistema operativo	Windows	Windows, Linux o macOS	Windows, Linux o macOS
Metodo di hosting	In-process (IIS o IIS Express)	Interno o esterno al processo	Console o servizio in background (viene eseguito come processo, in genere tramite dotnet cli o come daemon Windows Service/Linux)
Metodo di distribuzione	Web Deploy, MSI o copia manuale dei file	Dipendente dal framework o indipendente	Dipendente dal framework o indipendente
Server Web	Internet Information Services (IIS)	Internet Information Server (IIS) o Kestrel	Non applicabile (nessun server Web, progettato per carichi di lavoro non HTTP, ad esempio messaggistica, attività in background e app console)
Piattaforma di hosting	Servizio app di Azure (Windows), Macchine virtuali di Azure o server locali	Funzionalità Web Apps di Azure App Service, Azure Virtual Machines, Docker e Azure Kubernetes Service (AKS)	Azure Virtual Machines, servizio Azure Kubernetes, contenitori o qualsiasi ambiente in cui è supportato .NET Core
Versione .NET	.NET Framework 4.6.1 e versioni successive	Tutte le versioni di .NET supportate ufficialmente che non sono in anteprima	Tutte le versioni di .NET supportate ufficialmente che non sono in anteprima

Worker Service SDK non esegue alcuna raccolta di dati di telemetria da sola. ma viene fornito con alcuni dei più noti agenti di raccolta automatica di Application Insights, ad esempio DependencyCollector, PerfCounterCollector e ApplicationInsightsLoggingProvider. Questo SDK espone i metodi di estensione su per abilitare e configurare la raccolta di dati di telemetria.

Annotazioni

Un servizio di lavoro è un'applicazione in background a esecuzione prolungata che esegue attività all'esterno di una pipeline di richiesta/risposta HTTP. È possibile utilizzare l'SDK Application Insights per il servizio di lavoro nel nuovo Servizio di Lavoro di .NET Core, nei task in background in ASP.NET Core e nelle app console come .NET Core e .NET Framework.

Sostenuto	Node.js
Sistema operativo	Windows, Linux o macOS
Metodo di hosting	Console o servizio in background (viene eseguito come processo tramite script npm o comando node)
Metodo di distribuzione	Dipendente dal framework (richiede Node.js runtime installato tramite pacchetto npm)
Server Web	Modulo HTTP predefinito o framework Web (Express, Fastify e così via) o non applicabili per carichi di lavoro non HTTP
Piattaforma di hosting	Azure App Service, Azure Virtual Machines, servizio Azure Kubernetes, Docker, locale o qualsiasi ambiente in cui è supportato Node.js
Node.js versione	Tutte le versioni ufficialmente supportate Node.js LTS (attualmente 18.19.0+ o 20.6.0+ per SDK 3.X)

La libreria client Node.js può monitorare automaticamente le richieste HTTP in ingresso e in uscita, le eccezioni e alcune metriche di sistema. A partire dalla versione 0.20, la libreria client può anche monitorare alcuni pacchetti di terze parti comuni, ad esempio MongoDB, MySQL e Redis.

Tutti gli eventi relativi a una richiesta HTTP in ingresso vengono correlati per velocizzare la risoluzione dei problemi.

È possibile utilizzare l'API TelemetryClient per instrumentare e monitorare manualmente altri aspetti dell'app e del sistema. L'API TelemetryClient viene descritta in modo più dettagliato più avanti nell'articolo.

Aggiungere Application Insights

.NET

Contenuto della sezione

• Prerequisiti
• Instrumentare l'applicazione con Application Insights SDK
• Distribuire l'agente di Application Insights

Prerequisiti

• Sottoscrizione Azure. Se non ne hai già uno, crea un account Azure gratuito.
• Una risorsa basata sull'area di lavoro di Application Insights.
• Applicazione funzionante.

Instrumentare l'applicazione con Application Insights SDK

Questa sezione illustra come aggiungere Application Insights a un'app Web basata su modello.

ASP.NET

1. Aggiungere i pacchetti NuGet seguenti e le relative dipendenze al progetto:

   • Microsoft.ApplicationInsights.WindowsServer
   • Microsoft.ApplicationInsights.Web
   • Microsoft.AspNet.TelemetryCorrelation

2. In alcuni casi, il file ApplicationInsights.config viene creato automaticamente. Se il file è già presente, andare al passaggio 4.

   Crearlo manualmente se mancante. Nella directory radice di un'applicazione ASP.NET creare un nuovo file denominato ApplicationInsights.config.

3. Copiare la configurazione XML seguente nel file appena creato:

   
   Espandere per visualizzare la configurazione

   <?xml version="1.0" encoding="utf-8"?>
   <ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
     <TelemetryInitializers>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.HttpDependenciesParsingTelemetryInitializer, Microsoft.AI.DependencyCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureRoleEnvironmentTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.BuildInfoConfigComponentVersionTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.Web.WebTestTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SyntheticUserAgentTelemetryInitializer, Microsoft.AI.Web">
         <!-- Extended list of bots:
               search|spider|crawl|Bot|Monitor|BrowserMob|BingPreview|PagePeeker|WebThumb|URL2PNG|ZooShot|GomezA|Google SketchUp|Read Later|KTXN|KHTE|Keynote|Pingdom|AlwaysOn|zao|borg|oegp|silk|Xenu|zeal|NING|htdig|lycos|slurp|teoma|voila|yahoo|Sogou|CiBra|Nutch|Java|JNLP|Daumoa|Genieo|ichiro|larbin|pompos|Scrapy|snappy|speedy|vortex|favicon|indexer|Riddler|scooter|scraper|scrubby|WhatWeb|WinHTTP|voyager|archiver|Icarus6j|mogimogi|Netvibes|altavista|charlotte|findlinks|Retreiver|TLSProber|WordPress|wsr-agent|http client|Python-urllib|AppEngine-Google|semanticdiscovery|facebookexternalhit|web/snippet|Google-HTTP-Java-Client-->
         <Filters>search|spider|crawl|Bot|Monitor|AlwaysOn</Filters>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ClientIpHeaderTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AzureAppServiceRoleNameFromHostNameHeaderInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationNameTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationCorrelationTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.UserTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AuthenticatedUserIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AccountIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SessionTelemetryInitializer, Microsoft.AI.Web" />
     </TelemetryInitializers>
     <TelemetryModules>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
         <ExcludeComponentCorrelationHttpHeadersOnDomains>
           <!-- 
           Requests to the following hostnames will not be modified by adding correlation headers.
           Add entries here to exclude additional hostnames.
           NOTE: this configuration will be lost upon NuGet upgrade.
           -->
           <Add>core.windows.net</Add>
           <Add>core.chinacloudapi.cn</Add>
           <Add>core.cloudapi.de</Add>
           <Add>core.usgovcloudapi.net</Add>
         </ExcludeComponentCorrelationHttpHeadersOnDomains>
         <IncludeDiagnosticSourceActivities>
           <Add>Microsoft.Azure.EventHubs</Add>
           <Add>Azure.Messaging.ServiceBus</Add>
         </IncludeDiagnosticSourceActivities>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <!--
         Use the following syntax here to collect additional performance counters:
   
         <Counters>
           <Add PerformanceCounter="\Process(??APP_WIN32_PROC??)\Handle Count" ReportAs="Process handle count" />
           ...
         </Counters>
   
         PerformanceCounter must be either \CategoryName(InstanceName)\CounterName or \CategoryName\CounterName
   
         NOTE: performance counters configuration will be lost upon NuGet upgrade.
   
         The following placeholders are supported as InstanceName:
           ??APP_WIN32_PROC?? - instance name of the application process for Win32 counters.
           ??APP_W3SVC_PROC?? - instance name of the application IIS worker process for IIS/ASP.NET counters.
           ??APP_CLR_PROC?? - instance name of the application CLR process for .NET counters.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AppServicesHeartbeatTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureInstanceMetadataTelemetryModule, Microsoft.AI.WindowsServer">
         <!--
         Remove individual fields collected here by adding them to the ApplicationInsighs.HeartbeatProvider
         with the following syntax:
   
         <Add Type="Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule, Microsoft.ApplicationInsights">
           <ExcludedHeartbeatProperties>
             <Add>osType</Add>
             <Add>location</Add>
             <Add>name</Add>
             <Add>offer</Add>
             <Add>platformFaultDomain</Add>
             <Add>platformUpdateDomain</Add>
             <Add>publisher</Add>
             <Add>sku</Add>
             <Add>version</Add>
             <Add>vmId</Add>
             <Add>vmSize</Add>
             <Add>subscriptionId</Add>
             <Add>resourceGroupName</Add>
             <Add>placementGroupId</Add>
             <Add>tags</Add>
             <Add>vmScaleSetName</Add>
           </ExcludedHeartbeatProperties>
         </Add>
   
         NOTE: exclusions will be lost upon upgrade.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule, Microsoft.AI.WindowsServer">
         <!--</Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.FirstChanceExceptionStatisticsTelemetryModule, Microsoft.AI.WindowsServer">-->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web">
         <Handlers>
           <!-- 
           Add entries here to filter out additional handlers:
   
           NOTE: handler configuration will be lost upon NuGet upgrade.
           -->
           <Add>Microsoft.VisualStudio.Web.PageInspector.Runtime.Tracing.RequestDataHttpHandler</Add>
           <Add>System.Web.StaticFileHandler</Add>
           <Add>System.Web.Handlers.AssemblyResourceLoader</Add>
           <Add>System.Web.Optimization.BundleHandler</Add>
           <Add>System.Web.Script.Services.ScriptHandlerFactory</Add>
           <Add>System.Web.Handlers.TraceHandler</Add>
           <Add>System.Web.Services.Discovery.DiscoveryRequestHandler</Add>
           <Add>System.Web.HttpDebugHandler</Add>
         </Handlers>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AspNetDiagnosticTelemetryModule, Microsoft.AI.Web" />
     </TelemetryModules>
     <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
     <TelemetrySinks>
       <Add Name="default">
         <TelemetryProcessors>
           <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryProcessor, Microsoft.AI.PerfCounterCollector" />
           <Add Type="Microsoft.ApplicationInsights.Extensibility.AutocollectedMetricsExtractor, Microsoft.ApplicationInsights" />
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <ExcludedTypes>Event</ExcludedTypes>
           </Add>
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <IncludedTypes>Event</IncludedTypes>
           </Add>
           <!--
             Adjust the include and exclude examples to specify the desired semicolon-delimited types. (Dependency, Event, Exception, PageView, Request, Trace)
           -->
         </TelemetryProcessors>
         <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel" />
       </Add>
     </TelemetrySinks>
     <!-- 
       Learn more about Application Insights configuration with ApplicationInsights.config here:
       http://go.microsoft.com/fwlink/?LinkID=513840
     -->
     <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
   </ApplicationInsights>
   

4. Aggiungere la connection string, che può essere eseguita in due modi:

   • (scelta consigliata) Impostare il connection string nella configurazione.

     Prima del tag di chiusura </ApplicationInsights> in ApplicationInsights.config, è necessario aggiungere la stringa di connessione per la tua risorsa di Application Insights. È possibile trovare il connection string nel riquadro di panoramica della risorsa di Application Insights appena creata.

     <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
     

   • Impostare la stringa di connessione nel codice.

     Specificare un connection string nella classe program.cs.

     var configuration = new TelemetryConfiguration
     {
         ConnectionString = "Copy the connection string from your Application Insights resource"
     };
     

5. Allo stesso livello del progetto del file ApplicationInsights.config, creare una cartella denominata ErrorHandler con un nuovo file C# denominato AiHandleErrorAttribute.cs. Il contenuto del file sarà simile al seguente:

   using System;
   using System.Web.Mvc;
   using Microsoft.ApplicationInsights;
   
   namespace WebApplication10.ErrorHandler //namespace will vary based on your project name
   {
       [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)] 
       public class AiHandleErrorAttribute : HandleErrorAttribute
       {
           public override void OnException(ExceptionContext filterContext)
           {
               if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
               {
                   //If customError is Off, then AI HTTPModule will report the exception
                   if (filterContext.HttpContext.IsCustomErrorEnabled)
                   {   
                       var ai = new TelemetryClient();
                       ai.TrackException(filterContext.Exception);
                   } 
               }
               base.OnException(filterContext);
           }
       }
   }
   

6. Nella cartella App_Start aprire il file FilterConfig.cs e modificarlo in modo che corrisponda all'esempio:

   using System.Web;
   using System.Web.Mvc;
   
   namespace WebApplication10 //Namespace will vary based on project name
   {
       public class FilterConfig
       {
           public static void RegisterGlobalFilters(GlobalFilterCollection filters)
           {
               filters.Add(new ErrorHandler.AiHandleErrorAttribute());
           }
       }
   }
   

7. Se Web.config è già aggiornato, ignorare questo passaggio. In caso contrario, aggiornare il file come segue:

   
   Espandere per visualizzare la configurazione

   <?xml version="1.0" encoding="utf-8"?>
   <!--
     For more information on how to configure your ASP.NET application, please visit
     https://go.microsoft.com/fwlink/?LinkId=301880
     -->
   <configuration>
     <appSettings>
       <add key="webpages:Version" value="3.0.0.0" />
       <add key="webpages:Enabled" value="false" />
       <add key="ClientValidationEnabled" value="true" />
       <add key="UnobtrusiveJavaScriptEnabled" value="true" />
     </appSettings>
     <system.web>
       <compilation debug="true" targetFramework="4.7.2" />
       <httpRuntime targetFramework="4.7.2" />
       <!-- Code added for Application Insights start -->
       <httpModules>
         <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" />
         <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
       </httpModules>
       <!-- Code added for Application Insights end -->
     </system.web>
     <runtime>
       <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
         <dependentAssembly>
           <assemblyIdentity name="Antlr3.Runtime" publicKeyToken="eb42632606e9261f" />
           <bindingRedirect oldVersion="0.0.0.0-3.5.0.2" newVersion="3.5.0.2" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" />
           <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Optimization" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="1.1.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="0.0.0.0-1.6.5135.21930" newVersion="1.6.5135.21930" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-5.2.7.0" newVersion="5.2.7.0" />
         </dependentAssembly>
         <!-- Code added for Application Insights start -->
         <dependentAssembly>
           <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
           <bindingRedirect oldVersion="0.0.0.0-4.0.1.1" newVersion="4.0.1.1" />
         </dependentAssembly>
         <!-- Code added for Application Insights end -->
       </assemblyBinding>
     </runtime>
     <system.codedom>
       <compilers>
         <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:1659;1699;1701" />
         <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+" />
       </compilers>
     </system.codedom>
     <system.webServer>
       <validation validateIntegratedModeConfiguration="false" />
       <!-- Code added for Application Insights start -->
       <modules>
         <remove name="TelemetryCorrelationHttpModule" />
         <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" preCondition="managedHandler" />
         <remove name="ApplicationInsightsWebTracking" />
         <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
       </modules>
       <!-- Code added for Application Insights end -->
     </system.webServer>
   </configuration>
   

A questo punto, è stato configurato correttamente il monitoraggio delle applicazioni lato server. Se si esegue l'app Web, i dati di telemetria iniziano a comparire in Application Insights.

ASP.NET Core

1. Installare il pacchetto NuGet Application Insights SDK per ASP.NET Core.

   È consigliabile usare sempre la versione stabile più recente. Trova le note di rilascio complete per l'SDK nel repository open-source GitHub.

   L'esempio di codice seguente illustra le modifiche da aggiungere al file .csproj del progetto.

   <ItemGroup>
       <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
   </ItemGroup>
   

2. Aggiungere alla classe program.cs .

   Aggiungere dopo il metodo , come nell'esempio seguente:

   // This method gets called by the runtime. Use this method to add services to the container.
   var builder = WebApplication.CreateBuilder(args);
   
   // The following line enables Application Insights telemetry collection.
   builder.Services.AddApplicationInsightsTelemetry();
   
   // This code adds other services for your application.
   builder.Services.AddMvc();
   
   var app = builder.Build();
   

3. Aggiungere la connection string, che può essere eseguita in tre modi:

   • (scelta consigliata) Impostare il connection string nella configurazione.

     Impostare il connection string in appsettings.json e assicurarsi che il file di configurazione venga copiato nella cartella radice dell'applicazione durante la pubblicazione.

     {
         "Logging": {
             "LogLevel": {
                 "Default": "Information",
                 "Microsoft.AspNetCore": "Warning"
             }
         },
         "AllowedHosts": "*",
         "ApplicationInsights": {
             "ConnectionString": "<YOUR-CONNECTION-STRING>"
         }
     }
     

   • Impostare il connection string nella variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING o ApplicationInsights:ConnectionString nel file di configurazione JSON.

     Per esempio:

     • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
     • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     • In genere, viene usato nelle app Web. Può essere usata anche in tutte le posizioni in cui è supportato questo SDK.

     Annotazioni

     Un connection string specificato nel codice prevale sulla variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, che prevale su altre opzioni.

   • Imposta la stringa di connessione nel codice.

     Specificare una stringa di connessione come parte dell'argomento ApplicationInsightsServiceOptions a AddApplicationInsightsTelemetry nella classe program.cs.

Segreti utente e altri provider di configurazione

Se si desidera archiviare il connection string in ASP.NET Core segreti utente o recuperarlo da un altro provider di configurazione, è possibile usare l'overload con un parametro Microsoft.Extensions.Configuration.IConfiguration. Un parametro di esempio è .

In Microsoft.ApplicationInsights.AspNetCore versione 2.15.0 e versioni successive, la chiamata a services.AddApplicationInsightsTelemetry() legge automaticamente il connection string da Microsoft.Extensions.Configuration.IConfiguration dell'applicazione. Non è necessario specificare in modo esplicito .

Se ha caricato la configurazione da più provider, assegna priorità alla configurazione da appsettings.json, indipendentemente dall'ordine in cui vengono aggiunti i provider. Utilizzare il metodo per leggere la configurazione da senza questo trattamento preferenziale per appsettings.json.

Servizio del ruolo di lavoro

Contenuto della sezione

• Usare Application Insights SDK per il servizio del ruolo di lavoro
• Applicazione di tipo Worker Service di .NET Core
• Attività in background di ASP.NET Core con servizi ospitati
• Applicazione console di .NET Core/.NET Framework

Usare Application Insights SDK per il Worker Service

1. Installare il pacchetto Microsoft.ApplicationInsights.WorkerService nell'applicazione.

   Il frammento di codice seguente mostra le modifiche che devono essere aggiunte al file del progetto:

       <ItemGroup>
           <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
       </ItemGroup>
   

2. Configurare il connection string nella variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING o nella configurazione (appsettings.json).

   

3. Recuperare un'istanza di o di dal contenitore di inserimento delle dipendenze chiamando o utilizzando l'inserimento del costruttore. Questo passaggio attiva la configurazione di e dei moduli di raccolta automatica.

Le istruzioni specifiche per ogni tipo di applicazione sono descritte nelle sezioni seguenti.

Applicazione Worker Service .NET Core

L'esempio completo viene condiviso nel sito Web NuGet.

1. Scaricare e installare .NET SDK.

2. Creare un nuovo progetto Worker Service usando un nuovo modello di progetto di Visual Studio o la riga di comando dotnet new worker.

3. Aggiungere il pacchetto Microsoft.ApplicationInsights.WorkerService all'applicazione.

4. Aggiungere al metodo nella classe , come nell'esempio seguente:

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

5. Modifica il tuo secondo il seguente esempio:

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

6. Imposta la stringa di connessione.

   

   Annotazioni

   È consigliabile specificare il connection string nella configurazione. Nell'esempio di codice seguente viene illustrato come specificare un connection string in appsettings.json. Assicurati che venga copiato nella cartella radice dell'applicazione durante la pubblicazione.

       {
           "ApplicationInsights":
           {
               "ConnectionString" : "<YOUR-CONNECTION-STRING>"
           },
           "Logging":
           {
               "LogLevel":
               {
                   "Default": "Warning"
               }
           }
       }
   

In alternativa, specificare il connection string nella variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING.

In genere, APPLICATIONINSIGHTS_CONNECTION_STRING specifica la stringa di connessione per le applicazioni distribuite nelle applicazioni Web come WebJob.

Annotazioni

Un connection string specificato nel codice ha la precedenza sulla variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, che ha la precedenza su altre opzioni.

Attività in background di ASP.NET Core con servizi ospitati

Questo documento descrive come creare attività in background in un'applicazione ASP.NET Core.

L'esempio completo viene condiviso in questa pagina GitHub.

1. Installare il pacchetto Microsoft.ApplicationInsights.WorkerService nell'applicazione.

2. Aggiungere al metodo , come nell'esempio seguente:

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

   Il codice seguente è per , dove risiede la logica dell'attività in background:

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

3. Configura la stringa di connessione. Utilizzare lo stesso file appsettings.json dell'esempio del processo di lavoro dei servizi di .NET precedente.

Applicazione console di .NET Core/.NET Framework

Come accennato all'inizio di questo articolo, il nuovo pacchetto può essere usato per abilitare i dati di telemetria di Application Insights anche da una normale applicazione console. Questo pacchetto è destinato a netstandard2.0, quindi può essere usato per le app console su .NET Core o versione successiva e su .NET Framework o versione successiva.

L'esempio completo viene condiviso in questa pagina GitHub.

1. Installare il pacchetto Microsoft.ApplicationInsights.WorkerService nell'applicazione.

2. Modificare Program.cs come illustrato nell'esempio seguente:

       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 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 = "<YOUR-CONNECTION-STRING>");
   
                   // 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();
               }
           }
       }
   

Questa applicazione console usa anche lo stesso valore predefinito . Può essere personalizzato nello stesso modo degli esempi nelle sezioni precedenti.

Distribuire l'agente di Application Insights per i server locali

Contenuto della sezione

• Introduzione: per iniziare a usare esempi di codice concisi.
• Istruzioni dettagliate : per un approfondimento su come iniziare.
• Informazioni di riferimento sulle API : per informazioni di riferimento sulle API di PowerShell.

Application Insights Agent è un modulo di PowerShell pubblicato nel PowerShell Gallery. Sostituisce Status Monitor. I dati di telemetria vengono inviati al portale di Azure, dove è possibile monitorare l'app.

Per un elenco completo degli scenari di strumentazione automatica supportati, vedere Ambienti, linguaggi e provider di risorse supportati.

Annotazioni

Il modulo supporta attualmente la strumentazione senza codice di ASP.NET e ASP.NET Core app Web ospitate con Internet Information Server (IIS). Usare un SDK per instrumentare Java e Node.js applicazioni.

Annotazioni

Il monitoraggio lato client è abilitato per impostazione predefinita per le app ASP.NET Core. Se si vuole disabilitare il monitoraggio lato client, definire una variabile di ambiente nel server con le informazioni seguenti:

• Nome:
• Valore:

Come iniziare

Questa sezione contiene i comandi di avvio rapido previsti per la maggior parte degli ambienti. Le istruzioni dipendono da PowerShell Gallery per distribuire gli aggiornamenti. Questi comandi supportano il parametro di PowerShell.

Per una spiegazione di questi comandi, istruzioni per la personalizzazione e informazioni sulla risoluzione dei problemi, vedere le istruzioni dettagliate.

Se non si ha una sottoscrizione Azure, creare un account free prima di iniziare.

Opzione 1: Scaricare e installare Application Insights Agent tramite PowerShell Gallery

Annotazioni

Per i prerequisiti che potrebbero essere necessari, vedere PowerShell Gallery supporto TLS (Transport Layer Security.

1. Installare il modulo (esegui come amministratore):

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
   Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted
   Install-Module -Name PowerShellGet -Force
   

2. Installare Application Insights Agent (esegui come amministratore):

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   Install-Module -Name Az.ApplicationMonitor -AllowPrerelease -AcceptLicense
   

   Annotazioni

   L'opzione nel cmdlet consente l'installazione della versione beta.

   Per altre informazioni, vedere Install-Module.

3. Abilitare il monitoraggio:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'
   

Opzione 2: Scaricare e installare manualmente l'agente di Application Insights (opzione offline)

1. Scaricare manualmente la versione più recente del modulo da PowerShell Gallery.

2. Decomprimere e installare Application Insights Agent:

   $pathToNupkg = "C:\Users\t\Desktop\Az.ApplicationMonitor.0.3.0-alpha.nupkg"
   $pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
   $pathToNupkg | rename-item -newname $pathToZip
   $pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\Az.ApplicationMonitor"
   Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule
   

3. Abilitare il monitoraggio:

   Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'
   

Istruzioni dettagliate

Questa sezione descrive come eseguire l'onboarding nel PowerShell Gallery e scaricare il modulo ApplicationMonitor. Sono inclusi i parametri più comuni necessari per le attività iniziali. Forniamo anche istruzioni di download manuali nel caso in cui non si abbia accesso a Internet.

Eseguire PowerShell come amministratore con un criterio di esecuzione con privilegi elevati

Importante

PowerShell richiede autorizzazioni a livello di amministratore per apportare modifiche al computer.

Criteri di esecuzione

• Descrizione: per impostazione predefinita, l'esecuzione di script di PowerShell è disabilitata. È consigliabile consentire gli script RemoteSigned solo per l'ambito Corrente.
• Riferimento: Informazioni sui criteri di esecuzione e Set-ExecutionPolicy.
• Comando: .
• Parametro facoltativo:
  • . Evita la richiesta di conferma.

Esempi di errori

Install-Module : The 'Install-Module' command was found in the module 'PowerShellGet', but the module could not be
loaded. For more information, run 'Import-Module PowerShellGet'.

Import-Module : File C:\Program Files\WindowsPowerShell\Modules\PackageManagement\1.3.1\PackageManagement.psm1 cannot
be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.

Prerequisiti per PowerShell

Controllare l'istanza di PowerShell eseguendo il comando . Questo comando produce l'output seguente:

Name                           Value
----                           -----
PSVersion                      5.1.17763.316
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.17763.316
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Queste istruzioni sono state scritte e testate in un computer che esegue Windows 10 e le versioni seguenti.

Prerequisiti per PowerShell Gallery

Questi passaggi preparano il server per scaricare i moduli da PowerShell Gallery.

Annotazioni

PowerShell Gallery è supportato in Windows 10, Windows Server 2016 e PowerShell 6+. Per informazioni sulle versioni precedenti, vedere Installazione di PowerShellGet.

1. Esegui PowerShell come amministratore di sistema con criteri di esecuzione elevati.

2. Installare il provider di pacchetti NuGet.

   • Descrizione: questo provider deve interagire con i repository basati su NuGet, ad esempio PowerShell Gallery.
   • Riferimento: Install-PackageProvider.
   • Comando: .
   • Parametri facoltativi:
     • . Specifica un server proxy per la richiesta.
     • . Evita la richiesta di conferma.

   Questo prompt viene visualizzato se NuGet non è configurato:

   NuGet provider is required to continue
   PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories.
   The NuGet provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' or
   'C:\Users\t\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by running
   'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install and import
   the NuGet provider now?
   [Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):
   

3. Configurare PowerShell Gallery come repository affidabile.

   • Descrizione: per impostazione predefinita, PowerShell Gallery è un repository non attendibile.
   • Riferimento: Set-PSRepository.
   • Comando: .
   • Parametro facoltativo:
     • . Specifica un server proxy per la richiesta.

   Questo prompt viene visualizzato se PowerShell Gallery non è attendibile:

   Untrusted repository
   You are installing the modules from an untrusted repository.
   If you trust this repository, change its InstallationPolicy value
   by running the Set-PSRepository cmdlet. Are you sure you want to
   install the modules from 'PSGallery'?
   [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):
   

   È possibile confermare questa modifica e controllare tutti i eseguendo il comando .

4. Installare la versione più recente di PowerShellGet.

   • Descrizione: questo modulo contiene gli strumenti usati per ottenere altri moduli da PowerShell Gallery. La versione 1.0.0.1 viene fornita con Windows 10 e Windows Server. È richiesta la versione 1.6.0 o successiva. Per determinare la versione è installata nel computer, eseguire il comando .
   • Riferimento: Installazione di PowerShellGet.
   • Comando: .
   • Parametri facoltativi:
     • . Specifica un server proxy per la richiesta.
     • . Ignora l'avviso "già installato" e installa la versione più recente.

   Questo errore viene visualizzato se non si usa la versione più recente di PowerShellGet:

   Install-Module : A parameter cannot be found that matches parameter name 'AllowPrerelease'.
   At line:1 char:20
   Install-Module abc -AllowPrerelease
                  ~~~~~~~~~~~~~~~~
   CategoryInfo          : InvalidArgument: (:) [Install-Module], ParameterBindingException
   FullyQualifiedErrorId : NamedParameterNotFound,Install-Module
   

5. Riavviare PowerShell. Non è possibile caricare la nuova versione nella sessione corrente. Le nuove sessioni di PowerShell caricano la versione più recente di PowerShellGet.

Opzione 1: Scaricare e installare il modulo tramite PowerShell Gallery

Questi passaggi scaricano il modulo Az.ApplicationMonitor da PowerShell Gallery.

1. Assicurarsi che tutti i prerequisiti per PowerShell Gallery siano soddisfatti.
2. Esegui PowerShell come amministratore di sistema con criteri di esecuzione elevati.
3. Installare il modulo Az.ApplicationMonitor.
   • Riferimento: Install-Module.
   • Comando: .
   • Parametri facoltativi:
     • . Specifica un server proxy per la richiesta.
     • . Consente l'installazione di versioni alfa e beta.
     • . Ignora la richiesta "Accetta licenza"
     • . Ignora l'avviso "Repository non attendibile".

Opzione 2: Scaricare e installare il modulo manualmente (opzione offline)

Se per qualunque motivo non è possibile connettersi al modulo di PowerShell, è possibile scaricare e installare manualmente il modulo Az.ApplicationMonitor.

Scaricare manualmente il file nupkg più recente

1. Passare a .
2. Selezionare la versione più recente del file nella tabella Cronologia versioni.
3. In Opzioni di installazione, selezionare Download manuale.

Opzione 2.1: Installare in una directory dei moduli di PowerShell

Installare il modulo di PowerShell scaricato manualmente in una directory di PowerShell in modo che sia individuabile dalle sessioni di PowerShell. Per altre informazioni, vedere Installazione di un modulo di PowerShell.

Decomprimere nupkg come file ZIP usando Expand-Archive (v1.0.1.0)

• Descrizione: la versione di base di Microsoft.PowerShell.Archive (v1.0.1.0) non può decomprimere file nupkg. Rinominare il file con l'estensione .zip.

• Riferimento: Expand-Archive.

• Comando:

  $pathToNupkg = "C:\az.applicationmonitor.0.3.0-alpha.nupkg"
  $pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
  $pathToNupkg | rename-item -newname $pathToZip
  $pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
  Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule
  

Decomprimere nupkg usando Expand-Archive (v1.1.0.0)

• Descrizione: usare una versione corrente di Expand-Archive per decomprimere file nupkg senza modificare l'estensione.

• Riferimento: Expand-Archive e Microsoft.PowerShell.Archive.

• Comando:

  $pathToNupkg = "C:\az.applicationmonitor.0.2.1-alpha.nupkg"
  $pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
  Expand-Archive -LiteralPath $pathToNupkg -DestinationPath $pathInstalledModule
  

Opzione 2.2: Decomprimere e importare manualmente nupkg

Installare il modulo di PowerShell scaricato manualmente in una directory di PowerShell in modo che sia individuabile dalle sessioni di PowerShell. Per altre informazioni, vedere Installazione di un modulo di PowerShell.

Se si installa il modulo in qualunque altra directory, importare manualmente il modulo usando Import-Module.

Importante

Le librerie a collegamento dinamico (DLL) vengono installate tramite percorsi relativi. Archiviare il contenuto del pacchetto nella directory di runtime desiderata e accertarsi che le autorizzazioni di accesso consentano la lettura ma non la scrittura.

1. Modificare l'estensione in ".zip" ed estrarre il contenuto del pacchetto nella directory di installazione desiderata.
2. Trovare il percorso file di Az.ApplicationMonitor.psd1.
3. Esegui PowerShell come amministratore di sistema con criteri di esecuzione elevati.
4. Caricare il modulo usando il comando .

Instradare il traffico attraverso un proxy

Quando si monitora un computer in una rete intranet privata, è necessario instradare il traffico HTTP attraverso un proxy.

I comandi di PowerShell per scaricare e installare Az.ApplicationMonitor dal PowerShell Gallery supportano un parametro -Proxy. Esaminare le istruzioni precedenti quando si scrivono gli script di installazione.

L’SDK di Application Insights deve inviare dati di telemetria dell'app a Microsoft. È consigliabile configurare le impostazioni proxy per l'app nel file web.config. Per altre informazioni, vedere Come ottenere un pass-through proxy?.

Abilitare il monitoraggio

Usare il comando per abilitare il monitoraggio.

Per una descrizione dettagliata di come usare questo cmdlet, vedere il Riferimento API.

Informazioni di riferimento sulle API

Importante

• I cmdlet seguenti richiedono una sessione di PowerShell con autorizzazioni di amministratore e criteri di esecuzione elevati. Per altre informazioni, vedere Eseguire PowerShell come amministratore con un criterio di esecuzione con privilegi elevati.
• I cmdlet seguenti richiedono la revisione e l'accettazione della licenza e dell'informativa sulla privacy.
• Il motore di strumentazione aggiunge un sovraccarico maggiore ed è disattivato per impostazione predefinita.

Questa sezione descrive i cmdlet seguenti, che sono membri del modulo Az.ApplicationMonitor di PowerShell:

Annotazioni

Espandere una delle sezioni seguenti per altre informazioni, inclusi esempi, parametri e output.

Enable-InstrumentationEngine

Abilita il motore di strumentazione impostando alcune chiavi del registro. Riavviare IIS per applicare le modifiche apportate.

Il motore di strumentazione può integrare i dati raccolti dagli SDK (Software Development Kit) di .NET. Raccoglie eventi e messaggi che descrivono l'esecuzione di un processo gestito. Questi eventi e messaggi includono codici dei risultati delle dipendenze, verbi HTTP e il testo del comando SQL.

Abilitare il motore di strumentazione se:

• Il monitoraggio è già stato abilitato con il cmdlet ma non è stato abilitato il motore di strumentazione.
• L'app è stata instrumentata manualmente con gli SDK .NET e si vogliono raccogliere dati di telemetria aggiuntivi.

Esempi

Enable-InstrumentationEngine

Parametri

Parametro	Description
-AccettaLicenza	Optional. Usare questa opzione per accettare la licenza e l'informativa sulla privacy nelle installazioni headless.
-Verbose	Parametro comune. Usare questa opzione per restituire log dettagliati.

Risultato

Output di esempio dell'abilitazione corretta del motore di strumentazione:

Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...

Enable-ApplicationInsightsMonitoring

Abilita il monitoraggio del collegamento senza codice delle app IIS in un computer di destinazione.

Questo cmdlet modifica applicationHost.config di IIS e imposta alcune chiavi del registro. Crea un file applicationinsights.ikey.config, che definisce la chiave di strumentazione usata da ogni app. IIS all'avvio carica RedfieldModule, che inserisce l’SDK di Application Insights nelle applicazioni quando queste vengono avviate. Riavviare IIS per applicare le modifiche apportate.

Dopo aver abilitato il monitoraggio, è consigliabile usare Live Metrics per verificare rapidamente se l'app invia dati di telemetria.

Esempi

Esempio con una singola stringa di connessione

In questo esempio, tutte le app nel computer corrente sono dotate di una singola stringa di connessione.

Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'

Esempio con una singola chiave di strumentazione

In questo esempio viene fornita una singola chiave di strumentazione a tutte le app nel computer corrente.

Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Esempio con una mappa di chiavi di strumentazione

In questo esempio:

• corrisponde al computer corrente utilizzando il wildcard .
• fornisce un chiave di accesso agli strumenti . L’app specificata non è instrumentata.
• assegna all'app specificata una chiave di strumentazione univoca.
• assegna all'app specificata una chiave di strumentazione univoca.
• usa il carattere jolly per trovare la corrispondenza con qualunque app Web a cui non corrisponde ancora e assegna una chiave di strumentazione predefinita.
• Vengono aggiunti spazi per motivi di leggibilità.

Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
    ` @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
        ` @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
        ` @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
        ` @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})

• MachineFilter è un'espressione regolare C# necessaria del nome del computer o della macchina virtuale.
  • '.*' corrisponde a tutto
  • 'ComputerName' corrisponde solo ai computer con il nome esatto specificato.
• AppFilter è un'espressione regolare C# necessaria del nome del sito IIS. È possibile ottenere un elenco di siti nel server eseguendo il comando get-iissite.
  • '.*' corrisponde a tutto
  • 'SiteName' corrisponde solo al sito IIS con il nome esatto specificato.
• InstrumentationKey è necessario per abilitare il monitoraggio delle app che corrispondono ai due filtri precedenti.
  • Lasciare questo valore null se si desidera definire regole per escludere il monitoraggio.

Parametri

Parametro	Description
-EnableInstrumentationEngine	Optional. Usare questa opzione per consentire al motore di strumentazione di raccogliere eventi e messaggi relativi a ciò che accade durante l'esecuzione di un processo gestito. Questi eventi e messaggi includono codici dei risultati delle dipendenze, verbi HTTP e il testo del comando SQL. Il motore di strumentazione aggiunge un sovraccarico di risorse ed è disattivato di default.
-AccettaLicenza	Optional. Usare questa opzione per accettare la licenza e l'informativa sulla privacy nelle installazioni headless.
-IgnoreSharedConfig	Quando si dispone di un cluster di server Web, è possibile usare una configurazione condivisa. HttpModule non può essere inserito in questa configurazione condivisa. L’esito di questo script è negativo e viene visualizzato il messaggio indicante che sono necessari passaggi di installazione aggiuntivi. Usare questa opzione per ignorare questo controllo e continuare l’installazione dei prerequisiti. Per ulteriori informazioni, vedere conflitto noto con la configurazione condivisa di IIS
-Verbose	Parametro comune. Usare questa opzione per visualizzare log dettagliati.
-WhatIf	Parametro comune. Usare questa opzione per testare e convalidare i parametri di input senza abilitare effettivamente il monitoraggio.

Risultato

Esempio di output di un'abilitazione riuscita

Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Agent
Installing GAC module 'C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.0\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll'
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
Found GAC module Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.ManagedHttpModuleHelper, Microsoft.AppInsights.IIS.ManagedHttpModuleHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z_1'
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'enable'
Configuring IIS Environment for codeless attach...
Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...
Updating app pool permissions...
Successfully enabled Application Insights Agent

Disable-InstrumentationEngine

Disabilita il motore di strumentazione rimuovendo alcune chiavi del registro. Riavviare IIS per applicare le modifiche apportate.

Esempi

Disable-InstrumentationEngine

Parametri

Parametro	Description
-Verbose	Parametro comune. Usare questa opzione per restituire log dettagliati.

Risultato

Esempio di output della corretta disabilitazione del motore di strumentazione

Configuring IIS Environment for instrumentation engine...
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]'
Configuring registry for instrumentation engine...

Disable-ApplicationInsightsMonitoring

Disabilita il monitoraggio nel computer di destinazione. Questo cmdlet rimuove le modifiche all'applicationHost.config di IIS e rimuove le chiavi del registro.

Esempi

Disable-ApplicationInsightsMonitoring

Parametri

Parametro	Description
-Verbose	Parametro comune. Usare questa opzione per visualizzare log dettagliati.

Risultato

Esempio di output della corretta disabilitazione del monitoraggio

Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-00z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Agent

Get-ApplicationInsightsMonitoringConfig

Ottiene il file di configurazione e stampa i valori nella console.

Esempi

Get-ApplicationInsightsMonitoringConfig

Parametri

Non è necessario alcun parametro.

Risultato

Esempio di output della lettura del file di configurazione

RedfieldConfiguration:
Filters:
0)InstrumentationKey: AppFilter: WebAppExclude MachineFilter: .*
1)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2 AppFilter: WebAppTwo MachineFilter: .*
2)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault AppFilter: .* MachineFilter: .*

Get-ApplicationInsightsMonitoringStatus

Questo cmdlet fornisce informazioni sulla risoluzione dei problemi relativi ad Application Insights Agent. Usare questo cmdlet per analizzare lo stato del monitoraggio, la versione del modulo di PowerShell e per ispezionare il processo in esecuzione. Questo cmdlet riporta informazioni sulla versione e informazioni sui file chiave necessari per il monitoraggio.

Esempi

Esempio: Stato dell’applicazione

Eseguire il comando per visualizzare lo stato di monitoraggio dei siti Web.

Get-ApplicationInsightsMonitoringStatus

IIS Websites:

SiteName               : Default Web Site
ApplicationPoolName    : DefaultAppPool
SiteId                 : 1
SiteState              : Stopped

SiteName               : DemoWebApp111
ApplicationPoolName    : DemoWebApp111
SiteId                 : 2
SiteState              : Started
ProcessId              : not found

SiteName               : DemoWebApp222
ApplicationPoolName    : DemoWebApp222
SiteId                 : 3
SiteState              : Started
ProcessId              : 2024
Instrumented           : true
InstrumentationKey     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123

SiteName               : DemoWebApp333
ApplicationPoolName    : DemoWebApp333
SiteId                 : 4
SiteState              : Started
ProcessId              : 5184
AppAlreadyInstrumented : true

In questo esempio:

• Identificatore computer è un ID anonimo usato per identificare in modo univoco il server. Se si crea una richiesta di supporto, è necessario questo ID per trovare i log per il server.

• Sito Web predefinito è fermo in IIS

• IIS mostra DemoWebApp111 come avviato, ma l'app non riceve alcuna richiesta. Il report non mostra alcun processo in esecuzione (ProcessId: non trovato).

• DemoWebApp222 è in esecuzione ed è monitorato (Instrumentato: true). In base alla configurazione utente, la chiave di strumentazione xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123 è stata trovata per questo sito.

• DemoWebApp333 viene instrumentato manualmente con Application Insights SDK. Application Insights Agent rileva l'SDK e non monitora questo sito.

• La presenza di indica che l'agente di Application Insights ha identificato una DLL in conflitto caricata nell'applicazione web, assunto che l'app web sia strumentata manualmente e che l'agente si sia ritirato e non strumenti questo processo.

• indica che Application Insights Agent ha instrumentato correttamente l'app Web in esecuzione nel processo w3wp.exe specificato.

Esempio: Informazioni sul modulo di PowerShell

Eseguire il comando per visualizzare informazioni sul modulo corrente:

Get-ApplicationInsightsMonitoringStatus -PowerShellModule

PowerShell Module version:
0.4.0-alpha

Application Insights SDK version:
2.9.0.3872

Executing PowerShell Module Assembly:
Microsoft.ApplicationInsights.Redfield.Configurator.PowerShell, Version=2.8.14.11432, Culture=neutral, PublicKeyToken=31bf3856ad364e35

PowerShell Module Directory:
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.2\content\PowerShell

Runtime Paths:
ParentDirectory (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content

ConfigurationPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\applicationInsights.ikey.config

ManagedHttpModuleHelperPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll

RedfieldIISModulePath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll

InstrumentationEngine86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\MicrosoftInstrumentationEngine_x86.dll

InstrumentationEngine64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll

InstrumentationEngineExtensionHost86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.ApplicationInsights.ExtensionsHost_x86.dll

InstrumentationEngineExtensionHost64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll

InstrumentationEngineExtensionConfig86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.InstrumentationEngine.Extensions.config

InstrumentationEngineExtensionConfig64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.InstrumentationEngine.Extensions.config

ApplicationInsightsSdkPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

Esempio: Stato del runtime

È possibile ispezionare il processo nel computer instrumentato per verificare se tutte le DLL vengono caricate. Se il monitoraggio funziona, dovrebbero essere caricate almeno 12 DLL.

Eseguire il comando :

Get-ApplicationInsightsMonitoringStatus -InspectProcess

iisreset.exe /status
Status for IIS Admin Service ( IISADMIN ) : Running
Status for Windows Process Activation Service ( WAS ) : Running
Status for Net.Msmq Listener Adapter ( NetMsmqActivator ) : Running
Status for Net.Pipe Listener Adapter ( NetPipeActivator ) : Running
Status for Net.Tcp Listener Adapter ( NetTcpActivator ) : Running
Status for World Wide Web Publishing Service ( W3SVC ) : Running

handle64.exe -accepteula -p w3wp
BF0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.ServerTelemetryChannel.dll
C58: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.AzureAppServices.dll
C68: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.DependencyCollector.dll
C78: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.WindowsServer.dll
C98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Web.dll
CBC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.PerfCounterCollector.dll
DB0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Agent.Intercept.dll
B98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll
BB4: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.Contracts.dll
BCC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.Redfield.Lightup.dll
BE0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

listdlls64.exe -accepteula w3wp
0x0000000019ac0000  0x127000  C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll
0x00000000198b0000  0x4f000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll
0x000000000c460000  0xb2000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.Extensions.Base_x64.dll
0x000000000ad60000  0x108000  C:\Windows\TEMP\2.4.0.0.Microsoft.ApplicationInsights.Extensions.Intercept_x64.dll

Parametri

Per impostazione predefinita, questo cmdlet riporta lo stato di monitoraggio delle applicazioni Web. Usare questa opzione per verificare se l'applicazione è stata instrumentata correttamente. È anche possibile esaminare quale chiave di strumentazione è stata associata al sito.

Parametro	Description
-PowerShellModule	Facoltativo. Usare questa opzione per riportare i numeri di versione e i percorsi delle DLL necessarie per il monitoraggio. Usare questa opzione se è necessario identificare la versione di tutte le DLL, incluso l’SDK di Application Insights.
-InspectProcess	Facoltativo. Usare questa opzione per segnalare se IIS è in esecuzione. Scarica strumenti esterni per determinare se le DLL necessarie vengono caricate nel runtime di IIS. Se questo processo non riesce per un motivo qualunque, è possibile eseguire questi comandi manualmente: * iisreset.exe /status * \[handle64.exe\](/sysinternals/downloads/handle) -p w3wp \| findstr /I "InstrumentationEngine AI. ApplicationInsights" * \[listdlls64.exe\](/sysinternals/downloads/listdlls) w3wp \| findstr /I "InstrumentationEngine AI ApplicationInsights"
-Force	Facoltativo. Usato solo con InspectProcess. Usare questa opzione per ignorare la richiesta dell'utente visualizzata prima del download di altri strumenti.

Set-ApplicationInsightsMonitoringConfig

Imposta il file di configurazione senza eseguire una reinstallazione completa. Riavviare IIS per applicare le modifiche apportate.

Importante

Questo cmdlet richiede una sessione di PowerShell con autorizzazioni di amministratore.

Esempi

Esempio con una singola chiave di strumentazione

In questo esempio viene fornita una singola chiave di strumentazione a tutte le app nel computer corrente.

Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Esempio con una mappa di chiavi di strumentazione

In questo esempio:

• corrisponde al computer corrente utilizzando il wildcard .
• fornisce un chiave di accesso agli strumenti . L’app specificata non è instrumentata.
• assegna all'app specificata una chiave di strumentazione univoca.
• assegna all'app specificata una chiave di strumentazione univoca.
• usa il carattere jolly per trovare la corrispondenza con app Web a cui non corrisponde ancora e assegna una chiave di strumentazione predefinita.
• Vengono aggiunti spazi per motivi di leggibilità.

Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
    ` @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
      ` @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
      ` @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
      ` @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})

Parametri

Parametro	Description
-InstrumentationKey	Obbligatorio. Usare questo parametro per fornire una singola chiave di strumentazione da usare da tutte le app nel computer di destinazione.
-InstrumentationKeyMap	Obbligatorio. Usare questo parametro per fornire più chiavi di strumentazione e un mapping delle chiavi di strumentazione usate da ogni app.

È possibile creare un singolo script di installazione per diversi computer impostando .

Importante

Le app corrispondono alle regole nell'ordine specificato. Specificare prima le regole più specifiche e per ultime le regole più generiche.

Importante

InstrumentationKeyMap è una funzionalità di routing avanzata che esegue il mapping delle app Internet Information Services (IIS) nello stesso computer alle risorse di Application Insights. La funzionalità si applica alle app ASP.NET e ASP.NET Core ospitate in IIS che l'agente di Application Insights strumenta automaticamente.

Come funziona l'abbinamento

• La mappa definisce un elenco ordinato di regole denominate . La prima regola di abbinamento entra in vigore. Inserire prima le regole specifiche e terminare con una regola generale.
• Ogni regola può assegnare una risorsa di Application Insights diversa alle app corrispondenti. Preferire le stringhe di connessione negli scenari supportati poiché le chiavi di strumentazione sono obsolete.

Filtri disponibili

• o : espressione regolare C# che corrispondono al nome del computer o della macchina virtuale (VM). corrisponde a tutti i nomi.
• o : espressione regolare C# che corrisponde al nome del sito IIS (). Questo filtro è obbligatorio quando o non viene fornito.
• o : espressione regolare C# che corrisponde al percorso virtuale IIS (). Usare questo filtro per specificare come destinazione una singola app in un sito.

Mappatura della terminologia

• I cmdlet di PowerShell usano , e .
• L'estensione JSON delle macchine virtuali e dei set di scalabilità di macchine virtuali di Azure usa machineFilter, appFilter e virtualPathFilter e imposta la risorsa con instrumentationSettings.

Suggerimento

Includere una regola finale che corrisponda a tutte le app, ad esempio , e applicare una risorsa predefinita per rendere esplicito il comportamento.

Forma della mappa di questo cmdlet

• Specificare come matrice di tabelle hash di PowerShell.
• Per questo cmdlet, impostare la risorsa di destinazione per ogni regola con .
• Se si vuole una singola risorsa per tutte le app nel computer, usare invece o .

Start-ApplicationInsightsMonitoringTrace

Raccoglie gli eventi ETW (Event Tracing for Windows) generati dal runtime di collegamento senza codice. Usare questo cmdlet come alternativa più semplice all'esecuzione di PerfView.

Gli eventi vengono stampati nella console in tempo reale e vengono scritti anche in un file . È possibile aprire il file con PerfView per un'analisi più approfondita.

Questo cmdlet viene eseguito fino a quando non raggiunge il timeout, il valore predefinito è 5 minuti, o finché non lo si arresta manualmente con .

Esempi

Come raccogliere eventi

Usare questo flusso quando è necessario esaminare il motivo per cui un'app IIS non viene instrumentata.

Il runtime di collegamento senza codice genera eventi ETW all'avvio di IIS e all'avvio dell'app.

1. In un prompt dei comandi amministrativo eseguire per arrestare IIS e tutte le app Web.
2. Avviare la traccia eseguendo questo cmdlet.
3. In un prompt dei comandi amministrativo eseguire per avviare IIS.
4. Attivare l'avvio passando all'app.
5. Al termine del caricamento dell'app, premere per arrestare l'operazione o consentire il timeout per terminare la sessione.

Quali eventi raccogliere

È possibile scegliere le origini evento da includere:

1. raccoglie eventi da Application Insights SDK.
2. raccoglie gli eventi da Application Insights Agent e dal runtime di Redfield, che è utile per la diagnostica di avvio di IIS e dell'app.
3. Raccogliere entrambi i set specificando entrambe le opzioni.
4. Se non si specifica un'opzione, entrambi i set vengono raccolti per impostazione predefinita.

Parametri

Parametro	Description
-DurataMassimaInMinuti	Optional. Imposta la durata della raccolta prima del timeout. Il valore predefinito è 5 minuti.
-LogDirectory	Optional. Directory in cui deve essere scritto il file . Per impostazione predefinita, il file viene creato nella directory PowerShell del modulo. Il percorso completo viene visualizzato all'avvio della sessione.
-CollectSdkEvents	Optional. Includere gli eventi di Application Insights SDK.
-CollectRedfieldEvents	Optional. Includere gli eventi di Application Insights Agent e del runtime di Redfield.
-Verbose	Parametro comune. Restituisce log dettagliati.

Risultato

Esempio di log di avvio dell'applicazione

Start-ApplicationInsightsMonitoringTrace -CollectRedfieldEvents
Starting...
Log File: C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\logs\20190627_144217_ApplicationInsights_ETW_Trace.etl
Tracing enabled, waiting for events.
Tracing will timeout in 5 minutes. Press CTRL+C to cancel.
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftAppInsights_ManagedHttpModulePath='C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll', MicrosoftAppInsights_ManagedHttpModuleType='Microsoft.ApplicationInsights.RedfieldIISModule.RedfieldIISModule'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftDiagnosticServices_ManagedHttpModulePath2='', MicrosoftDiagnosticServices_ManagedHttpModuleType2=''
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Environment variable 'MicrosoftDiagnosticServices_ManagedHttpModulePath2' or 'MicrosoftDiagnosticServices_ManagedHttpModuleType2' is null, skipping managed dll loading

Distribuire l'agente di Application Insights per le macchine virtuali e i set di scalabilità di macchine virtuali

Contenuto della sezione

• Abilitare il monitoraggio per le macchine virtuali
• Abilita il monitoraggio dei set di scalabilità delle macchine virtuali

Abilitare il monitoraggio in Monitoraggio di AzureApplication Insights tramite autoinstrumentation per applicazioni ASP.NET e ASP.NET Core ospitate in Server di informazioni Internet (IIS) in Macchine virtuali di Azure e Set di scalabilità di macchine virtuali di Azure.

Distribuire l'agente di Application Insights con un'estensione per macchina virtuale. L'agente rileva automaticamente gli stessi segnali di dipendenza dell'SDK. Usare PowerShell per automatizzare le distribuzioni su larga scala.

Annotazioni

• Per le applicazioni Java, è possibile usare l'agente Java Application Insights 3.0, che autocolleziona le librerie, i framework, i log e le dipendenze più diffusi, insieme a molte altre configurazioni.
• Applicazioni Node.js e Python in esecuzione su macchine virtuali Azure e Azure Virtual Machine Scale Sets non supportano l'autostrumentazione. Usare invece la distribuzione Azure Monitor OpenTelemetry.
• Per monitorare i guest delle macchine virtuali oltre alle applicazioni ospitate, vedere dati guest della macchina virtuale.

Per un elenco completo degli scenari di strumentazione automatica supportati, vedere Ambienti, lingue e provider di risorse supportati.

Abilitare il monitoraggio per le macchine virtuali

È possibile usare il portale di Azure o PowerShell per abilitare il monitoraggio per le macchine virtuali.

Opzione 1: portale di Azure

1. Nel portale di Azure passare alla risorsa di Application Insights. Copiare la stringa di connessione negli Appunti.

   

2. Vai alla tua macchina virtuale. Nella sezione Impostazioni del menu a sinistra selezionare Estensioni e applicazioniAggiungi.

   Screenshot che mostra il riquadro Estensioni e applicazioni con il pulsante Aggiungi.

3. Selezionare Agente di Application InsightsAvanti.

   Screenshot che mostra il riquadro Installa un'estensione con il pulsante Avanti.

4. Incollare il connection string copiato nel passaggio 1 e selezionare Review + create.

   Screenshot che mostra la scheda Crea con il pulsante Rivedi e crea.

Opzione 2: PowerShell

Annotazioni

Novità di PowerShell? Vedere la Guida introduttiva.

Installare o aggiornare l'agente di Application Insights come estensione per Azure macchine virtuali:

# define variables to match your environment before running
$ResourceGroup = "<myVmResourceGroup>"
$VMName = "<myVmName>"
$Location = "<myVmLocation>"
$ConnectionString = "<myAppInsightsResourceConnectionString>"

$publicCfgJsonString = @"
{
    "redfieldConfiguration": {
        "instrumentationKeyMap": {
        "filters": [
            {
            "appFilter": ".*",
            "machineFilter": ".*",
            "virtualPathFilter": ".*",
            "instrumentationSettings" : {
                "connectionString": "$ConnectionString"
            }
            }
        ]
        }
    }
    }
"@

$privateCfgJsonString = '{}'
    
Set-AzVMExtension -ResourceGroupName $ResourceGroup -VMName $VMName -Location $Location -Name "ApplicationMonitoringWindows" -Publisher "Microsoft.Azure.Diagnostics" -Type "ApplicationMonitoringWindows" -Version "2.8" -SettingString $publicCfgJsonString -ProtectedSettingString $privateCfgJsonString

Annotazioni

Per distribuzioni più complesse su larga scala, è possibile usare un ciclo PowerShell per installare o aggiornare l'estensione dell'agente di Application Insights in più macchine virtuali.

Eseguire una query sullo stato dell'estensione dell'agente di Application Insights per le macchine virtuali di Azure.

Get-AzVMExtension -ResourceGroupName "<myVmResourceGroup>" -VMName "<myVmName>" -Name ApplicationMonitoringWindows -Status

Ottenere un elenco di estensioni installate per Azure macchine virtuali:

Get-AzResource -ResourceId "/subscriptions/<mySubscriptionId>/resourceGroups/<myVmResourceGroup>/providers/Microsoft.Compute/virtualMachines/<myVmName>/extensions"

Disinstallare l'estensione Application Insights Agent dalle macchine virtuali Azure:

Remove-AzVMExtension -ResourceGroupName "<myVmResourceGroup>" -VMName "<myVmName>" -Name "ApplicationMonitoring"

Annotazioni

Verificare l'installazione selezionando Live Metrics Stream all'interno della risorsa di Application Insights associata alla connection string usata per distribuire l'estensione dell'agente di Application Insights. Se si inviano dati da più macchine virtuali, selezionare le macchine virtuali di Azure in Nome Server. L'avvio del flusso dei dati potrebbe richiedere fino a un minuto.

instrumentationKeyMap (impostazioni dell'estensione)

Importante

InstrumentationKeyMap è una funzionalità di routing avanzata che esegue il mapping delle app Internet Information Services (IIS) nello stesso computer alle risorse di Application Insights. La funzionalità si applica alle app ASP.NET e ASP.NET Core ospitate in IIS, che l'agente di Application Insights strumenta automaticamente.

Come funziona l'abbinamento

• La mappa definisce un elenco ordinato di regole denominate . La prima regola di abbinamento entra in vigore. Inserire prima le regole specifiche e terminare con una regola generale.
• Ogni regola può assegnare una risorsa di Application Insights diversa alle app corrispondenti. Preferire le stringhe di connessione negli scenari supportati poiché le chiavi di strumentazione sono obsolete.

Filtri disponibili

• o : espressione regolare C# che corrispondono al nome del computer o della macchina virtuale (VM). corrisponde a tutti i nomi.
• o : espressione regolare C# che corrisponde al nome del sito IIS (). Questo filtro è obbligatorio quando o non viene fornito.
• o : espressione regolare C# che corrisponde al percorso virtuale IIS (). Usare questo filtro per specificare come destinazione una singola app in un sito.

Mappatura della terminologia

• I cmdlet di PowerShell usano , e .
• L'estensione JSON delle macchine virtuali e dei set di scalabilità di macchine virtuali di Azure usa machineFilter, appFilter e virtualPathFilter e imposta la risorsa con instrumentationSettings.

Suggerimento

Includere una regola finale che corrisponda a tutte le app, ad esempio , e applicare una risorsa predefinita per rendere esplicito il comportamento.

Dove va per l'estensione di macchine virtuali e set di scalabilità di macchine virtuali

Posizionare la mappa in redfieldConfiguration.instrumentationKeyMap.filters nelle impostazioni pubbliche dell'estensione (-SettingString per le macchine virtuali, -Setting per Virtual Machine Scale Sets). I nomi delle proprietà sono in camel case minuscolo. Imposta la risorsa di destinazione per ciascuna regola con .

{
  "redfieldConfiguration": {
    "instrumentationKeyMap": {
      "filters": [
        {
          "machineFilter": ".*",
          "appFilter": ".*",
          "instrumentationSettings": {
            "connectionString": "<your-APPLICATIONINSIGHTS_CONNECTION_STRING>"
          }
        }
      ]
    }
  }
}

Abilitare il monitoraggio per i set di scalabilità di macchine virtuali

È possibile usare il portale di Azure o PowerShell per abilitare il monitoraggio per i set di scalabilità di macchine virtuali.

Opzione 1: portale di Azure

Seguire i passaggi precedenti per le macchine virtuali, ma passare ai set di scalabilità di macchine virtuali anziché alla macchina virtuale.

Opzione 2: PowerShell

Installare o aggiornare Application Insights Agent come estensione per i set di scalabilità di macchine virtuali:

# Set resource group, vmss name, and connection string to reflect your environment
$ResourceGroup = "<myVmResourceGroup>"
$VMSSName = "<myVmName>"
$ConnectionString = "<myAppInsightsResourceConnectionString>"
$publicCfgHashtable =
@{
  "redfieldConfiguration"= @{
    "instrumentationKeyMap"= @{
      "filters"= @(
        @{
          "appFilter"= ".*";
          "machineFilter"= ".*";
          "virtualPathFilter"= ".*";
          "instrumentationSettings" = @{
            "connectionString"= "$ConnectionString"
          }
        }
      )
    }
  }
};
$privateCfgHashtable = @{};
$vmss = Get-AzVmss -ResourceGroupName $ResourceGroup -VMScaleSetName $VMSSName
Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ApplicationMonitoringWindows" -Publisher "Microsoft.Azure.Diagnostics" -Type "ApplicationMonitoringWindows" -TypeHandlerVersion "2.8" -Setting $publicCfgHashtable -ProtectedSetting $privateCfgHashtable
Update-AzVmss -ResourceGroupName $vmss.ResourceGroupName -Name $vmss
# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance

Ottenere un elenco di estensioni installate per i set di scalabilità di macchine virtuali:

Get-AzResource -ResourceId "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.Compute/virtualMachineScaleSets/<myVmssName>/extensions"

Disinstallare l'estensione di monitoraggio delle applicazioni dai set di scalabilità di macchine virtuali:

# set resource group and vmss name to reflect your environment
$vmss = Get-AzVmss -ResourceGroupName "<myResourceGroup>" -VMScaleSetName "<myVmssName>"
Remove-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ApplicationMonitoringWindows"
Update-AzVmss -ResourceGroupName $vmss.ResourceGroupName -Name $vmss.Name -VirtualMachineScaleSet $vmss
# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance

Risoluzione dei problemi

Per la procedura di risoluzione dei problemi dedicata, vedere Problemi di distribuzione dell'estensione dell'agente di monitoraggio di Application Insights per macchine virtuali e set di scalabilità di macchine virtuali.

Prerequisiti

• Sottoscrizione Azure. Se non ne hai già uno, crea un account Azure gratuito.
• Una risorsa basata sull'area di lavoro di Application Insights.
• Applicazione funzionante.

Configurare la libreria client Node.js

Includere l'SDK nell'app affinché possa raccogliere i dati.

1. Copia la stringa di connessione dalla tua nuova risorsa. Application Insights usa il connection string per eseguire il mapping dei dati alla risorsa Azure. Prima che l'SDK possa usare il connection string, è necessario specificare il connection string in una variabile di ambiente o nel codice.

   

2. Aggiungi la libreria client Node.js alle dipendenze dell'applicazione tramite . Dalla cartella radice dell'app eseguire:

   npm install applicationinsights --save
   

   Annotazioni

   Se stai utilizzando TypeScript, non installare pacchetti "typings" separati. Questo pacchetto NPM contiene scritture predefinite.

3. Carica esplicitamente la libreria nel tuo codice. Dato che l'SDK inserisce la strumentazione in molte altre librerie, caricare la libreria il prima possibile, anche prima di altre istruzioni .

   let appInsights = require('applicationinsights');
   

4. È anche possibile fornire un connection string tramite la variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, anziché passarla manualmente a setup() o new appInsights.TelemetryClient(). Questa procedura consente di mantenere le stringhe di connessione fuori dal codice sorgente sottoposto a commit ed è possibile specificare stringhe di connessione diverse per ambienti diversi. Per configurare manualmente, chiamare appInsights.setup('[your connection string]');.

   Per altre opzioni di configurazione, vedere le sezioni riportate di seguito.

   È possibile provare l'SDK senza inviare i dati di telemetria impostando .

5. Iniziare automaticamente a raccogliere e inviare i dati chiamando .

Annotazioni

Nell'ambito dell'uso della strumentazione di Application Insights, vengono raccolti e inviati dati di diagnostica a Microsoft. Questi dati consentono di eseguire e migliorare Application Insights. È possibile disabilitare la raccolta di dati non essenziali. Altre informazioni sono disponibili nelle domande frequenti su Application Insights.

Utilizzo di base

Per la raccolta predefinita di richieste HTTP, eventi più richiesti della libreria di terze parti, eccezioni non gestite e metriche di sistema:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Annotazioni

Se il connection string è impostato nella variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, è possibile chiamare .setup() senza argomenti. In questo modo è facile usare stringhe di connessione diverse per ambienti diversi.

Caricare il prima possibile la libreria di Application Insights negli script prima di caricare altri pacchetti. Questo passaggio è necessario affinché la libreria di Application Insights possa preparare i pacchetti successivi per il rilevamento. Se si verificano conflitti con altre librerie che eseguono operazioni di preparazione simili, provare a caricare la libreria di Application Insights in un secondo momento.

A causa del modo in cui JavaScript gestisce i callback, è richiesto più lavoro per tenere traccia di una richiesta tra dipendenze esterne e i callback successivi. Per impostazione predefinita, questo rilevamento aggiuntivo è abilitato. Disabilitarla chiamando come descritto nella sezione Configurazione dell'SDK.

Eseguire la migrazione dalle versioni precedenti alla versione 0.22

Sono state apportate modifiche significative se si confrontano le versioni precedenti alla versione 0.22 e quelle successive. Tali modifiche sono progettate per garantire coerenza con altri SDK di Application Insights e consentire un'estendibilità futura.

In generale, è possibile eseguire la migrazione effettuando le azioni seguenti:

• Sostituire i riferimenti a con .
• Sostituire i riferimenti a con .
• Sostituire tutti gli argomenti per i metodi client.track* con un singolo oggetto contenente proprietà denominate come argomenti. Per ogni tipo di dati di telemetria, vedere hint del tipo IDE predefinito o TelemetryTypes per l'oggetto escluso per ciascun tipo di dati di telemetria.

Se si accede alle funzioni di configurazione dell'SDK senza concatenarle a , è possibile trovare queste funzioni in . Un esempio è . Esaminare le modifiche apportate alla configurazione predefinita nella sezione successiva.

Verificare che Application Insights riceva i dati di telemetria

.NET

ASP.NET e ASP.NET Core

Eseguire l'applicazione ed effettuare richieste. I dati di telemetria dovrebbero ora fluire in Application Insights. Application Insights SDK raccoglie automaticamente le richieste Web in ingresso all'applicazione, insieme ai dati di telemetria seguenti.

Servizio del ruolo di lavoro

Esegui la tua applicazione. I lavoratori di tutti gli esempi precedenti effettuano una chiamata HTTP ogni secondo a bing.com e generano anche alcuni log usando . Queste righe vengono racchiuse all'interno della chiamata di , che viene usata per creare un'operazione. In questo esempio, è chiamato "operazione".

Application Insights raccoglie i log ILogger con un livello di gravità Avviso o superiore (impostazione predefinita), con le relative dipendenze. Sono correlati a in una relazione padre-figlio. La correlazione funziona anche tra i limiti di processo/rete. Ad esempio, se la chiamata è stata effettuata a un altro componente monitorato, è correlata anche a questo elemento padre.

Questa operazione personalizzata di può essere considerata come l'equivalente di una richiesta Web in ingresso in un'applicazione Web tipica. Non è necessario usare un'operazione, ma si adatta meglio al modello di dati di correlazione di Application Insights. svolge la funzione di operazione padre e ogni informazione di telemetria generata all'interno dell'iterazione del ruolo di lavoro viene considerata logicamente appartenente alla stessa operazione.

Questo approccio garantisce inoltre che i dati di telemetria generati, sia automatici che manuali, dispongano dello stesso . Poiché il campionamento è basato su , l'algoritmo di campionamento mantiene o elimina tutti i dati di telemetria da una singola iterazione.

L'SDK raccoglie automaticamente i dati di telemetria sul runtime Node.js e su alcuni moduli di terze parti comuni. Usare l'applicazione per generare alcuni di questi dati.

Quindi, nel portale Azure passare alla risorsa di Application Insights creata in precedenza. In Panoramica sequenza temporale cercare i primi punti dati. Per visualizzare altri dati dettagliati, selezionare diversi componenti nei grafici.

Per visualizzare la topologia individuata per l'app, è possibile usare Mappa delle applicazioni.

Nessun dato

Dato che l'SDK esegue l'invio dei dati in batch, potrebbe verificarsi un ritardo nella visualizzazione degli elementi nel portale. Se i dati non sono visibili nella risorsa, provare alcune delle correzioni seguenti:

• Continuare a usare l'applicazione. Eseguire altre azioni per generare dati di telemetria aggiuntivi.
• Fare clic su Aggiorna nella visualizzazione risorse nel portale. I grafici si aggiornano periodicamente in automatico, ma l'aggiornamento manuale ha effetto immediato.
• Verificare che le porte in uscita necessarie siano aperte.
• Usare l'opzione Cerca per cercare eventi specifici.
• Vedere le domande frequenti.

Raccolta di dati di telemetria

.NET

Contenuto della sezione

• Metriche in tempo reale
• Tracce (log)
• Traccia distribuita
• Dipendenze
• Exceptions
• Metriche personalizzate
• Operazioni personalizzate
• Contatori
• Raccolta di snapshot

Metriche in tempo reale

È possibile usare le metriche attive per verificare rapidamente se il monitoraggio delle applicazioni con Application Insights è configurato correttamente. La visualizzazione dei dati di telemetria può richiedere alcuni minuti nel portale di Azure, ma il riquadro delle metriche attive mostra l'utilizzo della CPU del processo in esecuzione quasi in tempo reale. Può anche visualizzare altri dati di telemetria, ad esempio richieste, dipendenze e tracce.

Annotazioni

Le metriche live sono abilitate per impostazione predefinita al momento dell'onboarding usando le istruzioni consigliate per le applicazioni .NET.

Get started

1. Abilitare le metriche attive con gli SDK di Application Insights seguendo le linee guida specifiche del linguaggio:

   • ASP.NET: abilitata per impostazione predefinita, ma può anche essere abilitata manualmente usando il codice.
   • ASP.NET Core: abilitata per impostazione predefinita, ma può anche essere abilitata manualmente usando il codice.
   • .NET/.NET Core Console/Worker: abilitato per impostazione predefinita.

2. Aprire la risorsa di Application Insights per l'applicazione nel portale Azure. Selezionare Live Metrics disponibile in Analisi dei problemi nel menu a sinistra.

3. Secure the control channel abilitando Microsoft Entra authentication se si usano filtri personalizzati.

Funzionalità supportate

Language	Metriche di base	Metriche delle prestazioni	Filtro personalizzato	Telemetria di esempio	Suddivisione della CPU per processo
.NET Framework	Supportato (LTS)	Supportato (LTS)	Supportato (LTS)	Supportato (LTS)	Supportato (LTS)
.NET Core (target=.NET Framework)	Supportato (LTS)	Supportato (LTS)	Supportato (LTS)	Supportato (LTS)	Supportato (LTS)
.NET Core (target=.NET Core)	Supportato (LTS)	Supported*	Supportato (LTS)	Supportato (LTS)	Non supportato

Le metriche di base includono richiesta, dipendenza e frequenza delle eccezioni. Le metriche delle prestazioni (contatori delle prestazioni) includono memoria e CPU. I dati di telemetria di esempio mostrano un flusso di informazioni dettagliate per le richieste non riuscite e le dipendenze, le eccezioni, gli eventi e le tracce.

Il supporto di PerfCounters varia leggermente tra le versioni di .NET Core che non hanno come destinazione .NET Framework:

• Le metriche perfCounters sono supportate durante l'esecuzione in Azure App Service per Windows (ASP.NET Core SDK versione 2.4.1 o successiva).
• PerfCounters sono supportati quando l'app è in esecuzione su qualsiasi computer Windows per le app destinate a .NET Core LTS o versione successiva.
• PerfCounters sono supportati quando l'app è in esecuzione ovunque (ad esempio Linux, Windows, servizio app su Linux o contenitori) nelle versioni più recenti, ma solo per le app destinate a .NET Core LTS o versione successiva.

Abilitare le metriche attive usando il codice per qualsiasi applicazione .NET

ASP.NET

Per configurare manualmente le metriche attive:

1. Installare il pacchetto NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. Il codice dell'app console di esempio seguente mostra la configurazione delle metriche attive:

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a TelemetryConfiguration instance.
            TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
            config.ConnectionString = "<YOUR-CONNECTION-STRING>";
            QuickPulseTelemetryProcessor quickPulseProcessor = null;
            config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
                .Use((next) =>
                {
                    quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
                    return quickPulseProcessor;
                })
                .Build();

            var quickPulseModule = new QuickPulseTelemetryModule();

            // Secure the control channel.
            // This is optional, but recommended.
            quickPulseModule.AuthenticationApiKey = "<YOUR-API-KEY>";
            quickPulseModule.Initialize(config);
            quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

            // Create a TelemetryClient instance. It is important
            // to use the same TelemetryConfiguration here as the one
            // used to set up live metrics.
            TelemetryClient client = new TelemetryClient(config);

            // This sample runs indefinitely. Replace with actual application logic.
            while (true)
            {
                // Send dependency and request telemetry.
                // These will be shown in live metrics.
                // CPU/Memory Performance counter is also shown
                // automatically without any additional steps.
                client.TrackDependency("My dependency", "target", "http://sample",
                    DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
                client.TrackRequest("My Request", DateTimeOffset.Now,
                    TimeSpan.FromMilliseconds(230), "200", true);
                Task.Delay(1000).Wait();
            }
        }
    }
}

ASP.NET Core

Per configurare manualmente le metriche attive:

1. Installare il pacchetto NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. Il codice dell'app console di esempio seguente mostra la configurazione delle metriche attive:

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

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "<YOUR-API-KEY>";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

L'esempio precedente riguarda un'app console, ma lo stesso codice può essere usato in qualsiasi applicazione .NET.

Importante

Se sono abilitati altri moduli di telemetria per la raccolta automatica dei dati di telemetria, assicurarsi che la stessa configurazione usata per l'inizializzazione di tali moduli venga usata per il modulo metriche attive.

Annotazioni

La configurazione predefinita raccoglie log e log di maggiore gravità. Per altre informazioni, vedere Come si personalizza la raccolta dei log ILogger?.

Servizio del ruolo di lavoro

I log emessi tramite con una gravità pari o superiore a Avviso vengono acquisiti automaticamente. Per modificare questo comportamento, eseguire in modo esplicito l'override della configurazione di registrazione per il provider , come illustrato nel codice seguente. La configurazione seguente consente ad Application Insights di acquisire tutti i log e i log più gravi.

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

È importante notare che l'esempio seguente non causa l'acquisizione dei log dal provider di Application Insights. Questi log non vengono acquisiti perché l'SDK aggiunge un filtro di registrazione predefinito che indica ad di acquisire solo i log e i log di maggiore gravità. Application Insights richiede un override esplicito.

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

Annotazioni

Application Insights rispetta i livelli di log configurati tramite ConfigureLogging(...) nel codice. Se viene usato solo appsettings.json e ConfigureLogging non viene sottoposto a override in modo esplicito, il livello di log predefinito è Avviso.

Per altre informazioni, vedere la documentazione di ILogger per personalizzare i livelli di log acquisiti da Application Insights.

Tracce (log)

Questa sezione illustra come inviare i log di traccia diagnostica da ASP.NET o ASP.NET Core applicazioni ad Application Insights e quindi esplorare o cercare tali log nel portale.

È possibile usare i log di traccia per identificare le tracce associate a ogni richiesta utente e correlarle con altri eventi ed eccezioni.

Application Insights acquisisce i log da ASP.NET Core e altre app .NET tramite ILogger e dai ASP.NET classici (.NET Framework) tramite l'SDK e gli adattatori classici.

Annotazioni

• Di default, il provider di Application Insights invia solo i log con una gravità di o superiore. Per includere o i log di livello inferiore, aggiornare le impostazioni del livello di log in .

• Il pacchetto NuGet, usato per abilitare Application Insights per i servizi in background, non rientra nell'ambito.

• Per esaminare le domande frequenti, vedere domande frequenti su Logging con .NET.

Installare la registrazione nell'app

ASP.NET

Scegliere un approccio di registrazione per generare log di diagnostica che Application Insights può raccogliere.

Per le app ASP.NET classiche che usano System.Diagnostics tracing, configurare un Application Insights TraceListener nella configurazione.

Aggiungere un listener a o :

<configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener"
             type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Annotazioni

Il modulo log-capture è un adattatore utile per logger di terze parti. Tuttavia, se non si usa già NLog, log4Net o , è consigliabile chiamare direttamente Application Insights TrackTrace().

Configurare Application Insights per raccogliere i log

Opzione 1: Aggiungere Application Insights al progetto, se non è già stato fatto. Quando si aggiunge Application Insights in Visual Studio, è possibile includere l'agente di raccolta log.

Opzioni 2: fare clic con il pulsante destro del mouse sul progetto in Solution Explorer per Configurare Application Insights. Selezionare l'opzione Configura raccolta di tracce .

Annotazioni

Se ti manca il menu o l'opzione dell'agente di raccolta log di Application Insights, consulta l'articolo dedicato sulla risoluzione dei problemi.

ASP.NET Core

Application Insights SDK per ASP.NET Core raccoglie già i log ILogger per impostazione predefinita. Se si usa l'SDK, in genere non è necessario chiamare ed è possibile ignorare le istruzioni di installazione di ILogger seguenti.

Se è necessario solo l'inoltro dei log e non lo stack di telemetria completo, è possibile usare il pacchetto del provider per acquisire i log.

Installazione manuale

Usare questo metodo se il tipo di progetto non è supportato dal programma di installazione di Application Insights (ad esempio, alcuni scenari desktop/console) o se si preferisce un controllo esplicito a livello di pacchetto.

1. In Solution Explorer fare clic con il pulsante destro del mouse sul progetto e selezionare Gestisci pacchetti NuGet.

2. Effettua una ricerca di Application Insights.

3. Selezionare uno dei pacchetti seguenti:

   • ILogger: Microsoft.Extensions.Logging.ApplicationInsightsNuGet ILogger
   • System.Diagnostics: Microsoft.ApplicationInsights.TraceListenerBanner System.Diagnostics NuGet
   • log4net: Microsoft.ApplicationInsights.Log4NetAppenderbanner NuGet Log4Net
   • NLog: Microsoft.ApplicationInsights.NLogTargetbanner NuGet NLog
   • Microsoft.ApplicationInsights.EventSourceListenerBanner listener origine eventi NuGet
   • Microsoft.ApplicationInsights.DiagnosticSourceListenerBanner Diagnostic Source Listener NuGet
   • Microsoft.ApplicationInsights.EtwCollectorBanner agente di raccolta Etw NuGet

Il pacchetto NuGet installa gli assembly necessari e modifica web.config o , se applicabile.

Istruzioni di installazione:

Annotazioni

Espandere una delle sezioni seguenti per istruzioni di installazione specifiche del pacchetto.

Ilogger

1. Installa il .

2. Aggiungi :

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Dopo aver installato il pacchetto NuGet e registrato il provider con l’inserimento delle dipendenze, l’app è pronta per registrare i log. Con l'inserimento del costruttore, o l'alternativa di tipo generico è necessaria. Quando queste implementazioni vengono risolte, fornisce tali implementazioni. I messaggi o le eccezioni registrati vengono inviati ad Application Insights.

Si consideri il controller di esempio seguente:

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Per altre informazioni, vedere Logging in ASP.NET Core e Qual è il tipo di telemetria di Application Insights generato dai log ILogger? Dove è possibile visualizzare i log ILogger in Application Insights?.

Inserire chiamate di log di diagnostica (System.Diagnostics.Trace/ log4net/ NLog)

Se si usa , una chiamata tipica sarà:

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

Se si preferisce o , usare:

    logger.Warn("Slow response - database01");

Usare gli eventi di EventSource

È possibile configurare gli eventi System.Diagnostics.Tracing.EventSource da inviare ad Application Insights come tracce.

1. Installare il pacchetto NuGet .

2. Modificare la sezione del file diApplicationInsights.config :

       <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
         <Sources>
           <Add Name="MyCompany" Level="Verbose" />
         </Sources>
       </Add>
   

Per ogni origine, è possibile impostare i parametri seguenti:

• Name specifica il nome dell'oggetto EventSource da raccogliere.
• Level specifica il livello di registrazione da raccogliere: Critical, Error, Informational, LogAlways, Verbose o Warning.
• Le parole chiave (facoltative) specificano il valore intero delle combinazioni di parole chiave da usare.

Usare gli eventi DiagnosticSource

È possibile configurare gli eventi System.Diagnostics.DiagnosticSource da inviare ad Application Insights come tracce.

1. Installare il pacchetto NuGet .

2. Modificare la sezione del file diApplicationInsights.config :

       <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
         <Sources>
           <Add Name="MyDiagnosticSourceName" />
         </Sources>
       </Add>
   

Per ogni origine di diagnostica che vuoi tracciare, aggiungi una voce con l'attributo impostato sul nome della tua origine di diagnostica.

Usare gli eventi ETW

È possibile configurare Event Tracing per gli eventi Windows (ETW) da inviare ad Application Insights come tracce.

1. Installare il pacchetto NuGet .

2. Modificare la sezione "TelemetryModules" del file ApplicationInsights.config :

Annotazioni

Gli eventi ETW possono essere raccolti solo se il processo che ospita l'SDK viene eseguito in un'identità che è membro del gruppo Performance Log Users o Administrators.

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Per ogni origine, è possibile impostare i parametri seguenti:

• ProviderName è il nome del provider ETW da raccogliere.
• ProviderGuid specifica il GUID del provider ETW da raccogliere. Può essere usato invece di .
• Level imposta il livello di registrazione per la raccolta. Può essere Critico, Errore, Informativo, LogAlways, Dettagliato o Avviso.
• Le parole chiave (facoltative) impostano il valore intero delle combinazioni di parole chiave da usare.

Usare direttamente l'API di traccia

È possibile chiamare direttamente l'API di traccia di Application Insights. Gli adattatori di registrazione usano questa API. Per esempio:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Un vantaggio di è che è possibile inserire dati relativamente lunghi nel messaggio. Ad esempio, è possibile codificare i dati POST in questa posizione.

È anche possibile aggiungere un livello di gravità al messaggio. Analogamente ad altri dati di telemetria, è possibile aggiungere valori di proprietà per filtrare o cercare set di tracce diversi. Per esempio:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

È ora possibile filtrare facilmente in Cerca tutti i messaggi di un particolare livello di gravità correlato a un determinato database.

Applicazione console

Per aggiungere la registrazione di Application Insights alle applicazioni console, installare prima di tutto i pacchetti NuGet seguenti:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

Nell'esempio seguente viene usato il pacchetto e viene illustrato il comportamento predefinito per un'applicazione console. Il pacchetto deve essere usato in un'applicazione console o ogni volta che si vuole un'implementazione minima di Application Insights senza il set di funzionalità completo, ad esempio metriche, traccia distribuita, campionamento e inizializzatori di telemetria.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Per altre informazioni, vedere Che tipo di dati di telemetria di Application Insights viene prodotto dai log ILogger? Dove è possibile visualizzare i log ILogger in Application Insights?.

Ambiti di registrazione

Annotazioni

Le indicazioni seguenti si applicano agli scenari ILogger (solo ASP.NET Core e console). Non si applica alla versione classica di ASP.NET.

supporta gli ambiti di log, che sono abilitati per impostazione predefinita.

Se l'ambito è di tipo , ogni coppia chiave/valore nella raccolta viene aggiunta ai dati di telemetria di Application Insights come proprietà personalizzate. Nell'esempio seguente, i log vengono acquisiti come e hanno nelle proprietà.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Se viene utilizzato un altro tipo come ambito, verrà archiviato sotto la proprietà nei dati di telemetria di Application Insights. Nell'esempio seguente, ha una proprietà chiamata che contiene l'ambito.

using (_logger.BeginScope("hello scope"))
{
    _logger.LogError("An example of an Error level message");
}

Trova i tuoi log

Eseguire l'app in modalità di debug o distribuirla in tempo reale.

Esplora nella ricerca

Nel riquadro di panoramica dell'app nel portale di Application Insights selezionare Cerca in cui è possibile:

• Filtrare in base alle tracce di log o agli elementi con proprietà specifiche.
• Esaminare in dettaglio un elemento specifico.
• Trovare altri dati di log di sistema correlati alla stessa richiesta utente (con lo stesso ID operazione).
• Salvare la configurazione di una pagina come preferito.

Annotazioni

Se l'applicazione invia grandi quantità di dati e si usa Application Insights SDK per ASP.NET versione 2.0.0-beta3 o successiva, la funzionalità di campionamento adaptive potrebbe funzionare e inviare solo una parte dei dati di telemetria. Altre informazioni sul campionamento.

Esplorare nei log di Azure Monitor

I log ILogger vengono visualizzati come dati di telemetria di traccia (tabella traces in Application Insights e AppTraces in Log Analytics).

Esempio

Nel portale di Azure passare ad Application Insights ed eseguire:

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

Tracciamento distribuito

Le architetture moderne di cloud e microservizi hanno abilitato servizi semplici e indipendenti che riducono i costi aumentando la disponibilità e la velocità effettiva. Tuttavia, ha reso i sistemi generali più difficili da ragionare e eseguire il debug. Il tracciamento distribuito risolve questo problema fornendo un profiler delle prestazioni che funziona come le pile di chiamate nelle architetture cloud e microservizi.

Azure Monitor offre due esperienze per l'utilizzo di dati di traccia distribuiti: la diagnostica transaction per una singola transazione/richiesta e la mappa application per mostrare l'interazione dei sistemi.

Application Insights può monitorare ogni componente separatamente e rilevare quale componente è responsabile di errori o riduzione delle prestazioni usando la correlazione di telemetria distribuita. Questo articolo illustra il modello di dati, le tecniche di propagazione del contesto, i protocolli e l'implementazione di tattiche di correlazione su linguaggi e piattaforme diversi usati da Application Insights.

Abilitare la traccia distribuita tramite Application Insights utilizzando l'autoinstrumentazione o gli SDK

Gli agenti e gli SDK di Application Insights per .NET, .NET Core, Java, Node.jse JavaScript supportano la traccia distribuita in modo nativo.

Dopo avere installato e configurato la versione corretta di Application Insights SDK, le informazioni di traccia vengono raccolte automaticamente per le librerie, le tecnologie e i framework più diffusi da agenti di raccolta delle dipendenze dell'SDK automatici. L'elenco completo delle tecnologie supportate è disponibile nella documentazione sulla raccolta automatica delle dipendenze.

Qualsiasi tecnologia può anche essere rilevata manualmente con una chiamata a TrackDependency in TelemetryClient.

Modello di dati per la correlazione dei dati di telemetria

Application Insights definisce un modello di dati per la correlazione di dati di telemetria distribuita. Per associare i dati di telemetria a un'operazione logica, ogni elemento di telemetria ha un campo di contesto denominato . Ogni elemento di telemetria nella traccia distribuita condivide questo identificatore. Pertanto, anche se si perdono i dati di telemetria da un singolo livello, è comunque possibile associare i dati di telemetria segnalati da altri componenti.

Un'operazione logica distribuita è in genere costituita da un set di operazioni più piccole elaborate da uno dei componenti. I dati di telemetria delle richieste definiscono queste operazioni. Ogni elemento di telemetria della richiesta ha il proprio , che lo identifica in modo globale e univoco. E tutti gli elementi di telemetria, ad esempio tracce ed eccezioni, associati alla richiesta devono impostare su il valore della richiesta .

La telemetria delle dipendenze rappresenta ogni operazione in uscita, ad esempio una chiamata HTTP a un altro componente. Definisce anche il proprio , un elemento univoco a livello globale. La telemetria delle richieste, avviata dalla chiamata di dipendenza, usa questo come .

È possibile compilare una vista dell'operazione logica distribuita usando , e con . Questi campi definiscono anche l'ordine di causalità delle chiamate di telemetria.

In un ambiente di microservizi, le tracce dei componenti possono passare a elementi di archiviazione diversi. Ogni componente può avere un proprio connection string in Application Insights. Per ottenere dati di telemetria per l'operazione logica, Application Insights esegue query sui dati da ogni elemento di archiviazione.

Quando il numero di elementi di archiviazione è grande, è necessario un suggerimento su dove cercare successivamente. Il modello di dati di Application Insights definisce due campi per risolvere questo problema: e . Il primo campo identifica il componente che ha avviato la richiesta di dipendenza. Il secondo campo identifica il componente che ha restituito la risposta della chiamata di dipendenza.

Per informazioni sull'esecuzione di query da più istanze diverse, vedere Eseguire query sui dati in aree di lavoro, applicazioni e risorse Log Analytics in Monitoraggio di Azure.

Example

Di seguito è descritto un esempio. Un'applicazione denominata Stock Prices mostra il prezzo di mercato corrente di un titolo usando un'API esterna denominata Stock. L'applicazione Prezzi azionari ha una pagina denominata Pagina stock visualizzata dal Web browser client tramite . L'applicazione esegue una query sull'API Stock usando la chiamata HTTP .

È possibile analizzare i dati di telemetria risultanti eseguendo una query:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Nei risultati tutti gli elementi di telemetria condividono la radice . Quando viene effettuata una chiamata Ajax dalla pagina, viene assegnato un nuovo ID univoco () ai dati di telemetria delle dipendenze e l'ID di pageView viene usato come . La richiesta del server usa quindi l'ID Ajax come .

tipo di elemento	nome	Documento d'identità	operation_ParentId	operation_Id
pageView	Pagina delle scorte	STYz		STYz
dipendenza	GET /Home/Stock	qJSXU	STYz	STYz
request	GET /Home/Stock	KqKwlrSt9PA=	qJSXU	STYz
dipendenza	GET /api/stock/value # Ottieni il valore d'inventario tramite API	bBrf2L7mm2g=	KqKwlrSt9PA=	STYz

Quando la chiamata viene effettuata a un servizio esterno, è necessario conoscere l'identità del server in modo da poter impostare il campo in modo appropriato. Quando il servizio esterno non supporta il monitoraggio, viene impostato sul nome host del servizio. Un esempio è . Tuttavia, se il servizio si identifica restituendo un'intestazione HTTP predefinita, contiene l'identità del servizio che consente ad Application Insights di compilare una traccia distribuita eseguendo query sui dati di telemetria da tale servizio.

Intestazioni di correlazione utilizzando W3C TraceContext

Application Insights esegue la transizione a W3C Trace-Context, che definisce:

• : Trasporta l'ID operativo univoco globale e l'identificatore univoco della chiamata.
• : contiene il contesto di tracciamento specifico del sistema.

La versione più recente di Application Insights SDK supporta il protocollo Trace-Context, ma potrebbe essere necessario acconsentire esplicitamente. La retrocompatibilità con il protocollo di correlazione precedente supportato dall'SDK di Application Insights è mantenuta.

Il protocollo HTTP di correlazione, detto anche Request-Id, è deprecato. Questo protocollo definisce due intestazioni:

• : porta l'ID univoco globale della chiamata.
• : contiene la raccolta di coppie nome-valore delle proprietà di tracciamento distribuito.

Application Insights definisce anche l'estensione per il protocollo HTTP di correlazione. Usa le coppie nome-valore per propagare la raccolta di proprietà usate dal chiamante o dal destinatario della chiamata. Il SDK di Application Insights utilizza questo header per impostare i campi e .

I modelli di dati W3C Trace-Context e Application Insights sono mappati nel modo seguente:

Approfondimenti sulle Applicazioni	W3C TraceContext
di e	parent-id
Operation_Id	trace-id
Operation_ParentId	parent-id dell'intervallo padre di questo intervallo. Questo campo deve essere vuoto se è un intervallo radice.

Per altre informazioni, vedere Modello di dati di telemetria di Application Insights.

Abilitare il supporto per la traccia distribuita W3C

La traccia distribuita basata su W3C TraceContext è abilitata per impostazione predefinita in tutti gli SDK .NET Framework/.NET Core più recenti, insieme alla compatibilità retroattiva con il protocollo legacy Request-Id.

Correlazione dei dati di telemetria

La correlazione viene gestita automaticamente durante l'integrazione di un'app. Non sono necessarie azioni speciali.

.NET runtime supporta i sistemi distribuiti con l'aiuto di Activity e DiagnosticSource

Application Insights .NET SDK usa DiagnosticSource e Activity per raccogliere e correlare i dati di telemetria.

Dipendenze

Dipendenze rilevate automaticamente

Gli SDK di Application Insights per .NET e .NET Core includono DependencyTrackingTelemetryModule, un modulo di telemetria che raccoglie automaticamente le dipendenze. Il modulo viene fornito come pacchetto NuGet Microsoft.ApplicationInsights.DependencyCollector e usato automaticamente quando si usa il pacchetto NuGet o il pacchetto NuGet.

Attualmente, tiene traccia delle dipendenze seguenti automaticamente:

Dipendenze	Dettagli
HTTP/HTTPS	Chiamate HTTP/HTTPS locali o remote.
Chiamate WCF	Rilevata automaticamente solo se vengono usate associazioni basate su HTTP.
SQL	Chiamate effettuate con . Vedere la sezione Rilevamento SQL avanzato per ottenere query SQL complete per l'acquisizione di query SQL.
Archiviazione BLOV di Azure, Archiviazione di tabelle o Archiviazione di code	Chiamate effettuate con il client Azure Storage.
Azure Event Hubs SDK client	Usare il pacchetto più recente: https://nuget.org/packages/Azure.Messaging.EventHubs.
SDK client del Azure Service Bus	Usare il pacchetto più recente: https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB	Rilevato automaticamente se viene usato HTTP/HTTPS. La traccia per le operazioni in modalità diretta con TCP viene acquisita automaticamente usando il pacchetto di anteprima >= 3.33.0-preview. Per altri dettagli, vedere la documentazione.

Se la dipendenza non viene selezionata automaticamente, è possibile monitorarla manualmente con una chiamata di dipendenza di rilevamento.

Per altre informazioni sul funzionamento del rilevamento delle dipendenze, vedere Rilevamento delle dipendenze in Application Insights.

Come funziona il monitoraggio automatico delle dipendenze?

• La strumentazione del bytecode viene applicata ai metodi selezionati utilizzando InstrumentationEngine e può essere abilitata tramite StatusMonitor o l'estensione di Application Insights per Servizio app di Azure.

• EventSource i callback vengono usati per acquisire dati di telemetria dalle librerie .NET che generano eventi strutturati.

• DiagnosticSource i callback vengono usati nei più recenti SDK .NET e .NET Core per raccogliere dati di telemetria dalle librerie che supportano il tracciamento distribuito.

Configurare il rilevamento automatico delle dipendenze nelle app console

Per tenere traccia automaticamente delle dipendenze dalle app console di .NET, installare il pacchetto NuGet Microsoft.ApplicationInsights.DependencyCollector e inizializzare DependencyTrackingTelemetryModule:

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

Annotazioni

Per le app console di .NET Core, TelemetryConfiguration.Active è obsoleto.

Rilevamento manuale delle dipendenze

Gli esempi seguenti di dipendenze, che non vengono raccolti automaticamente, richiedono il rilevamento manuale:

• Azure Cosmos DB viene monitorato automaticamente solo se viene usato HTTP/HTTPS. La modalità TCP non viene acquisita automaticamente da Application Insights per le versioni dell'SDK precedenti a .
• Redis

Per tali dipendenze non raccolte automaticamente dall'SDK, è possibile tenerne traccia manualmente usando l'API TrackDependency usata dai moduli di raccolta automatica standard.

Esempio

Se si compila il codice con un assembly che non è stato scritto manualmente, è possibile eseguire tutte le chiamate. Questo scenario consente di scoprire quale contributo apporta ai tempi di risposta.

Per visualizzare i dati nei grafici relativi alle dipendenze in Application Insights, inviarli mediante :

    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

In alternativa, fornisce i metodi di estensione e , che possono essere usati per tenere traccia manualmente delle dipendenze, come illustrato in Rilevamento delle dipendenze in uscita.

Disabilitazione del modulo di rilevamento delle dipendenze standard

Per altre informazioni, vedere Moduli di telemetria.

Rilevamento SQL avanzato per ottenere la query SQL completa

Per le chiamate SQL, il nome del server e del database viene sempre raccolto e archiviato come nome dell'oggetto raccolto . Un altro campo, denominato dati, può contenere il testo completo della query SQL.

Annotazioni

Azure Functions richiede impostazioni separate per abilitare la raccolta di testo SQL. Per altre informazioni, vedere Abilitare la raccolta di query SQL.

ASP.NET

Per le applicazioni ASP.NET, il testo completo della query SQL viene raccolto con l'aiuto della strumentazione del codice byte, che richiede l'uso del motore di strumentazione o del pacchetto NuGet Microsoft.Data.SqlClient anziché della libreria System.Data.SqlClient. I passaggi specifici della piattaforma per abilitare la raccolta completa di query SQL sono descritti nella tabella seguente.

Platform	Passaggi necessari per ottenere la query SQL completa
Web Apps in Azure App Service	Nel pannello di controllo dell'app Web aprire il riquadro Application Insights e abilitare i comandi SQL in .NET.
Server IIS (Azure Virtual Machines, locale e così via)	Usare il pacchetto NuGet Microsoft.Data.SqlClient oppure usare il modulo PowerShell dell'agente di Application Insights per installare il motore di strumentazione e riavviare IIS.
Azure Cloud Services	Aggiungere un'attività di avvio per installare StatusMonitor. L'app deve essere integrata con all'ApplicationInsights SDK in fase di compilazione, installando i pacchetti NuGet per applicazioni ASP.NET o ASP.NET Core.
IIS Express	Usare il pacchetto NuGet Microsoft.Data.SqlClient .
Processi Web nel servizio app di Azure	Usare il pacchetto NuGet Microsoft.Data.SqlClient .

Oltre ai passaggi precedenti specifici della piattaforma, è anche necessario acconsentire esplicitamente all'abilitazione della raccolta di comandi SQL modificando il file con il codice seguente:

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

ASP.NET Core

Per ASP.NET Core applicazioni, è necessario acconsentire esplicitamente alla raccolta di testo SQL usando:

services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module. EnableSqlCommandTextInstrumentation = true; });

Nei casi precedenti, il modo corretto per convalidare che il motore di strumentazione sia installato correttamente è convalidando che la versione SDK di raccolta è . L'uso di o indica che le dipendenze vengono raccolte tramite callback o , quindi la query SQL completa non viene acquisita.

Exceptions

Le eccezioni nelle applicazioni Web possono essere segnalate con Application Insights. È possibile correlare le richieste non riuscite con le eccezioni e altri eventi sia nel client che nel server, in modo da poter diagnosticare rapidamente le cause. Questa sezione illustra come configurare la segnalazione delle eccezioni, segnalare le eccezioni in modo esplicito, diagnosticare gli errori e altro ancora.

Configurare la creazione di report sulle eccezioni

È possibile configurare Application Insights per segnalare le eccezioni che si verificano nel server o nel client. A seconda della piattaforma da cui dipende l'applicazione, è necessario usare l'estensione o l'SDK appropriato.

Lato server

Per fare in modo che le eccezioni vengano segnalate dall'applicazione lato server, considerare gli scenari seguenti:

• Aggiungere l'estensione Application Insights per Azure app Web.
• Aggiungere l'estensione Application Monitoring Extension per le macchine virtuali Azure, i set di scalabilità di macchine virtuali Azure e le app ospitate in IIS.
• Aggiungi Application Insights SDK al codice dell'app, esegui Application Insights Agent per i server Web IIS oppure abilita Java agent per le app Web Java.

Lato client

L'SDK di JavaScript offre la possibilità di segnalare lato client le eccezioni che si verificano nei Web browser. Per configurare la segnalazione delle eccezioni nel client, vedere Application Insights per le pagine Web.

Framework applicazioni

Con alcuni framework dell'applicazione, è necessaria una maggiore configurazione. Considerare le tecnologie seguenti:

• Web Form
• MVC
• API Web 1.*
• API Web 2.*
• WCF

Importante

Questa sezione è incentrata sulle app di .NET Framework dal punto di vista di un esempio di codice. Alcuni dei metodi che funzionano per .NET Framework sono obsoleti in .NET Core SDK.

Diagnosticare errori ed eccezioni

portale di Azure

Application Insights offre un'esperienza di gestione delle prestazioni delle applicazioni curata che consente di diagnosticare gli errori nelle applicazioni monitorate.

Per istruzioni dettagliate, vedere Analizzare errori, prestazioni e transazioni con Application Insights.

Visual Studio

1. Aprire la soluzione dell'app in Visual Studio. Eseguire l'app nel server o nel computer di sviluppo usando F5. Ricreare l'eccezione.

2. Aprire la finestra di telemetria Application Insights Search in Visual Studio. Durante il debug selezionare la casella di riepilogo a discesa Application Insights .

3. Selezionare la segnalazione di un'eccezione per visualizzarne l'analisi dello stack. Per aprire il relativo file di codice, selezionare un riferimento di riga nell'analisi dello stack.

   Se CodeLens è abilitato, vengono visualizzati i dati sulle eccezioni:

   Screenshot che mostra la notifica CodeLens delle eccezioni.

Dati di traccia e di log personalizzati

Per ottenere dati di diagnostica specifici per l'app, è possibile inserire codice per l'invio dei propri dati di telemetria. I propri dati di log o telemetria vengono visualizzati nella ricerca diagnostica insieme alla richiesta, alla visualizzazione di pagina e ad altri dati raccolti automaticamente.

Usando , sono disponibili diverse API:

• viene usato in genere per il monitoraggio dei modelli di utilizzo, ma i dati inviati vengono visualizzati anche in Eventi personalizzati nella ricerca diagnostica. Gli eventi sono denominati e possono includere proprietà di stringa e metriche numeriche, in base alle quali è possibile filtrare le ricerche diagnostiche.
• consente di inviare dati più lunghi, ad esempio informazioni POST.
• invia i dettagli dell'eccezione, ad esempio l'analisi dello stack ad Application Insights.

Per visualizzare questi eventi, nel menu a sinistra aprire Cerca. Selezionare il menu a discesa Tipi di evento e quindi scegliere Evento personalizzato, Traccia o Eccezione.

Screenshot che mostra la schermata Cerca.

Annotazioni

Se l'app genera grandi quantità di dati di telemetria, il modulo di campionamento adattivo riduce automaticamente il volume inviato al portale inviando solo una frazione rappresentativa di eventi. Gli eventi che fanno parte della stessa operazione vengono selezionati o deselezionati come gruppo, per rendere possibile lo spostamento tra eventi correlati. Per altre informazioni, vedere Campionamento in Application Insights.

Vedere i dati POST di una richiesta

I dettagli della richiesta non includono i dati inviati all'app in una chiamata POST. Per poter ottenere questi dati:

• Aggiungere Application Insights SDK al codice dell'app.
• Inserire il codice nell'applicazione per chiamare Microsoft.ApplicationInsights.TrackTrace(). Inviare i dati POST nel parametro del messaggio. Esiste un limite per le dimensioni consentite, quindi è consigliabile provare a inviare solo i dati essenziali.
• Quando si esamina una richiesta non riuscita, trovare le tracce associate.

Acquisire le delle eccezioni e i dati di diagnostica correlati

Per impostazione predefinita, non tutte le eccezioni che generano errori nell'app vengono visualizzate nel portale. Se si usa JavaScript SDK nelle pagine Web, vengono visualizzate eccezioni del browser. Tuttavia, la maggior parte delle eccezioni lato server vengono intercettate da IIS ed quindi è necessario aggiungere del codice per acquisirle e segnalarle.

È possibile:

• Registrare le eccezioni in modo esplicito inserendo il codice nei gestori di eccezioni per segnalare le eccezioni.
• Cattura automaticamente le eccezioni configurando il framework ASP.NET. Gli elementi da aggiungere variano a seconda dei diversi tipi di framework.

Segnalare le eccezioni in modo esplicito

Il modo più semplice per segnalare consiste nell'inserire una chiamata a in un gestore eccezioni.

C#

var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}

JavaScript

try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

I parametri delle proprietà e delle misurazioni sono facoltativi, ma sono utili per filtrare e aggiungere altre informazioni. Ad esempio, se hai un'app che può eseguire diversi giochi, potresti trovare i report delle eccezioni correlati a un determinato gioco. È possibile aggiungere il numero desiderato di elementi a ogni dizionario.

Eccezioni del browser

Viene segnalata la maggior parte delle eccezioni del browser.

Se la pagina Web include file di script provenienti da reti per la distribuzione di contenuti o da altri domini, verificare che il tag dello script contenga l'attributo e che il server invii intestazioni CORS. Questo comportamento consente di ottenere un'analisi dello stack e i dettagli per le eccezioni JavaScript non gestite da queste risorse.

Riutilizzare il client di telemetria

Annotazioni

È consigliabile creare un'istanza di una volta e riutilizzarla per tutta la durata di un'applicazione.

Con Dependency Injection (DI) in .NET, il corretto SDK di .NET e la giusta configurazione di Application Insights per DI, puoi richiedere TelemetryClient come parametro del costruttore.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

Nell'esempio precedente, l'oggetto viene inserito nella classe .

Web Form

Per Web Forms, il modulo HTTP può raccogliere le eccezioni quando non sono configurati reindirizzamenti con . Tuttavia, quando sono presenti reindirizzamenti attivi, aggiungere le righe seguenti alla funzione in Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

Nell'esempio precedente, è una variabile con ambito classe di tipo .

MVC

A partire da Application Insights Web SDK versione 2.6 (beta 3 e versioni successive), Application Insights raccoglie le eccezioni non gestite generate automaticamente nei metodi dei controller MVC 5+. Se in precedenza è stato aggiunto un gestore personalizzato per tenere traccia di tali eccezioni, è possibile rimuoverlo per evitare il doppio rilevamento delle eccezioni.

Esistono diversi scenari in cui un filtro eccezioni non riesce a gestire correttamente gli errori quando vengono generate eccezioni:

• Dai costruttori del controller
• Dai gestori di messaggi
• Durante il routing
• Durante la serializzazione del contenuto della risposta
• Durante l'avvio dell'applicazione
• Nelle attività in background

È ancora necessario tenere traccia manualmente di tutte le eccezioni gestite dall'applicazione. Le eccezioni non gestite provenienti dai controller in genere restituiscono una risposta 500 "Errore interno del server". Se tale risposta viene costruita manualmente come risultato di un'eccezione gestita o nessuna eccezione, viene rilevata nei dati di telemetria delle richieste corrispondenti con 500. Tuttavia, l'SDK di Application Insights non è in grado di tenere traccia di un'eccezione corrispondente.

Supporto delle versioni precedenti

Se si usa MVC 4 (e versioni precedenti) di Application Insights Web SDK 2.5 (e versioni precedenti), vedere gli esempi seguenti per tenere traccia delle eccezioni.

Espandere per visualizzare le istruzioni per le versioni precedenti

Se la configurazione di CustomErrors è , le eccezioni possono essere raccolte dal modulo HTTP. Se invece è impostata su (impostazione predefinita) o , l'eccezione viene cancellata e non può essere raccolta automaticamente da Application Insights. È possibile correggere il comportamento eseguendo l'override della classe System.Web.Mvc.HandleErrorAttribute e applicando la classe sottoposta a override come illustrato per le diverse versioni MVC qui (vedere GitHub source):

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

MVC 2

Sostituire l'attributo HandleError con il nuovo attributo nei controller:

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

Esempio

MVC 3

Registrare come filtro globale in Global.asax.cs:

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

Esempio

MVC 4, MVC 5

Registrare come filtro globale in FilterConfig.cs:

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

Esempio

API per il Web

A partire da Application Insights Web SDK versione 2.6 (beta 3 e versioni successive), Application Insights raccoglie le eccezioni non gestite generate automaticamente nei metodi dei controller per API Web 2+. Se in precedenza è stato aggiunto un gestore personalizzato per tenere traccia di tali eccezioni (come descritto nell'esempio seguente), è possibile rimuoverlo per evitare il doppio rilevamento delle eccezioni.

Esistono diversi casi in cui i filtri delle eccezioni non possono essere gestiti. Per esempio:

• Eccezioni generate dai costruttori dei controller.
• Eccezioni generate dai gestori di messaggi.
• Eccezioni generate durante il routing.
• Eccezioni generate durante la serializzazione del contenuto della risposta.
• Eccezione generata durante l'avvio dell'applicazione.
• Eccezione generata in attività in background.

È ancora necessario tenere traccia manualmente di tutte le eccezioni gestite dall'applicazione. Le eccezioni non gestite provenienti dai controller in genere restituiscono una risposta 500 "Errore interno del server". Se tale risposta viene costruita manualmente come risultato di un'eccezione gestita o nessuna eccezione, viene rilevata in una telemetria di richiesta corrispondente con 500. Tuttavia, l'SDK di Application Insights non è in grado di tenere traccia di un'eccezione corrispondente.

Supporto delle versioni precedenti

Se si usa API Web 1 (e versioni precedenti) di Application Insights Web SDK 2.5 (e versioni precedenti), vedere gli esempi seguenti per tenere traccia delle eccezioni.

Espandere per visualizzare le istruzioni per le versioni precedenti

API Web 1.x

Override:

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

È possibile aggiungere questo attributo di cui è stato eseguito l'override ai controller specifici o alla configurazione del filtro globale nella classe :

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

Esempio

API Web 2.x

Aggiungere un'implementazione di :

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

Aggiungere questo frammento di codice ai servizi in :

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

Esempio

In alternativa, è possibile:

• Sostituire l'unica istanza con un'implementazione personalizzata di . Questo gestore di eccezione viene chiamato solo quando il framework può ancora scegliere il messaggio di risposta da inviare, non quando la connessione viene interrotta.
• Usare i filtri eccezioni, come descritto nella sezione precedente sui controller dell'API Web 1.x, che non vengono chiamati in tutti i casi.

WCF

Aggiungere una classe che estende e implementa e .

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

Aggiungere l'attributo alle implementazioni del servizio:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Esempio

Contatori delle prestazioni delle eccezioni

Se si installato l'agente di Application Insights Azure Monitor nel server, è possibile ottenere un grafico della frequenza delle eccezioni misurata da .NET. Sono incluse le eccezioni .NET sia gestite che non gestite.

Aprire una scheda Esplora metriche e aggiungere un nuovo grafico. In Contatori delle prestazioni selezionare Frequenza eccezioni.

Il framework .NET calcola la frequenza conteggiando il numero di eccezioni in un intervallo e dividendo per la lunghezza dell'intervallo.

Questo conteggio è diverso dal conteggio delle eccezioni calcolato dal portale di Application Insights, che conteggia i report . Gli intervalli di campionamento sono diversi e l'SDK non invia segnalazioni di per tutte le eccezioni gestite e non gestite.

Raccolta di metriche personalizzate

Gli SDK di Azure Monitor Application Insights .NET e .NET Core hanno due diversi metodi di raccolta di metriche personalizzate:

• Il metodo , che non dispone della preaggregazione.
• Il metodo , che dispone della preaggregazione.

È consigliabile usare l'aggregazione, quindi non è più il metodo preferito per raccogliere metriche personalizzate. Questo articolo illustra come usare il metodo e alcune delle motivazioni alla base del funzionamento.

Espandere per saperne di più sulle API con preaggregazione e senza preaggregazione

Il metodo invia dati di telemetria non elaborati che denota una metrica. Non è efficiente inviare un singolo elemento di telemetria per ogni valore. Il metodo è anche inefficiente in termini di prestazioni perché ogni attraversa la pipeline SDK completa di inizializzatori e processori di telemetria.

Al contrario di , gestisce la preaggregazione locale e quindi invia solo una metrica riepilogativa aggregata a un intervallo fisso di un minuto. Se è necessario monitorare attentamente alcune metriche personalizzate al secondo o anche al livello di millisecondo, è possibile farlo solo in caso di costi di archiviazione e traffico di rete solo ogni minuto. Questo comportamento riduce notevolmente anche il rischio di limitazione perché il numero totale di elementi di telemetria che devono essere inviati per una metrica aggregata viene notevolmente ridotto.

In Application Insights le metriche personalizzate raccolte tramite e non sono soggette al campionamento. Il campionamento di metriche importanti può determinare scenari in cui gli avvisi compilati in base a tali metriche diventano inaffidabili. Non eseguendo mai il campionamento delle metriche personalizzate, in genere è possibile assicurarsi che quando le soglie di avviso vengono superate, viene generato un avviso. Poiché le metriche personalizzate non vengono campionate, esistono alcune potenziali preoccupazioni.

Il rilevamento delle tendenze in una metrica ogni secondo o a un intervallo ancora più granulare può comportare:

• Aumento dei costi di archiviazione dei dati. È previsto un costo associato alla quantità di dati inviati a Azure Monitor. Maggiore è il costo complessivo del monitoraggio.
• Aumento del traffico di rete o sovraccarico delle prestazioni. In alcuni scenari, questo sovraccarico potrebbe avere un costo delle prestazioni monetarie e dell'applicazione.
• Rischio di limitazione dell'inserimento. Azure Monitor scarta ("rallenta") i punti dati quando l'app invia una grande quantità di telemetria in un breve intervallo di tempo.

La limitazione è un problema perché può causare la mancata visualizzazione di avvisi. La condizione per attivare un avviso può verificarsi in locale e quindi essere eliminata nell'endpoint di inserimento a causa di troppi dati inviati. Non è consigliabile usare TrackMetric() per .NET e .NET Core, a meno che non sia stata implementata la logica di aggregazione locale. Se si sta tentando di tenere traccia di ogni istanza che si verifica un evento in un determinato periodo di tempo, è possibile che sia una scelta migliore. Tenere presente che, a differenza delle metriche personalizzate, gli eventi personalizzati sono soggetti al campionamento. È comunque possibile usare anche senza scrivere la propria preaggregazione locale. Ma se lo fai, tieni presente le insidie.

In sintesi, è consigliabile perché esegue la preaggregazione, accumula valori da tutte le chiamate e invia un riepilogo/aggregazione una volta ogni minuto. Il metodo può ridurre significativamente il costo e il sovraccarico delle prestazioni inviando un minor numero di punti dati pur raccogliendo tutte le informazioni pertinenti.

Introduzione a GetMetric

Per gli esempi si userà un'applicazione di servizio di lavoro di base .NET Core 3.1. Per replicare l'ambiente di test usato con questi esempi, seguire i passaggi da 1 a 6 sotto applicazione di servizio Worker di .NET Core. Questi passaggi aggiungono Application Insights a un modello di progetto del servizio di lavoro di base. I concetti si applicano a qualsiasi applicazione generale in cui è possibile usare l'SDK, incluse le app Web e le app console.

Inviare metriche

Sostituire il contenuto del file con il codice seguente:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

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

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

Quando si esegue il codice di esempio, viene visualizzato il ciclo while in esecuzione ripetutamente senza inviare dati di telemetria nella finestra di output Visual Studio. Un singolo elemento di telemetria viene inviato intorno al contrassegno di 60 secondi, che nel test ha un aspetto simile al seguente:

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

Questo singolo elemento di telemetria rappresenta un'aggregazione di 41 misurazioni di metriche distinte. Poiché stavamo inviando lo stesso valore più e più volte, abbiamo una deviazione standard () di con valori massimi identici () e minimo (). La proprietà rappresenta una somma di tutti i singoli valori aggregati.

Annotazioni

Il metodo non supporta il rilevamento dell'ultimo valore (ad esempio, ) o il rilevamento di istogrammi o distribuzioni.

Se si esamina la risorsa di Application Insights nell'esperienza Log (Analytics), il singolo elemento di telemetria sarà simile allo screenshot seguente.

Annotazioni

Anche se l'elemento di telemetria non elaborato non contiene una proprietà/campo di somma esplicito una volta inserita, ne creiamo uno automaticamente. In questo caso, sia la proprietà chee rappresentano la stessa cosa.

È anche possibile accedere ai dati di telemetria delle metriche personalizzati nella sezione Metriche del portale sia come metrica basata su log che personalizzata. Lo screenshot seguente è un esempio di metrica basata su log.

Screenshot che mostra la visualizzazione Esplora metriche.

Informazioni di riferimento sulle metriche della cache per l'utilizzo a velocità effettiva elevata

I valori delle metriche possono essere osservati frequentemente in alcuni casi. Ad esempio, un servizio a velocità effettiva elevata che elabora 500 richieste al secondo potrebbe voler generare 20 metriche di telemetria per ogni richiesta. Il risultato indica il rilevamento di 10.000 valori al secondo. In questi scenari con velocità effettiva elevata, gli utenti potrebbero dover aiutare l'SDK evitando alcune ricerche.

Ad esempio, l'esempio precedente ha eseguito una ricerca per un handle per la metrica e quindi ha rilevato un valore osservato di . Al contrario, l'handle potrebbe essere memorizzato nella cache per più chiamate di traccia:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Oltre a memorizzare nella cache l'handle delle metriche, l'esempio precedente si riduce anche a 50 millisecondi in modo che il ciclo venga eseguito più frequentemente. Il risultato è 772 chiamate .

Metriche multidimensionali

Gli esempi nella sezione precedente mostrano le metriche zero-dimensionali. Le metriche possono anche essere multidimensionali. Attualmente sono supportate fino a 10 dimensioni.

Ecco un esempio di come creare una metrica unidimensionale:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

L'esecuzione del codice di esempio per almeno 60 secondi comporta l'invio di tre elementi di telemetria distinti a Azure. Ogni elemento rappresenta l'aggregazione di uno dei tre fattori di forma. Come in precedenza, è possibile esaminare ulteriormente nella visualizzazione Log (Analytics).

In Esplora metriche:

Screenshot che mostra le metriche personalizzate.

Si noti che non è possibile suddividere la metrica in base alla nuova dimensione personalizzata o visualizzare la dimensione personalizzata con la visualizzazione delle metriche.

Screenshot che mostra il supporto della suddivisione.

Per impostazione predefinita, le metriche multidimensionali all'interno di Esplora metriche non sono attivate nelle risorse di Application Insights.

Abilitare le metriche multidimensionali

Per abilitare le metriche multidimensionali per una risorsa di Application Insights, selezionare Utilizzo e costi stimatiMetriche personalizzate Abilita avvisi sulle dimensioni delle metriche personalizzate OK. Per altre informazioni, vedere Dimensioni e preaggregazione delle metriche personalizzate.

Dopo aver apportato questa modifica e inviato nuovi dati di telemetria multidimensionali, è possibile selezionare Applica suddivisione.

Annotazioni

Solo le metriche appena inviate dopo l'attivazione della funzionalità nel portale hanno dimensioni archiviate.

Screenshot che mostra l'applicazione della suddivisione.

Visualizzare le aggregazioni delle metriche per ogni dimensione .

Screenshot che mostra i fattori di forma.

Usare MetricIdentifier quando sono presenti più di tre dimensioni

Attualmente sono supportate 10 dimensioni. L'uso di più di tre dimensioni richiede l'uso di :

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

Configurazione della metrica personalizzata

Se si vuole modificare la configurazione della metrica, è necessario apportare modifiche nella posizione in cui viene inizializzata la metrica.

Nomi di dimensioni speciali

Le metriche non usano il contesto di telemetria dell'oggetto usato per accedervi. L'uso di nomi di dimensioni speciali disponibili come costanti nella classe è la soluzione migliore per questa limitazione.

Le aggregazioni di metriche inviate dalla metrica seguente non hanno il parametro impostato su . Il metodo o qualsiasi altro metodo ha il parametro impostato correttamente su .

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

In questa circostanza, utilizzare i nomi delle dimensioni speciali elencati nella classe per specificare i valori .

Ad esempio, quando l'aggregazione di metriche risultante dall'istruzione successiva viene inviata all'endpoint cloud di Application Insights, il relativo campo dati viene impostato su :

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

Il valore di questa dimensione speciale viene copiato in e non viene usato come dimensione normale. Se si desidera mantenere anche una dimensione operativa per l'esplorazione normale delle metriche, è necessario creare una dimensione separata a tale scopo:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

Limite di dimensioni e serie temporali

Per impedire che il sottosistema di telemetria usi accidentalmente le risorse, è possibile controllare il numero massimo di serie di dati per metrica. I limiti predefiniti non sono più di 1.000 serie di dati totali per metrica e non più di 100 valori diversi per dimensione.

Importante

Usare valori cardinali bassi per le dimensioni per evitare la limitazione.

Nel contesto del limite di dimensioni e serie temporali, viene usato per assicurarsi che vengano osservati i limiti. Se i limiti sono già raggiunti, restituisce e il valore non verrà monitorato. In caso contrario, restituisce . Questo comportamento è utile se i dati per una metrica provengono dall'input dell'utente.

Il costruttore accetta alcune opzioni su come gestire serie diverse all'interno della rispettiva metrica e un oggetto di una classe che implementa che specifica il comportamento di aggregazione per ogni singola serie della metrica:

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call doesn't track the metric, and returns false.

• è il numero massimo di serie temporali di dati che una metrica può contenere. Quando viene raggiunto questo limite, le chiamate a che normalmente comportano la restituzione di una nuova serie, ora restituiscono .
• limita il numero di valori distinti per dimensione in modo analogo.
• determina se devono essere rilevati solo valori integer non negativi.

Ecco un esempio di come inviare un messaggio per sapere se vengono superati i limiti limite:

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

Rilevamento delle operazioni personalizzate

Gli SDK di Application Insights verificano automaticamente le richieste HTTP in ingresso e le chiamate ai servizi dipendenti, come richieste HTTP e query SQL. La verifica e la correlazione di richieste e dipendenze offre visibilità sui tempi di risposta e sull'affidabilità dell'intera applicazione in tutti i microservizi che combinano questa applicazione.

Esiste una classe di modelli di applicazione che non può essere supportata in modo generico. Per il corretto monitoraggio di tali modelli, è necessaria la strumentazione manuale del codice. Questa sezione illustra alcuni modelli che potrebbero richiedere l'uso della strumentazione manuale, come l'elaborazione di code personalizzate e l'esecuzione di attività in background a lungo termine.

Questa sezione offre indicazioni su come tenere traccia delle operazioni personalizzate con Application Insights SDK.

Informazioni generali

Un'operazione è un lavoro logico eseguito da un'applicazione. Sono indicati nome, ora di avvio, durata, risultato e contesto dell'esecuzione, ad esempio nome utente, proprietà e risultato. Se l'operazione A è stata avviata dall'operazione B, l'operazione B è impostata come elemento padre per A. Un'operazione può avere un solo padre, ma può avere molte operazioni figlio. Per ulteriori informazioni sulle operazioni e la correlazione dei dati di telemetria, vedere Correlazione dei dati di telemetria di Application Insights.

In Application Insights .NET SDK l'operazione viene descritta dalla classe astratta OperationTelemetry e dai relativi discendenti RequestTelemetry e DependencyTelemetry.

Verifica delle operazioni in ingresso

Application Insights Web SDK raccoglie automaticamente richieste HTTP per le applicazioni ASP.NET eseguite in una pipeline IIS e tutte le applicazioni ASP.NET Core. Sono disponibili soluzioni supportate dalla community per altre piattaforme e altri framework. Se l'applicazione non è supportata dalle soluzioni standard o supportate dalla community, è possibile instrumentarla manualmente.

Un altro esempio che richiede la verifica personalizzata è offerto dal ruolo di lavoro che riceve gli elementi dalla coda. Per alcune code, la chiamata per aggiungere un messaggio a questa coda viene registrata come dipendenza. L'operazione generale che descrive l'elaborazione del messaggio non viene raccolta automaticamente.

Di seguito è illustrato come si può tenere traccia di queste operazioni.

A un livello elevato, l'attività consiste nel creare e impostare le proprietà note. Al termine dell'operazione, tenere traccia dei dati di telemetria. L'esempio seguente illustra questa attività.

Richiesta HTTP nell'app con self-hosting Owin

In questo esempio il contesto della traccia viene propagato in base al protocollo HTTP per la correlazione. Si deve prevedere di ricevere le intestazioni descritte qui.

Espandere per visualizzare il codice

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

Il protocollo HTTP per la correlazione dichiara inoltre l’intestazione . È omesso qui per motivi di semplicità.

Strumentazione della coda

Il contesto di traccia W3C e il protocollo HTTP per la correlazione consenta di passare i dettagli di correlazione con la richiesta HTTP, ma ogni protocollo di accodamento deve definire come passare gli stessi dettagli al messaggio della coda. Alcuni protocolli di coda, ad esempio AMQP, consentono di passare più metadati. Altri protocolli, ad esempio Azure Storage Queue, richiedono che il contesto venga codificato nel payload del messaggio.

Annotazioni

La traccia tra componenti non è ancora supportata per le code.

Con HTTP, se il produttore e l'utente inviano dati di telemetria a risorse di Application Insights diverse, l'esperienza di diagnostica delle transazioni e la mappa delle applicazioni mostrano le transazioni e mappano end-to-end. Per le code, questa funzionalità non è ancora supportata.

Coda del bus di servizio

Per informazioni sulla distribuzione della traccia e sulla correlazione, vedere la traccia distribuita e la correlazione tramite Azure Service Bus Messaging.

Azure Storage Queue

Nell'esempio seguente viene illustrato come tenere traccia delle operazioni della coda Azure Storage e correlare la telemetria tra il produttore, il consumatore e Azure Storage.

La coda di archiviazione ha un'API HTTP. Tutte le chiamate alla coda vengono tracciate dall'agente di raccolta di dipendenze Application Insights per le richieste HTTP. È configurato per impostazione predefinita nelle applicazioni ASP.NET e ASP.NET Core. Con altri tipi di applicazioni, vedere la documentazione delle applicazioni console.

Inoltre è possibile correlare l'ID operazione di Application Insights con l'ID di richiesta di Archiviazione. Per informazioni su come impostare e ottenere un client di richiesta di archiviazione e un ID richiesta server, vedere Monitor, diagnosticare e risolvere i problemi Azure Storage.

Accodare

Poiché le code di archiviazione di Azure supportano l'API HTTP, tutte le operazioni con la coda vengono automaticamente registrate da Application Insights. In molti casi, questa strumentazione dovrebbe essere sufficiente. Per correlare le tracce sul lato consumer con le tracce del producer, è necessario passare parte del contesto di correlazione in modo simile a quanto avviene nel protocollo HTTP per la correlazione.

Questo esempio illustra come tenere traccia dell'operazione . È possibile:

• Correlare gli eventuali tentativi, che hanno tutti un'operazione padre comune, ovvero . In caso contrario, vengono registrati come elementi figlio della richiesta in ingresso. Se sono presenti più richieste logiche per la coda, potrebbe risultare difficile trovare la chiamata che ha restituito i tentativi.
• Correlare i log di archiviazione (se e quando necessario) con i dati di telemetria di Application Insights.

L'operazione è l'elemento figlio di un'operazione padre. Un esempio è una richiesta HTTP in ingresso. La chiamata di dipendenza HTTP è l'elemento figlio dell'operazione e nipote della richiesta in ingresso.

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

Per ridurre la quantità di dati di telemetria segnalati dall'applicazione o per non tenere traccia dell'operazione per altri motivi, è possibile usare direttamente l'API :

• Creare (e avviare) un nuovo anziché avviare l'operazione Application Insights. Non è necessario assegnare alcuna proprietà ad essa, ad eccezione del nome dell'operazione.
• Serializzare nel payload dei messaggi invece di . È anche possibile usare .

Rimuovere dalla coda

In modo simile a , la richiesta HTTP effettiva per la coda di archiviazione viene automaticamente registrata da Application Insights. L'operazione tuttavia viene probabilmente eseguita nel contesto padre, ad esempio il contesto della richiesta in ingresso. Gli SDK di Application Insights correlano automaticamente tale operazione (e la parte HTTP) con la richiesta padre e gli altri dati di telemetria segnalati nello stesso ambito.

L'operazione è un'operazione complessa. L’SDK Application Insights tiene automaticamente traccia delle richieste HTTP. Tuttavia, non conosce il contesto di correlazione fino a quando non viene analizzato il messaggio. Non è possibile correlare la richiesta HTTP per ottenere il messaggio con il resto dei dati di telemetria, soprattutto quando vengono ricevuti più messaggi.

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

Processo

Nell'esempio seguente un messaggio in arrivo viene verificato in maniera simile a quanto avviene per una richiesta HTTP in ingresso:

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Analogamente, è possibile instrumentare le altre operazioni della coda. L'operazione di visualizzazione deve essere instrumentata in modo simile a quella di rimozione dalla coda. Non è necessario instrumentare operazioni di gestione della coda. Application Insights tiene traccia di operazioni come HTTP e nella maggior parte dei casi è sufficiente.

Quando si instrumenta l'eliminazione di un messaggio, assicurarsi di impostare gli identificatori delle operazioni (correlazione). In alternativa, è possibile usare l'API . Non è quindi necessario impostare gli identificatori delle operazioni negli elementi di telemetria perché Application Insights SDK esegue questa operazione automaticamente:

• Creare un nuovo oggetto dopo avere ottenuto un elemento dalla coda.
• Usare per correlare i log del consumer e del producer.
• Avviare il .
• Tenere traccia delle operazioni di rimozione dalla coda, elaborazione ed eliminazione usando gli helper . dallo stesso flusso di controllo asincrono (contesto di esecuzione). In questo modo la correlazione sarà corretta.
• Arrestare il .
• Usare o chiamare telemetry manualmente.

Tipi di dipendenza

Application Insights usa il tipo di dipendenza per personalizzare le esperienze dell'interfaccia utente. Per le code, riconosce i tipi seguenti di che migliorano l'esperienza di diagnostica delle transazioni:

• Azure queue per code di Archiviazione di Azure
• Azure Event Hubs per Azure Event Hubs
• Azure Service Bus per Azure Service Bus

Elaborazione in batch

Per alcune code, è possibile una rimozione dalla coda di più messaggi con una singola richiesta. L'elaborazione di tali messaggi è presumibilmente indipendente e appartiene a diverse operazioni logiche. Non è possibile correlare l'operazione a un determinato messaggio elaborato.

Ogni elaborazione dei messaggi deve essere eseguita nel proprio flusso di controllo asincrono. Per ulteriori informazioni, vedere la sezione Verifica delle dipendenze in uscita.

Attività in background a esecuzione prolungata

Alcune applicazioni avviano operazioni a esecuzione prolungata che possono essere causate dalle richieste degli utenti. Dal punto di vista della verifica/strumentazione, non c'è differenza dalla strumentazione delle richieste o delle dipendenze:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

In questo esempio crea e specifica il contesto di correlazione. Si supponga di avere un'operazione padre creata dalle richieste in ingresso che hanno pianificato l'operazione. , purché venga avviato nello stesso flusso di controllo asincrono di una richiesta in ingresso, viene correlato con tale operazione padre. e tutti gli elementi di telemetria annidati vengono automaticamente correlati alla richiesta che l'ha generato anche dopo la fine della richiesta.

Quando l'attività viene avviata dal thread in background a cui non sono associate operazioni (), non ha elementi padre. Tuttavia, può avere operazioni annidate. Tutti gli elementi di telemetria segnalati dall'attività sono correlati a creato in .

Verifica delle dipendenze in uscita

È possibile tenere traccia della propria tipologia di dipendenza o di operazioni non supportate da Application Insights.

Il metodo Enqueue nella coda Service Bus o la coda di archiviazione può fungere da esempi per il rilevamento personalizzato.

L'approccio generale per la verifica personalizzata delle dipendenze è:

• Chiamare il metodo (estensione) che riempie le proprietà necessarie per la correlazione e altre proprietà, come avvio, timestamp e durata.
• Impostare le altre proprietà personalizzate in , ad esempio nome e altri contesti necessari.
• Effettuare una chiamata di dipendenza e attendere.
• Al termine, arrestare l'operazione con .
• Gestire le eccezioni.

public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

L'eliminazione di un'operazione causa l'arresto dell'operazione, pertanto è possibile eseguirla invece di chiamare .

Avvertimento

In alcuni casi, un'eccezione non gestita potrebbe impedire la chiamata di , pertanto le operazioni potrebbero non essere rilevate.

Elaborazione e verifica di operazioni parallele

La chiamata arresta solo l'operazione avviata. Se l'operazione corrente in esecuzione non corrisponde all'operazione che si desidera arrestare, non esegue alcuna operazione. Questa situazione può verificarsi se si avviano più operazioni in parallelo nello stesso contesto di esecuzione.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Chiamare sempre ed elaborare l'operazione nello stesso metodo async per isolare le operazioni eseguite in parallelo. Se l'operazione è sincrona, o non asincrona, eseguire il wrapping del processo e verificare con .

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Operazioni di ApplicationInsights e System.Diagnostics.Activity

rappresenta il contesto di traccia distribuita e viene usato da framework e librerie per creare e propagare il contesto all'interno e all'esterno del processo e correlare gli elementi di telemetria. interagisce con come meccanismo di notifica tra il framework o la libreria per notificare eventi interessanti, ad esempio richieste in ingresso o in uscita ed eccezioni.

Le attività sono funzionalità di primo livello in Application Insights. Le dipendenze automatiche e la raccolta di richieste si basano principalmente su di essi insieme agli eventi . Se è stata creata nell'applicazione, non verrà creata l'Application Insights Telemetry. Application Insights deve ricevere eventi e conoscere i nomi degli eventi e i payload da convertire in dati di telemetria.

Ogni operazione di Application Insights (richiesta o dipendenza) comporta . Quando viene chiamato, crea sotto. è il modo consigliato per tenere traccia manualmente delle telemetrie di richiesta o dipendenza e assicurarsi che tutto sia correlato.

Counters

Application Insights supporta contatori di prestazioni e contatori di eventi. Questa guida offre una panoramica di entrambi, inclusi gli scopi, la configurazione e l'utilizzo nelle applicazioni .NET.

• i contatori Performance sono integrati nel sistema operativo Windows e offrono metriche predefinite, come l'utilizzo della CPU, il consumo di memoria e l'attività del disco. Questi contatori sono ideali per monitorare le metriche di prestazioni standard con una configurazione minima. Consentono di tenere traccia dell'utilizzo delle risorse o risolvere i colli di bottiglia a livello di sistema nelle applicazioni basate su Windows, ma non supportano metriche personalizzate specifiche dell'applicazione.

• i contatori Event funzionano su più piattaforme, tra cui Windows, Linux e macOS. Consentono agli sviluppatori di definire e monitorare metriche leggere e personalizzabili specifiche per le applicazioni, offrendo una maggiore flessibilità rispetto ai contatori di prestazioni. I contatori di eventi sono utili quando le metriche di sistema sono insufficienti o quando sono necessari dati di telemetria dettagliati in applicazioni multipiattaforma. Richiedono operazioni di implementazione e configurazione esplicite, che rendono l'installazione più impegnativa.

Contatori delle prestazioni

Windows fornisce vari contatori performance, ad esempio quelli usati per raccogliere statistiche sull'utilizzo del processore, della memoria e del disco. È anche possibile definire contatori delle prestazioni personalizzati.

L'applicazione supporta la raccolta dei contatori di prestazioni se viene eseguita in Internet Information Server (IIS) su un host locale o su una macchina virtuale con accesso amministrativo. Le applicazioni in esecuzione come Azure Web Apps non possono accedere direttamente ai contatori delle prestazioni, ma Application Insights raccoglie un subset di contatori disponibili.

Suggerimento

Come per altre metriche, è possibile impostare un avviso per segnalare quando un contatore supera un limite specificato. Per impostare un avviso, aprire il riquadro Avvisi e selezionare Aggiungi avviso.

Prerequisiti

Concedere all'account del servizio pool di app l'autorizzazione per monitorare i contatori delle prestazioni aggiungendolo al gruppo Utenti di monitoraggio delle prestazioni.

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Visualizzare i contatori

Nel riquadro Metrica è riportato un set predefinito di contatori delle prestazioni.

ASP.NET

Contatori predefiniti per ASP.NET applicazioni Web:

• % Processo\Tempo processore
• % Processo\Tempo normalizzato processore
• Memoria\Byte disponibili
• Richieste ASP.NET/sec
• Eccezioni lanciate dal Common Language Runtime (CLR) .NET al secondo
• Tempo di esecuzione delle richieste delle applicazioni ASP.NET
• Processo\Byte privati
• Processo\Byte dati IO/sec
• Applicazioni ASP.NET: Richieste nella coda dell'applicazione
• Processor(_Total)\% tempo processore

ASP.NET Core

Contatori predefiniti per le applicazioni Web ASP.NET Core:

• % Processo\Tempo processore
• % Processo\Tempo normalizzato processore
• Memoria\Byte disponibili
• Processo\Byte privati
• Processo\Byte dati IO/sec
• Processor(_Total)\% tempo processore

Annotazioni

Il supporto per i contatori delle prestazioni in ASP.NET Core è limitato:

• SDK versioni 2.4.1 e successive raccolgono i contatori delle prestazioni se l'applicazione è in esecuzione in Azure Web Apps (Windows).
• Le versioni SDK 2.7.1 e successive raccolgono i contatori delle prestazioni se l'applicazione è in esecuzione in Windows e supporta NETSTANDARD2.0 o versioni successive.
• Per le applicazioni destinate a .NET Framework, tutte le versioni dell'SDK supportano i contatori delle prestazioni.
• Le versioni SDK 2.8.0 e successive supportano il contatore di CPU/memoria in Linux. Linux non supporta nessun altro contatore. Per ottenere i contatori di sistema in Linux (e altri ambienti non Windows), usare i contatori degli eventi.

Aggiungere contatori

Se il contatore delle prestazioni desiderato non è incluso nell'elenco delle metriche, è possibile aggiungerlo.

ASP.NET

Opzione 1: Configurazione in ApplicationInsights.config

1. È possibile identificare i contatori disponibili nel server usando questo comando di PowerShell nel server locale:

   Get-Counter -ListSet *
   

   Per altre informazioni, vedere .

2. Aprire .

   Se Application Insights è stato aggiunto all'app durante lo sviluppo:

   1. Modificare nel progetto.
   2. Ridistribuirlo nei server.

3. Modificare la direttiva dell'agente di raccolta delle prestazioni:

   
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <Counters>
           <Add PerformanceCounter="\Objects\Processes"/>
           <Add PerformanceCounter="\Sales(photo)\# Items Sold" ReportAs="Photo sales"/>
         </Counters>
       </Add>
   

È possibile acquisire i contatori standard e quelli implementati autonomamente. \Objects\Processes è un esempio di contatore standard disponibile in tutti i sistemi Windows. è un esempio di contatore personalizzato che può essere implementato in un servizio Web.

Il formato è oppure, per categorie non associate a istanze, solo .

Il parametro è obbligatorio per i nomi dei contatori che non corrispondono a .

Se si specifica un'istanza, questa diventa una dimensione della metrica indicata.

Opzione 2: Configurazione nel codice

Vedere la sezione seguente.

ASP.NET Core

Configurare secondo il metodo in :

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();

Raccogliere contatori delle prestazioni nel codice per applicazioni Web ASP.NET o applicazioni console .NET/.NET Core

Per raccogliere i contatori delle prestazioni di sistema e inviarli ad Application Insights, è possibile adattare il frammento di codice seguente:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

In alternativa, è possibile eseguire la stessa operazione con le metriche personalizzate create:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Contatori delle prestazioni per le applicazioni in esecuzione in contenitori di Azure Web Apps e Windows in Azure App Service

Sia ASP.NET che le applicazioni ASP.NET Core distribuite in Azure Web Apps vengono eseguite in un ambiente sandbox speciale. Le applicazioni distribuite in Azure App Service possono usare un contenitore Windows o essere ospitate in un ambiente sandbox. Se l'applicazione viene distribuita in un contenitore Windows, tutti i contatori delle prestazioni standard sono disponibili nell'immagine del contenitore.

L'ambiente sandbox non consente l'accesso diretto ai contatori delle prestazioni di sistema. Tuttavia, un subset limitato di contatori viene esposto come variabile di ambiente, come descritto in Contatori delle prestazioni esposte come variabili di ambiente. In questo ambiente è disponibile solo un subset di contatori.

Application Insights SDK per ASP.NET e ASP.NET Core rileva se il codice viene distribuito in un'app Web o in un contenitore non Windows. Il rilevamento determina se raccoglie i contatori delle prestazioni in un ambiente sandbox o usa il meccanismo di raccolta standard quando è ospitato in un contenitore Windows o in una macchina virtuale.

Query di Log Analytics per i contatori delle prestazioni

È possibile cercare e visualizzare i report dei contatori delle prestazioni in Log Analytics.

Lo schema performanceCounters espone , il nome e il nome per ogni contatore delle prestazioni. Nei dati di telemetria per ogni applicazione vengono visualizzati solo i contatori per l'applicazione specifica. Ad esempio, per visualizzare quali contatori sono disponibili:

performanceCounters | summarize count(), avg(value) by category, instance, counter

Qui fa riferimento all'istanza del contatore delle prestazioni e non all'istanza del ruolo o del server. Solitamente, il nome dell'istanza del contatore delle prestazioni segmenta i contatori, ad esempio il tempo del processore, in base al nome del processo o dell'applicazione.

Per ottenere un grafico della memoria disponibile nel periodo recente:

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

Come altri dati di telemetria, performanceCounters contiene anche una colonna che indica l'identità dell'istanza del server host in cui viene eseguita l'app. Ad esempio, per confrontare le prestazioni dell'applicazione su computer diversi:

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

Domande frequenti sui contatori di prestazioni

Per consultare le domande frequenti, vedere Domande frequenti sui contatori di prestazioni.

Contatori di eventi

EventCounter è un meccanismo di .NET/.NET Core per pubblicare e utilizzare contatori o statistiche. EventCounters sono supportati in tutte le piattaforme del sistema operativo: Windows, Linux e macOS. Può essere considerato un equivalente multipiattaforma per il PerformanceCounters supportato solo nei sistemi Windows.

Anche se gli utenti possono pubblicare qualsiasi contatore di eventi personalizzato per soddisfare le proprie esigenze, .NET pubblica un set di questi contatori per impostazione predefinita. Questo documento illustra i passaggi necessari per raccogliere e visualizzare i contatori degli eventi (definiti dal sistema o definiti dall'utente) in Azure Application Insights.

Suggerimento

Come per altre metriche, è possibile impostare un avviso per segnalare quando un contatore supera un limite specificato. Per impostare un avviso, aprire il riquadro Avvisi e selezionare Aggiungi avviso.

Uso di Application Insights per raccogliere EventCounters

Application Insights supporta la raccolta di con , che fa parte del pacchetto NuGet Microsoft.ApplicationInsights.EventCounterCollector rilasciato di recente. viene abilitato automaticamente quando si usa AspNetCore o WorkerService. raccoglie i contatori con una frequenza di raccolta non configurabile pari a 60 secondi. Non sono richieste autorizzazioni speciali per raccogliere EventCounters. Per le applicazioni ASP.NET Core, è necessario aggiungere anche il pacchetto Microsoft.ApplicationInsights.AspNetCore.

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Contatori predefiniti raccolti

A partire dalla versione 2.15.0 di AspNetCore SDK o WorkerService SDK, i contatori non vengono raccolti per impostazione predefinita. Il modulo stesso è abilitato, in questo modo gli utenti possono aggiungere i contatori desiderati per raccoglierli.

Per consultare l'elenco dei contatori noti pubblicati dal Runtime .NET, vedere il documento Contatori Disponibili.

Personalizzazione dei contatori da raccogliere

L'esempio seguente illustra come aggiungere/rimuovere contatori. Questa personalizzazione viene eseguita come parte della configurazione del servizio dell'applicazione dopo l'abilitazione della telemetria di Application Insights con o . Di seguito è riportato un codice di esempio di un'applicazione ASP.NET Core. Per altri tipi di applicazioni, vedere Configurare i moduli di telemetria.

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );

Disabilitazione del modulo di raccolta EventCounter

può essere disabilitato utilizzando .

Nell'esempio seguente viene usato ASP.NET Core SDK.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Un approccio simile può essere usato anche per Worker Service SDK, ma lo spazio dei nomi deve essere modificato come illustrato nell'esempio seguente.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Query di Log Analytics per i contatori degli eventi

È possibile cercare e visualizzare report dei contatori di eventi in Log Analytics, nella tabella customMetrics.

Eseguire ad esempio la query seguente per visualizzare i contatori raccolti e disponibili per le query:

customMetrics | summarize avg(value) by name

Per ottenere un grafico di un contatore specifico, ad esempio , nel periodo recente, eseguire la query seguente.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

Come altri dati di telemetria, customMetrics contiene anche una colonna che indica l'identità dell'istanza del server host in cui viene eseguita l'app. La query precedente mostra il valore del contatore per ogni istanza e può essere usata per confrontare le prestazioni di diverse istanze del server.

Domande frequenti sui contatore di eventi

Per consultare le domande frequenti, vedere Domande frequenti sui contatori di eventi.

Raccolta di snapshot

Per informazioni su come configurare la raccolta snapshot per le applicazioni ASP.NET e ASP.NET Core, vedere Enable Snapshot Debugger for .NET apps in Azure Service Fabric, Cloud Services e Virtual Machines.

Contenuto della sezione

• Metriche in tempo reale
• Traccia distribuita
• Dipendenze
• Metriche estese
• TelemetryClient API

Metriche in tempo reale

È possibile usare le metriche attive per verificare rapidamente se il monitoraggio delle applicazioni con Application Insights è configurato correttamente. La visualizzazione dei dati di telemetria può richiedere alcuni minuti nel portale di Azure, ma il riquadro delle metriche attive mostra l'utilizzo della CPU del processo in esecuzione quasi in tempo reale. Può anche visualizzare altri dati di telemetria, ad esempio richieste, dipendenze e tracce.

Abilitare le metriche in tempo reale

1. Per abilitare l'invio di metriche in tempo reale dall'app a Azure, usare setSendLiveMetrics(true).

2. Aprire la risorsa di Application Insights per l'applicazione nel portale Azure. Selezionare Live Metrics disponibile in Analisi dei problemi nel menu a sinistra.

3. Secure the control channel abilitando Microsoft Entra authentication se si usano filtri personalizzati.

   Annotazioni

   Attualmente, i filtri delle metriche live nel portale non sono supportati.

Funzionalità supportate

Metriche di base	Metriche delle prestazioni	Filtro personalizzato	Telemetria di esempio	Suddivisione della CPU per processo
Supportata (V1.3.0 e successive)	Supportata (V1.3.0 e successive)	Supportata (V1.3.0 e successive)	Supportata (V1.3.0 e successive)	Non supportato

Le metriche di base includono richiesta, dipendenza e frequenza delle eccezioni. Le metriche delle prestazioni (contatori delle prestazioni) includono memoria e CPU. I dati di telemetria di esempio mostrano un flusso di informazioni dettagliate per le richieste non riuscite e le dipendenze, le eccezioni, gli eventi e le tracce.

Tracciamento distribuito

Le architetture moderne di cloud e microservizi hanno abilitato servizi semplici e indipendenti che riducono i costi aumentando la disponibilità e la velocità effettiva. Tuttavia, ha reso i sistemi generali più difficili da ragionare e eseguire il debug. Il tracciamento distribuito risolve questo problema fornendo un profiler delle prestazioni che funziona come le pile di chiamate nelle architetture cloud e microservizi.

Azure Monitor offre due esperienze per l'utilizzo di dati di traccia distribuiti: la diagnostica transaction per una singola transazione/richiesta e la mappa application per mostrare l'interazione dei sistemi.

Application Insights può monitorare ogni componente separatamente e rilevare quale componente è responsabile di errori o riduzione delle prestazioni usando la correlazione di telemetria distribuita. Questo articolo illustra il modello di dati, le tecniche di propagazione del contesto, i protocolli e l'implementazione di tattiche di correlazione su linguaggi e piattaforme diversi usati da Application Insights.

Abilitare la traccia distribuita tramite Application Insights utilizzando l'autoinstrumentazione o gli SDK

Gli agenti e gli SDK di Application Insights per .NET, .NET Core, Java, Node.jse JavaScript supportano la traccia distribuita in modo nativo.

Dopo avere installato e configurato la versione corretta di Application Insights SDK, le informazioni di traccia vengono raccolte automaticamente per le librerie, le tecnologie e i framework più diffusi da agenti di raccolta delle dipendenze dell'SDK automatici. L'elenco completo delle tecnologie supportate è disponibile nella documentazione sulla raccolta automatica delle dipendenze.

Qualsiasi tecnologia può anche essere rilevata manualmente con una chiamata a TrackDependency in TelemetryClient.

Modello di dati per la correlazione dei dati di telemetria

Application Insights definisce un modello di dati per la correlazione di dati di telemetria distribuita. Per associare i dati di telemetria a un'operazione logica, ogni elemento di telemetria ha un campo di contesto denominato . Ogni elemento di telemetria nella traccia distribuita condivide questo identificatore. Pertanto, anche se si perdono i dati di telemetria da un singolo livello, è comunque possibile associare i dati di telemetria segnalati da altri componenti.

Un'operazione logica distribuita è in genere costituita da un set di operazioni più piccole elaborate da uno dei componenti. I dati di telemetria delle richieste definiscono queste operazioni. Ogni elemento di telemetria della richiesta ha il proprio , che lo identifica in modo globale e univoco. E tutti gli elementi di telemetria, ad esempio tracce ed eccezioni, associati alla richiesta devono impostare su il valore della richiesta .

La telemetria delle dipendenze rappresenta ogni operazione in uscita, ad esempio una chiamata HTTP a un altro componente. Definisce anche il proprio , un elemento univoco a livello globale. La telemetria delle richieste, avviata dalla chiamata di dipendenza, usa questo come .

È possibile compilare una vista dell'operazione logica distribuita usando , e con . Questi campi definiscono anche l'ordine di causalità delle chiamate di telemetria.

In un ambiente di microservizi, le tracce dei componenti possono passare a elementi di archiviazione diversi. Ogni componente può avere un proprio connection string in Application Insights. Per ottenere dati di telemetria per l'operazione logica, Application Insights esegue query sui dati da ogni elemento di archiviazione.

Quando il numero di elementi di archiviazione è grande, è necessario un suggerimento su dove cercare successivamente. Il modello di dati di Application Insights definisce due campi per risolvere questo problema: e . Il primo campo identifica il componente che ha avviato la richiesta di dipendenza. Il secondo campo identifica il componente che ha restituito la risposta della chiamata di dipendenza.

Per informazioni sull'esecuzione di query da più istanze diverse, vedere Eseguire query sui dati in aree di lavoro, applicazioni e risorse Log Analytics in Monitoraggio di Azure.

Example

Di seguito è descritto un esempio. Un'applicazione denominata Stock Prices mostra il prezzo di mercato corrente di un titolo usando un'API esterna denominata Stock. L'applicazione Prezzi azionari ha una pagina denominata Pagina stock visualizzata dal Web browser client tramite . L'applicazione esegue una query sull'API Stock usando la chiamata HTTP .

È possibile analizzare i dati di telemetria risultanti eseguendo una query:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Nei risultati tutti gli elementi di telemetria condividono la radice . Quando viene effettuata una chiamata Ajax dalla pagina, viene assegnato un nuovo ID univoco () ai dati di telemetria delle dipendenze e l'ID di pageView viene usato come . La richiesta del server usa quindi l'ID Ajax come .

tipo di elemento	nome	Documento d'identità	operation_ParentId	operation_Id
pageView	Pagina delle scorte	STYz		STYz
dipendenza	GET /Home/Stock	qJSXU	STYz	STYz
request	GET /Home/Stock	KqKwlrSt9PA=	qJSXU	STYz
dipendenza	GET /api/stock/value # Ottieni il valore d'inventario tramite API	bBrf2L7mm2g=	KqKwlrSt9PA=	STYz

Quando la chiamata viene effettuata a un servizio esterno, è necessario conoscere l'identità del server in modo da poter impostare il campo in modo appropriato. Quando il servizio esterno non supporta il monitoraggio, viene impostato sul nome host del servizio. Un esempio è . Tuttavia, se il servizio si identifica restituendo un'intestazione HTTP predefinita, contiene l'identità del servizio che consente ad Application Insights di compilare una traccia distribuita eseguendo query sui dati di telemetria da tale servizio.

Intestazioni di correlazione utilizzando W3C TraceContext

Application Insights esegue la transizione a W3C Trace-Context, che definisce:

• : Trasporta l'ID operativo univoco globale e l'identificatore univoco della chiamata.
• : contiene il contesto di tracciamento specifico del sistema.

La versione più recente di Application Insights SDK supporta il protocollo Trace-Context, ma potrebbe essere necessario acconsentire esplicitamente. La retrocompatibilità con il protocollo di correlazione precedente supportato dall'SDK di Application Insights è mantenuta.

Il protocollo HTTP di correlazione, detto anche Request-Id, è deprecato. Questo protocollo definisce due intestazioni:

• : porta l'ID univoco globale della chiamata.
• : contiene la raccolta di coppie nome-valore delle proprietà di tracciamento distribuito.

Application Insights definisce anche l'estensione per il protocollo HTTP di correlazione. Usa le coppie nome-valore per propagare la raccolta di proprietà usate dal chiamante o dal destinatario della chiamata. Il SDK di Application Insights utilizza questo header per impostare i campi e .

I modelli di dati W3C Trace-Context e Application Insights sono mappati nel modo seguente:

Approfondimenti sulle Applicazioni	W3C TraceContext
di e	parent-id
Operation_Id	trace-id
Operation_ParentId	parent-id dell'intervallo padre di questo intervallo. Questo campo deve essere vuoto se è un intervallo radice.

Per altre informazioni, vedere Modello di dati di telemetria di Application Insights.

Abilitare il supporto per la traccia distribuita W3C

Per impostazione predefinita, l'SDK invia intestazioni riconosciute da altre applicazioni o servizi instrumentati con Application Insights SDK. È possibile abilitare l'invio e la ricezione di intestazioni del Contesto di traccia W3C, oltre alle intestazioni di IA esistenti. In questo modo, la correlazione con i servizi legacy esistenti non sarà interrotta.

L'abilitazione delle intestazioni W3C consente all'app di correlarsi con altri servizi non instrumentati con Application Insights, ma che adottano questo standard W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

Dipendenze

Dipendenze rilevate automaticamente

Un elenco dei moduli attualmente supportati più recenti viene mantenuto nei Server di pubblicazione del canale di diagnostica.

Come funziona il monitoraggio automatico delle dipendenze?

• La strumentazione del bytecode viene applicata ai metodi selezionati utilizzando InstrumentationEngine e può essere abilitata tramite StatusMonitor o l'estensione di Application Insights per Servizio app di Azure.

• EventSource i callback vengono usati per acquisire dati di telemetria dalle librerie .NET che generano eventi strutturati.

• DiagnosticSource i callback vengono usati nei più recenti SDK .NET e .NET Core per raccogliere dati di telemetria dalle librerie che supportano il tracciamento distribuito.

Tenere traccia manualmente delle dipendenze

Per istruzioni, vedere Tenere traccia delle dipendenze.

Metriche estese

Annotazioni

La possibilità di inviare metriche native estese è stata aggiunta nella versione 1.4.0.

Per abilitare l'invio di metriche native estese dall'app a Azure, installare il pacchetto di metriche native separato. L'SDK si carica automaticamente quando viene installato e inizia a raccogliere le metriche native Node.js.

npm install applicationinsights-native-metrics

Attualmente, il pacchetto di metriche native esegue la raccolta automatica del tempo della CPU di Garbage Collection, dei tick del ciclo di eventi e dell'utilizzo dell'heap:

• Gestione dei rifiuti: La quantità di tempo della CPU impiegato per ogni tipo di gestione dei rifiuti e il numero di volte in cui ciascun tipo si verifica.
• Ciclo di eventi: numero di tick che si sono verificati e tempo della CPU impiegato in totale.
• Heap o nonheap: Quanto dell'utilizzo della memoria dell'app è nell'heap o nel nonheap.

API TelemetryClient

Per una descrizione completa dell'API TelemetryClient, vedere API di Application Insights per metriche ed eventi personalizzati.

Con la libreria client di Application Insights per Node.js è possibile tenere traccia di qualsiasi richiesta, evento, metrica o eccezione. L'esempio di codice seguente illustra alcune API che è possibile usare:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Tenere traccia delle dipendenze

Usare il codice seguente per tenere traccia delle dipendenze:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Un'utilità di esempio che usa per misurare il tempo necessario per la pianificazione del ciclo di eventi:

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Aggiungi una proprietà personalizzata a tutti gli eventi

Usare il codice seguente per aggiungere una proprietà personalizzata a tutti gli eventi:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Tenere traccia delle richieste HTTP GET

Usare il codice seguente per tenere traccia manualmente delle richieste HTTP GET:

Annotazioni

• Tutte le richieste vengono rilevate per impostazione predefinita. Per disabilitare la raccolta automatica, chiamare prima di chiamare .
• Le richieste API di recupero nativo non vengono rilevate automaticamente da Application Insights classico; è necessario tenere traccia delle dipendenze manuali.

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

In alternativa, è possibile rilevare le richieste usando il metodo :

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Tenere traccia del tempo di avvio del server

Usare il codice seguente per tenere traccia dell'ora di avvio del server:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Flush

Per impostazione predefinita, i dati di telemetria vengono memorizzati nel buffer per 15 secondi prima dell'invio al server di inserimento. Se l'applicazione ha una durata breve, ad esempio uno strumento dell'interfaccia della riga di comando, potrebbe essere necessario scaricare manualmente i dati di telemetria memorizzati nel buffer quando l'applicazione termina, usando .

Se l'SDK rileva un arresto anomalo dell'applicazione, chiama lo scaricamento per l'utente usando . Con l'opzione di svuotamento , si presume che l'applicazione sia in stato anomalo e non sia adatta per inviare telemetria. L'SDK salva invece tutti i dati di telemetria memorizzati nel buffer nell'archiviazione permanente e consente all'applicazione di essere terminata. Quando si riavvia, l'applicazione tenta di inviare tutti i dati di telemetria salvati nell'archiviazione permanente.

Elaborazione e filtro dei dati di telemetria

.NET

Contenuto della sezione

• Filtrare e pre-elaborare i dati di telemetria
• Inizializzatori di telemetria
• Processore di telemetria
• Campionamento
• Arricchire i dati tramite HTTP

Filtrare e pre-elaborare i dati di telemetria

È possibile scrivere codice per filtrare, modificare o arricchire i dati di telemetria prima dell'invio dall'SDK. L'elaborazione include i dati inviati dai moduli di telemetria standard, ad esempio la raccolta di richieste HTTP e la raccolta delle dipendenze.

• Il filtro può modificare o rimuovere i dati di telemetria prima che vengano inviati dall'SDK implementando . Ad esempio, è possibile ridurre il volume di dati di telemetria escludendo le richieste dai robot. A differenza del campionamento, si ha il controllo completo su ciò che viene inviato o rimosso, ma influisce su qualsiasi metrica basata su log aggregati. A seconda della modalità di eliminazione degli elementi, è anche possibile perdere la possibilità di spostarsi tra gli elementi correlati.

• Aggiungere o modificare proprietà a tutti i dati di telemetria inviati dall'app implementando un oggetto . Ad esempio, è possibile aggiungere valori calcolati o numeri di versione in base ai quali filtrare i dati nel portale.

• Il campionamento riduce il volume di dati di telemetria senza influire sulle statistiche. Mantiene insieme i punti dati correlati in modo che sia possibile spostarsi tra di essi durante la diagnosi di un problema. Nel portale i conteggi totali vengono moltiplicati per compensare il campionamento.

Annotazioni

L'API SDK viene usata per inviare metriche ed eventi personalizzati.

Filtraggio

Questa tecnica consente di controllare direttamente gli elementi inclusi o esclusi dal flusso di telemetria. Il filtro può essere usato per eliminare gli elementi di telemetria dall'invio ad Application Insights. È possibile usare il filtro con il campionamento o separatamente.

Per filtrare i dati di telemetria, scrivere un processore di telemetria e registrarlo con . Tutti i dati di telemetria passano attraverso il processore. È possibile scegliere di rilasciarlo dal flusso o assegnarlo al processore successivo nella catena. I dati di telemetria dai moduli standard, come il collettore di richieste HTTP e il collettore di dipendenze, e la telemetria che hai tracciato personalmente sono inclusi. Ad esempio, è possibile filtrare i dati di telemetria relativi alle richieste dei robot o alle chiamate di dipendenza riuscite.

Avvertimento

Filtrare i dati di telemetria inviati dall'SDK usando processori può asimmetriare le statistiche visualizzate nel portale e rendere difficile seguire gli elementi correlati.

Prendere invece in considerazione l'uso del campionamento.

ITelemetryProcessor e ITelemetryInitializer

Qual è la differenza tra processori di telemetria e inizializzatori di telemetria?

• Ci sono alcune sovrapposizioni in ciò che è possibile fare con loro. Entrambi possono essere usati per aggiungere o modificare le proprietà dei dati di telemetria, anche se è consigliabile usare gli inizializzatori a tale scopo.
• Gli inizializzatori di telemetria vengono sempre eseguiti prima dei processori di telemetria.
• Gli inizializzatori di telemetria possono essere chiamati più volte. Per convenzione, non impostano alcuna proprietà già impostata.
• I processori di telemetria consentono di sostituire o rimuovere completamente un elemento di telemetria.
• Tutti gli inizializzatori di telemetria registrati vengono chiamati per ogni elemento di telemetria. Per i processori di telemetria, SDK garantisce la chiamata al primo processore di telemetria. Se il resto dei processori viene chiamato o meno viene deciso dai processori di telemetria precedenti.
• Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con più proprietà o eseguire l'override di uno esistente. Usare un processore di telemetria per filtrare i dati di telemetria.

Aggiungere/modificare le proprietà

Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà di telemetria impostate dai moduli di telemetria standard.

Ad esempio, Application Insights per un pacchetto Web raccoglie i dati di telemetria sulle richieste HTTP. Per impostazione predefinita, contrassegna qualsiasi richiesta con un codice di risposta =400 come non riuscita. Se invece si vuole considerare 400 come un risultato positivo, è possibile fornire un inizializzatore di telemetria che imposti la proprietà Success.

Se si specifica un inizializzatore di telemetria, viene chiamato ogni volta che viene chiamato uno dei metodi Track*(). Questo inizializzatore include metodi chiamati dai moduli di telemetria standard. Per convenzione, questi moduli non impostano alcuna proprietà già impostata da un inizializzatore. Gli inizializzatori di telemetria vengono chiamati prima di chiamare i processori di telemetria, quindi tutti gli arricchimenti eseguiti dagli inizializzatori sono visibili ai processori.

Inizializzatori di telemetria

Per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà di telemetria impostate dai moduli di telemetria standard, usare gli inizializzatori di telemetria.

Gli inizializzatori di telemetria impostano proprietà di contesto che vengono inviate insieme ad ogni elemento di telemetria. È possibile scrivere inizializzatori personalizzati per impostare le proprietà del contesto.

Gli inizializzatori standard sono tutti impostati dal Web o dai pacchetti NuGet WindowsServer:

Inizializzatore	Description
AccountIdTelemetryInitializer	Imposta la proprietà .
AuthenticatedUserIdTelemetryInitializer	Imposta la proprietà come impostata da JavaScript SDK.
AzureRoleEnvironmentTelemetryInitializer	Aggiorna le proprietà RoleName e RoleInstance del contesto Device per tutti gli elementi di telemetria con informazioni estratte dall'ambiente di runtime Azure.
BuildInfoConfigComponentVersionTelemetryInitializer	Aggiorna la proprietà del contesto per tutti gli elementi di telemetria con il valore estratto dal file prodotto dalla compilazione MS.
ClientIpHeaderTelemetryInitializer	Aggiorna la proprietà del contesto di tutti gli elementi di telemetria in base all'intestazione HTTP della richiesta.
DeviceTelemetryInitializer	Aggiorna le proprietà seguenti del contesto per tutti gli elementi di telemetria: • viene impostato su . • viene impostato sul nome di dominio del computer in cui è in esecuzione l'applicazione Web. • viene impostato sul valore estratto dal campo tramite WMI. • viene impostato sul valore estratto dal campo tramite WMI. • viene impostato sul valore estratto dalla proprietà . • viene impostato sul nome della proprietà .
DomainNameRoleInstanceTelemetryInitializer	Aggiorna la proprietà del contesto per tutti gli elementi di telemetria con il nome di dominio del computer in cui è in esecuzione l'applicazione Web.
OperationNameTelemetryInitializer	Aggiorna la proprietà Name di RequestTelemetry e la proprietà Name del contesto Operation di tutti gli elementi di telemetria basati sul metodo HTTP e i nomi del controller ASP.NET MVC e dell'azione richiamati per elaborare la richiesta.
o	Aggiorna la proprietà di contesto di tutti gli elementi di telemetria rilevati durante la gestione di una richiesta con il generato automaticamente.
SessionTelemetryInitializer	Aggiorna la proprietà del contesto per tutti gli elementi di telemetria con il valore estratto dal cookie generato dal codice di strumentazione JavaScript di in esecuzione nel browser dell'utente.
o	Aggiorna le proprietà di contesto , e di tutti gli elementi di telemetria rilevati durante la gestione di una richiesta da un'origine sintetica, ad esempio un test di disponibilità o un robot del motore di ricerca. Per impostazione predefinita, esplora metriche non mostra la telemetria sintetica. imposta le proprietà di identificazione delle richieste.
UserTelemetryInitializer	Aggiorna le proprietà e del contesto per tutti gli elementi di telemetria con i valori estratti dal cookie generato dal codice di strumentazione JavaScript di Application Insights in esecuzione nel browser dell'utente.
WebTestTelemetryInitializer	Imposta l'ID utente, l'ID di sessione e le proprietà di origine sintetica per le richieste HTTP che provengono da test di disponibilità. imposta le proprietà di identificazione delle richieste.

Annotazioni

Per le applicazioni .NET in esecuzione in Azure Service Fabric, è possibile includere il pacchetto NuGet Microsoft.ApplicationInsights.ServiceFabric. Questo pacchetto include una proprietà , che aggiunge le proprietà di Service Fabric per gli elementi di telemetria. Per altre informazioni, vedere la pagina GitHub sulle proprietà aggiunte da questo pacchetto NuGet.

Aggiungere ITelemetryInitializer

Questo blog descrive un progetto per diagnosticare i problemi di dipendenza inviando automaticamente ping regolari alle dipendenze.

1. Definire l'inizializzatore

   using System;
   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.DataContracts;
   using Microsoft.ApplicationInsights.Extensibility;
   
   namespace MvcWebRole.Telemetry
   {
     /*
      * Custom TelemetryInitializer that overrides the default SDK
      * behavior of treating response codes >= 400 as failed requests
      *
      */
       public class MyTelemetryInitializer : ITelemetryInitializer
       {
           public void Initialize(ITelemetry telemetry)
           {
               var requestTelemetry = telemetry as RequestTelemetry;
               // Is this a TrackRequest() ?
               if (requestTelemetry == null) return;
               int code;
               bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
               if (!parsed) return;
               if (code >= 400 && code < 500)
               {
                   // If we set the Success property, the SDK won't change it:
                   requestTelemetry.Success = true;
   
                   // Allow us to filter these requests in the portal:
                   requestTelemetry.Properties["Overridden400s"] = "true";
               }
               // else leave the SDK to set the Success property
           }
       }
   }
   

2. Caricare l'inizializzatore

ASP.NET

Opzione 1: Configurazione nel codice

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

Opzione 2: Configurazione in ApplicationInsights.config

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

Per altre informazioni , vedere questo esempio.

Annotazioni

Assicurarsi che il fileapplicationinsights.config si trova nella directory di output e contenga eventuali modifiche recenti.

ASP.NET Core

L'aggiunta di un inizializzatore tramite ApplicationInsights.config o TelemetryConfiguration.Active non è valida per le applicazioni ASP.NET Core.

Per le app scritte con ASP.NET Core, l'aggiunta di un nuovo inizializzatore di telemetria viene eseguita aggiungendola al contenitore DependencyInjection, come illustrato. Eseguire questo passaggio nel metodo .

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Annotazioni

funziona per inizializzatori semplici. Per gli altri, è necessario .

Rimuovere gli inizializzatori di telemetria

Per impostazione predefinita, gli inizializzatori di telemetria sono presenti. Per rimuovere tutti gli inizializzatori di telemetria o alcuni specifici, usare il codice di esempio seguente dopo la chiamata di .

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

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

var app = builder.Build();

Servizio del ruolo di lavoro

L'aggiunta di un inizializzatore tramite o non è valida per Worker Service SDK.

Per le app scritte utilizzando il Worker Service, un nuovo inizializzatore di telemetria viene aggiunto al contenitore, come illustrato. Eseguire questo passaggio nel metodo .

    using Microsoft.ApplicationInsights.Extensibility;

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

Rimuovere gli inizializzatori di telemetria

Gli inizializzatori di telemetria sono presenti per impostazione predefinita. Per rimuovere tutti gli inizializzatori di telemetria o alcuni specifici, usare il codice di esempio seguente dopo la chiamata di .

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

Esempio di Inizializzatori di Telemetria

Aggiungere una proprietà personalizzata

L'inizializzatore di esempio seguente aggiunge una proprietà personalizzata a ogni telemetria rilevata.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Aggiungere un nome del ruolo cloud e un'istanza del ruolo cloud

Passaggio 1: Scrivere un TelemetryInitializer personalizzato

L'inizializzatore di esempio seguente imposta il nome del ruolo cloud su ogni telemetria rilevata.

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

namespace CustomInitializer.Telemetry
{
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
            {
                //set custom role name here
                telemetry.Context.Cloud.RoleName = "Custom RoleName";
                telemetry.Context.Cloud.RoleInstance = "Custom RoleInstance";
            }
        }
    }
}

Passaggio 2: Caricare un inizializzatore in TelemetryConfiguration

ASP.NET

Nel file ApplicationInsights.config :

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

Un metodo alternativo per le web app ASP.NET consiste nel creare un'istanza dell'inizializzatore nel codice. L'esempio seguente mostra il codice nel file Global.aspx.cs :

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }

ASP.NET Core

Per aggiungere una nuova istanza di , la si aggiunge al contenitore di Inserimento delle dipendenze. L'esempio seguente illustra questo approccio. Aggiungere questo codice nel metodo della classe.

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Controllare l'indirizzo IP client usato per i mapping di georilevazione

L'inizializzatore di esempio seguente imposta l'IP client, usato per la mappatura della geolocalizzazione al posto dell'indirizzo IP del socket client, durante l'acquisizione di telemetria.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

Processori di telemetria

I processori di telemetria possono filtrare e modificare ciascun elemento di telemetria prima di inviarlo dal SDK al portale.

Implementare

I processori di telemetria costruiscono una catena di elaborazione. Quando si istanzia un processore di telemetria, si ottiene un riferimento al processore successivo nella catena. Quando un punto dati di telemetria viene passato al metodo di processo, esegue il lavoro e quindi chiama (o non chiama) il processore di telemetria successivo nella catena.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.DataContracts;

public class SuccessfulDependencyFilter : ITelemetryProcessor
{
    private ITelemetryProcessor Next { get; set; }

    // next will point to the next TelemetryProcessor in the chain.
    public SuccessfulDependencyFilter(ITelemetryProcessor next)
    {
        this.Next = next;
    }

    public void Process(ITelemetry item)
    {
        // To filter out an item, return without calling the next processor.
        if (!OKtoSend(item)) { return; }

        this.Next.Process(item);
    }

    // Example: replace with your own criteria.
    private bool OKtoSend (ITelemetry item)
    {
        var dependency = item as DependencyTelemetry;
        if (dependency == null) return true;

        return dependency.Success != true;
    }
}

Aggiungere il processore

ASP.NET

Inserire questo frammento di codice in ApplicationInsights.config:

<TelemetryProcessors>
    <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
    <!-- Set public property -->
    <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
    </Add>
</TelemetryProcessors>

È possibile passare valori stringa dal file .config fornendo proprietà denominate pubbliche nella classe.

Avvertimento

Prestare attenzione a associare il nome del tipo e i nomi delle proprietà nel file .config ai nomi di classe e proprietà nel codice. Se il file .config fa riferimento a un tipo o a una proprietà inesistente, l'SDK potrebbe non inviare dati di telemetria.

In alternativa, è possibile inizializzare il filtro nel codice. In una classe di inizializzazione appropriata, ad esempio AppStart in , inserire il processore nella catena:

Annotazioni

L'esempio di codice seguente è obsoleto, ma viene reso disponibile qui per la posterità. È consigliabile iniziare a usare OpenTelemetry o eseguire la migrazione a OpenTelemetry.

var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
builder.Use((next) => new SuccessfulDependencyFilter(next));

// If you have more processors:
builder.Use((next) => new AnotherProcessor(next));

builder.Build();

I client di telemetria creati dopo questo punto usano i processori.

Processore di telemetria di campionamento adattivo (da 2.0.0-beta3)

Questa funzionalità è abilitata per impostazione predefinita. Se l'app invia numerosi dati di telemetria, questo processore ne rimuove alcuni.

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

Il parametro fornisce la destinazione che l'algoritmo tenta di ottenere. Ogni istanza dell'SDK funziona in modo indipendente. Pertanto, se il server è un cluster di più computer, il volume effettivo dei dati di telemetria viene moltiplicato di conseguenza.

Altre informazioni sul campionamento.

Processore di telemetria di campionamento adattivo (da 2.0.0-beta1)

È disponibile anche un processore di telemetria di campionamento standard (dalla versione 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>

ASP.NET Core

Annotazioni

L'aggiunta di un processore tramite ApplicationInsights.config o TelemetryConfiguration.Active non è valida per le applicazioni ASP.NET Core o se si usa Microsoft.ApplicationInsights.WorkerService SDK.

Per ASP.NET Core, l'aggiunta di un nuovo processore di telemetria viene eseguita usando il metodo di estensione AddApplicationInsightsTelemetryProcessor in IServiceCollection, come illustrato. Questo metodo viene chiamato nel metodo della classe .

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

Per registrare i processori di telemetria che necessitano di parametri in ASP.NET Core, creare una classe personalizzata che implementi ITelemetryProcessorFactory. Chiamare il costruttore con i parametri desiderati nel metodo Create e quindi usare AddSingletonITelemetryProcessorFactory, MyTelemetryProcessorFactory().

Servizio del ruolo di lavoro

Annotazioni

L'aggiunta di un processore tramite ApplicationInsights.config o TelemetryConfiguration.Active non è valida per le applicazioni ASP.NET Core o se si usa Microsoft.ApplicationInsights.WorkerService SDK.

Nel servizio del ruolo di lavoro, l'aggiunta di un nuovo processore di telemetria viene eseguita usando il metodo di estensione su , come mostrato. Questo metodo viene chiamato nel metodo della classe .

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

Filtri di esempio

Richieste sintetiche

Filtrare i robot e i test Web. Anche se Esplora metriche offre la possibilità di filtrare le origini sintetiche, questa opzione riduce il traffico e le dimensioni di inserimento filtrandoli nell'SDK stesso.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Autenticazione non riuscita

Filtrare ed escludere le richieste che ricevono una risposta "401".

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

Filtrare le chiamate di dipendenza remote rapide

Se si desidera diagnosticare solo le chiamate lente, filtrarne le veloci.

Annotazioni

Questo filtro sfasa le statistiche visualizzate nel portale.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

campionamento

Per informazioni su come configurare il campionamento per applicazioni ASP.NET e ASP.NET Core, vedere Sampling in Application Insights.

Servizio del ruolo di lavoro

Application Insights SDK per Worker Service supporta sia il campionamento a frequenza fissa che il campionamento adattivo. Il campionamento adattivo è abilitato per impostazione predefinita. Il campionamento può essere disabilitato usando l'opzione in ApplicationInsightsServiceOptions.

Per configurare altre impostazioni di campionamento, è possibile usare l'esempio seguente:

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.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Arricchire i dati tramite HTTP

ASP.NET

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

ASP.NET Core

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Contenuto della sezione

• Filtrare e pre-elaborare i dati di telemetria
• Inizializzatori di telemetria
• Processore di telemetria
• Campionamento
• Più ruoli per applicazioni multi-componente

Filtrare e pre-elaborare i dati di telemetria

È possibile scrivere codice per filtrare, modificare o arricchire i dati di telemetria prima dell'invio dall'SDK. L'elaborazione include i dati inviati dai moduli di telemetria standard, ad esempio la raccolta di richieste HTTP e la raccolta delle dipendenze.

• Il filtro può modificare o rimuovere i dati di telemetria prima che vengano inviati dall'SDK implementando . Ad esempio, è possibile ridurre il volume di dati di telemetria escludendo le richieste dai robot. A differenza del campionamento, si ha il controllo completo su ciò che viene inviato o rimosso, ma influisce su qualsiasi metrica basata su log aggregati. A seconda della modalità di eliminazione degli elementi, è anche possibile perdere la possibilità di spostarsi tra gli elementi correlati.

• Aggiungere o modificare proprietà a tutti i dati di telemetria inviati dall'app implementando un oggetto . Ad esempio, è possibile aggiungere valori calcolati o numeri di versione in base ai quali filtrare i dati nel portale.

• Il campionamento riduce il volume di dati di telemetria senza influire sulle statistiche. Mantiene insieme i punti dati correlati in modo che sia possibile spostarsi tra di essi durante la diagnosi di un problema. Nel portale i conteggi totali vengono moltiplicati per compensare il campionamento.

Annotazioni

L'API SDK viene usata per inviare metriche ed eventi personalizzati.

Filtraggio

Questa tecnica consente di controllare direttamente gli elementi inclusi o esclusi dal flusso di telemetria. Il filtro può essere usato per eliminare gli elementi di telemetria dall'invio ad Application Insights. È possibile usare il filtro con il campionamento o separatamente.

Per filtrare i dati di telemetria, scrivere un processore di telemetria e registrarlo con . Tutti i dati di telemetria passano attraverso il processore. È possibile scegliere di rilasciarlo dal flusso o assegnarlo al processore successivo nella catena. I dati di telemetria dai moduli standard, come il collettore di richieste HTTP e il collettore di dipendenze, e la telemetria che hai tracciato personalmente sono inclusi. Ad esempio, è possibile filtrare i dati di telemetria relativi alle richieste dei robot o alle chiamate di dipendenza riuscite.

Avvertimento

Filtrare i dati di telemetria inviati dall'SDK usando processori può asimmetriare le statistiche visualizzate nel portale e rendere difficile seguire gli elementi correlati.

Prendere invece in considerazione l'uso del campionamento.

ITelemetryProcessor e ITelemetryInitializer

Qual è la differenza tra processori di telemetria e inizializzatori di telemetria?

• Ci sono alcune sovrapposizioni in ciò che è possibile fare con loro. Entrambi possono essere usati per aggiungere o modificare le proprietà dei dati di telemetria, anche se è consigliabile usare gli inizializzatori a tale scopo.
• Gli inizializzatori di telemetria vengono sempre eseguiti prima dei processori di telemetria.
• Gli inizializzatori di telemetria possono essere chiamati più volte. Per convenzione, non impostano alcuna proprietà già impostata.
• I processori di telemetria consentono di sostituire o rimuovere completamente un elemento di telemetria.
• Tutti gli inizializzatori di telemetria registrati vengono chiamati per ogni elemento di telemetria. Per i processori di telemetria, SDK garantisce la chiamata al primo processore di telemetria. Se il resto dei processori viene chiamato o meno viene deciso dai processori di telemetria precedenti.
• Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con più proprietà o eseguire l'override di uno esistente. Usare un processore di telemetria per filtrare i dati di telemetria.

Aggiungere/modificare le proprietà

Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà di telemetria impostate dai moduli di telemetria standard.

Ad esempio, Application Insights per un pacchetto Web raccoglie i dati di telemetria sulle richieste HTTP. Per impostazione predefinita, contrassegna qualsiasi richiesta con un codice di risposta =400 come non riuscita. Se invece si vuole considerare 400 come un risultato positivo, è possibile fornire un inizializzatore di telemetria che imposti la proprietà Success.

Se si specifica un inizializzatore di telemetria, viene chiamato ogni volta che viene chiamato uno dei metodi Track*(). Questo inizializzatore include metodi chiamati dai moduli di telemetria standard. Per convenzione, questi moduli non impostano alcuna proprietà già impostata da un inizializzatore. Gli inizializzatori di telemetria vengono chiamati prima di chiamare i processori di telemetria, quindi tutti gli arricchimenti eseguiti dagli inizializzatori sono visibili ai processori.

Processori di telemetria

È possibile elaborare e filtrare i dati raccolti prima dell'invio per la conservazione usando i processori di telemetria. I processori di telemetria vengono chiamati uno alla volta, nell'ordine in cui sono stati aggiunti prima dell'invio dell'elemento di telemetria al cloud.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Se un processore di telemetria restituisce , l'elemento di telemetria non viene inviato.

Tutti i processori di telemetria ricevono i dati di telemetria e la relativa busta per l'ispezione e la modifica. Inoltre, ricevono un oggetto di contesto. Il contenuto di questo oggetto viene definito dal parametro quando si chiama un metodo di rilevamento dei dati di telemetria rilevati manualmente. Per i dati di telemetria raccolti automaticamente, questo oggetto viene compilato con le informazioni disponibili sulla richiesta e con il contenuto della richiesta persistente fornito da (se è abilitata la correlazione automatica delle dipendenze).

Il tipo TypeScript per un processore di telemetria è:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Ad esempio, un processore che rimuove i dati di traccia degli stack dalle eccezioni può essere scritto e aggiunto come segue:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Aggiungere un nome del ruolo cloud e un'istanza del ruolo cloud

Impostare il nome del ruolo cloud tramite tag di contesto diretto:

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Impostare il nome del ruolo cloud tramite il processore di telemetria:

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

campionamento

Per impostazione predefinita, l'SDK invia tutti i dati raccolti al servizio Application Insights. Se si desidera abilitare il campionamento e ridurre la quantità di dati, impostare il campo sull'oggetto di un client. L'impostazione su 100 (impostazione predefinita) indica che tutti i dati saranno inviati, mentre 0 indica che non vi sarà alcun invio.

Se si usa la correlazione automatica, tutti i dati associati a una singola richiesta vengono inclusi o esclusi come un'unica unità.

Aggiungere del codice come il seguente per abilitare il campionamento:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Più ruoli per applicazioni multi-componente

In alcuni scenari, l'applicazione potrebbe essere costituita da più componenti che si desidera instrumentare tutti con la stessa connection string. Nel portale si vogliono comunque visualizzare questi componenti come unità separate, come se stessero utilizzando stringhe di connessione separate. Un esempio è costituito dai nodi separati nella Mappa delle applicazioni. È necessario configurare manualmente il campo per distinguere i dati di telemetria di un componente dagli altri componenti che inviano dati alla risorsa di Application Insights.

Usare il codice seguente per impostare il campo :

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Configurazione dell'SDK

.NET

Contenuto della sezione

• Canali di telemetria
• Moduli di telemetria
• Disabilitare i dati di telemetria
• Stringa di connessione
• Provider ApplicationId

È possibile personalizzare Application Insights SDK per ASP.NET, ASP.NET Core e servizio di lavoro per modificare la configurazione predefinita.

ASP.NET

Application Insights .NET SDK è costituito da molti pacchetti NuGet. Il pacchetto di base fornisce l'API per l'invio di dati di telemetria ad Application Insights. Altri pacchetti forniscono moduli e inizializzatori di telemetria per il rilevamento automatico dei dati di telemetria dall'applicazione e dal rispettivo contesto. Modificando il file di configurazione, è possibile abilitare o disabilitare moduli di telemetria e inizializzatori. È anche possibile impostare parametri per alcuni di essi.

Il file di configurazione è denominato o . Il nome dipende dal tipo di applicazione. Viene aggiunto automaticamente al progetto quando si installano alcune versioni dell'SDK.

Per impostazione predefinita, quando si usa l'esperienza automatica dei progetti modello di Visual Studio che supportano Add>Application Insights Telemetry, il file ApplicationInsights.config viene creato nella cartella radice del progetto. Dopo la compilazione, viene copiato nella cartella bin. Viene anche aggiunto a un'app Web da Application Insights Agent in un server IIS.

Importante

Il file di configurazione viene ignorato se viene usata l'extension per i siti Web di Azure o l'extension per Azure macchine virtuali e Azure set di scalabilità di macchine virtuali.

Non esiste un file equivalente per controllare l'SDK in una pagina Web.

ASP.NET Core

Nelle applicazioni ASP.NET Core vengono apportate tutte le modifiche alla configurazione nel metodo ConfigureServices() della classe Startup.cs, a meno che non diversamente indicato.

Annotazioni

Nelle applicazioni ASP.NET Core la modifica della configurazione modificando TelemetryConfiguration.Active non è supportata.

Servizio del ruolo di lavoro

Il valore predefinito TelemetryConfiguration usato dall'SDK del servizio di lavoro è simile alla configurazione automatica usata in un'applicazione ASP.NET o ASP.NET Core, meno gli inizializzatori di telemetria usati per arricchire i dati di telemetria da HttpContext.

È possibile personalizzare Application Insights SDK for Worker Service per modificare la configurazione predefinita. Gli utenti dell'SDK di Application Insights ASP.NET Core potrebbero avere familiarità con la modifica della configurazione usando la dependency injection integrata di ASP.NET Core. Worker Service SDK si basa anche su principi simili. Apportare quasi tutte le modifiche di configurazione nella sezione chiamando i metodi appropriati in , come descritto nella sezione successiva.

Annotazioni

Quando si usa Worker Service SDK, la modifica della configurazione tramite la modifica non è supportata e le modifiche non verranno riflesse.

Canali di telemetria

I canali di telemetria costituiscono parte integrante degli SDK di Application Insights. Essi gestiscono il buffering e la trasmissione dei dati di telemetria al servizio Application Insights. Le versioni di .NET e .NET Core degli SDK hanno due canali di telemetria predefiniti: InMemoryChannel e ServerTelemetryChannel. Questa sezione descrive ogni canale e illustra come personalizzare il comportamento del canale.

Annotazioni

Per consultare le domande frequenti, vedere Domande frequenti sui canali di telemetria

Che cosa sono i canali di telemetria?

I canali di telemetria sono responsabili del buffering degli elementi di telemetria e del loro invio al servizio Application Insights, dove vengono archiviati per l'esecuzione di query e l'analisi. Un canale di telemetria è una qualsiasi classe che implementa l'interfaccia .

Il metodo di un canale di telemetria viene chiamato dopo aver chiamato tutti gli inizializzatori e i processori di telemetria. Pertanto, tutti gli elementi eliminati da un processore di telemetria non raggiungono il canale. Solitamente, il metodo non invia istantaneamente gli elementi al back-end. In genere, li memorizza nel buffer nella memoria e li invia in batch per una trasmissione efficiente.

Evitare di chiamare a meno che non sia fondamentale inviare immediatamente i dati di telemetria memorizzati nel buffer. Usarlo solo in scenari come l'arresto dell'applicazione, la gestione delle eccezioni o quando si usano processi di breve durata come i processi in background o gli strumenti da riga di comando. Nelle applicazioni Web o nei servizi a esecuzione prolungata, l'SDK gestisce automaticamente l'invio dei dati di telemetria. Chiamare inutilmente può causare problemi di prestazioni.

Live Metrics Stream include anche un canale personalizzato che supporta lo streaming live dei dati di telemetria. Questo canale è indipendente dal canale di telemetria normale, quindi questo documento non è pertinente.

Canali di telemetria predefiniti

Application Insights .NET e .NET Core SDK vengono forniti con due canali predefiniti:

• InMemoryChannel: un canale leggero che inserisce gli elementi nel buffer di memoria finché non vengono inviati. Gli elementi vengono memorizzati nel buffer di memoria e scaricati una volta ogni 30 secondi, oppure ogni volta che vengono inseriti 500 elementi nel buffer. Questo canale offre garanzie di affidabilità minime perché non riprova a inviare i dati di telemetria in seguito a un errore. Inoltre, questo canale non conserva gli elementi su disco. Pertanto, gli eventuali elementi non inviati vengono persi in modo permanente all'arresto dell'applicazione, che si un arresto normale o meno. Questo canale implementa un metodo che può essere usato per forzare lo scaricamento sincrono di tutti gli elementi di telemetria in memoria. Questo canale è ideale per le applicazioni a esecuzione breve per le quali è ideale lo scaricamento sincrono.

  Il canale fa parte del pacchetto NuGet Microsoft.ApplicationInsights più esteso ed è il canale predefinito usato dall'SDK in assenza di altre opzioni di configurazione.

• ServerTelemetryChannel: Un canale più avanzato con criteri di ripetizione dei tentativi e la possibilità di archiviare i dati in un disco locale. Questo canale ritenta l'invio dei dati di telemetria in caso di errori temporanei. Inoltre, questo canale si avvale dell'archiviazione su disco locale per mantenere gli elementi su disco durante interruzioni di rete o in presenza di volumi di telemetria elevati. A causa di questi meccanismi di ripetizione dei tentativi e dell'archiviazione su disco locale, questo è il canale ritenuto più affidabile. È consigliabile per tutti gli scenari di produzione. Questo canale è l'impostazione predefinita per le applicazioni ASP.NET e ASP.NET Core configurate in base alla documentazione ufficiale. Il canale è ottimizzato per scenari server con processi a esecuzione prolungata. Il metodo implementato da questo canale non è sincrono.

  Questo canale viene fornito come pacchetto NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel e viene acquisito automaticamente quando si usa il pacchetto NuGet Microsoft.ApplicationInsights.Web o Microsoft.ApplicationInsights.AspNetCore.

Configurare un canale di telemetria

Un canale di telemetria si configura impostandolo sulla configurazione di telemetria attiva. Per le applicazioni ASP.NET, la configurazione comporta l'impostazione dell'istanza del canale di telemetria su TelemetryConfiguration.Active o modificando ApplicationInsights.config. Per le applicazioni ASP.NET Core, la configurazione prevede l'aggiunta del canale al contenitore di iniezione delle dipendenze.

Nelle sezioni seguenti sono riportati esempi di configurazione dell'impostazione per il canale in diversi tipi di applicazioni. è solo una delle impostazioni configurabili. Per l'elenco completo delle impostazioni di configurazione, vedere la sezione Impostazioni configurabili nei canali, più avanti in questo articolo.

ASP.NET

Opzione 1: Configurazione nel codice

Il codice seguente configura un'istanza con impostato su un percorso personalizzato. Aggiungere questo codice all'inizio dell'applicazione, in genere nel metodo in Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

Opzione 2: Configurazione in ApplicationInsights.config

Nella sezione seguente di ApplicationInsights.config viene mostrato il canale configurato con impostato su un percorso personalizzato:

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

ASP.NET Core

Modificare il metodo della classe come illustrato di seguito:

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

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

Importante

La configurazione del canale tramite TelemetryConfiguration.Active non è supportata per le applicazioni ASP.NET Core.

Override di ServerTelemetryChannel

Il canale di telemetria predefinito è . Nell'esempio seguente viene illustrato come eseguirne l'override.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

Annotazioni

Per svuotare il buffer, vedere Svuotamento dei dati. Ad esempio, potrebbe essere necessario scaricare il buffer se si usa l'SDK in un'applicazione che si arresta.

Servizio del ruolo di lavoro

Il canale predefinito è . È possibile eseguirne l'override come illustrato nell'esempio seguente:

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

Configurazione nel codice per applicazioni console

Per le app console, il codice è lo stesso per .NET e .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Dettagli sul funzionamento di ServerTelemetryChannel

archivia gli elementi in arrivo in un buffer di memoria. Gli elementi vengono serializzati, compressi e archiviati in un'istanza una volta ogni 30 secondi, oppure quando nel buffer sono stati inseriti 500 elementi. Una singola istanza può contenere fino a 500 elementi e rappresenta un batch di dati di telemetria inviati tramite una singola chiamata HTTPS al servizio Application Insights.

Per impostazione predefinita, è possibile inviare in parallelo un massimo di 10 istanze . Se i dati di telemetria arrivano a velocità più elevate o se la rete o il back-end di Application Insights sono lenti, le istanze vengono archiviate in memoria. La capacità predefinita di questo buffer di memoria è di 5 MB. Quando si supera la capacità di memoria, le istanze vengono archiviate sul disco locale fino a un limite di 50 MB.

Le istanze vengono archiviate sul disco locale anche in caso di problemi di rete. Solo gli elementi archiviati su un disco locale non subiscono conseguenze dopo un arresto anomalo dell'applicazione. Essi vengono inviati ogni volta che si riavvia l'applicazione. Se i problemi di rete persistono, usa una logica di backoff esponenziale in un periodo compreso tra 10 secondi e 1 ora prima di ritentare l'invio dei dati di telemetria.

Impostazioni configurabili nei canali

Per l'elenco completo delle impostazioni configurabili per ogni canale, vedere:

• InMemoryChannel
• ServerTelemetryChannel

Di seguito sono riportate le impostazioni più comunemente usate per :

• : quantità massima di memoria, in byte, utilizzata dal canale per inserire le trasmissioni nel buffer di memoria. Quando viene raggiunta questa capacità, i nuovi elementi vengono archiviati direttamente sul disco locale. Il valore predefinito è 5 MB. L'impostazione di un valore superiore comporta un minore utilizzo del disco, tuttavia si deve ricordare che gli elementi in memoria vanno persi in caso di arresto anomalo dell'applicazione.

• : il numero massimo di istanze che vengono inviate contemporaneamente ad Application Insights. Il valore predefinito è 10. Questa impostazione può essere configurata con un numero maggiore, consigliabile quando viene generato un enorme volume di dati di telemetria. Generalmente, un volume elevato si verifica durante i test di carico o quando il campionamento è disattivato.

• : la cartella usata dal canale per archiviare gli elementi su disco in base alle esigenze. In Windows, %LOCALAPPDATA% o %TEMP% viene usato se non viene specificato alcun altro percorso in modo esplicito. Negli ambienti diversi da Windows, per impostazione predefinita vengono usati i percorsi seguenti (in ordine): %TMPDIR%, /var/tmp/ o /tmp/.

Quale canale è consigliabile usare?

È preferibile per la maggior parte degli scenari di produzione che coinvolgano applicazioni a esecuzione prolungata. Per altre informazioni sullo scaricamento dei dati di telemetria, leggere la documentazione sull'uso di .

Quando usare Flush()

Il metodo invia immediatamente tutti i dati di telemetria memorizzati nel buffer. Tuttavia, deve essere usato solo in scenari specifici.

Usare quando:

• L'applicazione sta per arrestarsi e si vuole assicurarsi che i dati di telemetria vengano inviati prima della chiusura.
• Si è in un gestore eccezioni e si ha bisogno di garantire che i dati di telemetria vengano recapitati.
• Si sta scrivendo un processo di breve durata, ad esempio un processo in background o uno strumento dell'interfaccia della riga di comando che si chiude rapidamente.

Evitare di usare in applicazioni a esecuzione prolungata come i servizi Web. L'SDK gestisce automaticamente il buffering e la trasmissione. Chiamare inutilmente può causare problemi di prestazioni e non garantisce che tutti i dati vengano inviati, specialmente quando si usa , che non scarica in modo sincrono.

Moduli di telemetria

Application Insights raccoglie automaticamente i dati di telemetria relativi a carichi di lavoro specifici senza richiedere il rilevamento manuale da parte dell'utente.

Per impostazione predefinita, sono abilitati i seguenti moduli di raccolta automatica. È possibile disabilitarli o configurarli per modificarne il comportamento predefinito.

ASP.NET

Ogni modulo di telemetria raccoglie un tipo specifico di dati e utilizza l’API principale per inviare i dati. I moduli sono installati da diversi pacchetti NuGet che aggiungono anche le linee necessarie al file .config.

Area	Description
Rilevamento delle richieste	Raccoglie i dati di telemetria delle richieste (tempo di risposta, codice di risultato) per le richieste Web in ingresso. Modulo: NuGet:Microsoft.ApplicationInsights.Web
Rilevamento delle dipendenze	Raccoglie i dati di telemetria sulle dipendenze in uscita (chiamate HTTP, chiamate SQL). Per operare in IIS, installare Application Insights Agent. È anche possibile scrivere il rilevamento personalizzato delle dipendenze usando l’API TrackDependency. Supporta la strumentazione automatica con App Service e il monitoraggio di VM e set di scalabilità di macchine virtuali. Modulo: NuGet:Microsoft.ApplicationInsights.DependencyCollector
Contatori delle prestazioni	Raccoglie i contatori delle prestazioni di Windows (CPU, memoria, carico di rete dalle installazioni di IIS). Specificare i contatori (inclusi quelli personalizzati). Per altre informazioni, vedere Raccoglie i contatori delle prestazioni di sistema. Modulo: NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Contatori di eventi	Raccoglie .NET EventCounters. Consigliato per ASP.NET Core e per l'uso multipiattaforma al posto dei contatori delle prestazioni di Windows. Modulo: (SDK ≥ 2.8.0)
Metriche live (QuickPulse)	Raccoglie i dati di telemetria per il riquadro Metriche live. Modulo:
Heartbeat (servizio app)	Invia heartbeat e metriche personalizzate per l'ambiente del servizio app. Modulo:
Heartbeat (macchine virtuali e set di scalabilità di macchine virtuali)	Invia heartbeats e metriche personalizzate per l'ambiente VM di Azure. Modulo:
Dati di telemetria di diagnostica	Segnala errori nel codice di strumentazione di Application Insights, (ad esempio, contatori mancanti, eccezioni ). I dati di telemetria di traccia vengono visualizzati in Ricerca diagnostica. Modulo: NuGet:Microsoft.ApplicationInsights Nota: se si installa questo pacchetto, il file ApplicationInsights.config non viene creato automaticamente.
Modalità sviluppatore (debugger collegato)	Forza a inviare immediatamente gli elementi quando il debugger è collegato. Riduce la latenza ma aumenta il sovraccarico di CPU/rete. Modulo: NuGet:Application Insights Windows Server
Rilevamento delle eccezioni (Web)	Rileva le eccezioni non gestite nell'app Web. Vedere Errori ed eccezioni. Modulo: NuGet:Microsoft.ApplicationInsights.Web
Rilevamento delle eccezioni (non osservate/non gestite)	Tiene traccia delle eccezioni delle attività non rilevate e delle eccezioni non gestite per i ruoli di lavoro, i servizi Windows e le app console. Modules:  •  • NuGet:Microsoft.ApplicationInsights.WindowsServer
Rilevamento EventSource	Invia eventi EventSource configurati ad Application Insights come tracce. Modulo: NuGet:Microsoft.ApplicationInsights.EventSourceListener
Agente di raccolta ETW	Invia eventi del provider ETW configurati ad Application Insights come tracce. Modulo: NuGet:Microsoft.ApplicationInsights.EtwCollector
API Core (non un modulo)	API Core usata da altri componenti di telemetria e per dati di telemetria personalizzati. Modulo: NuGet:Microsoft.ApplicationInsights Nota: se si installa questo pacchetto, il file ApplicationInsights.config non viene creato automaticamente.

ASP.NET Core

Area	Description
Rilevamento delle richieste	Rilevamento delle richieste integrato tramite l'integrazione di Application Insights con ASP.NET Core. Modulo:Nessuna classe di modulo separata. NuGet:Microsoft.ApplicationInsights.AspNetCore
Rilevamento delle dipendenze	Tramite raccolta delle dipendenze. NuGet:Microsoft.ApplicationInsights.DependencyCollector
Contatori delle prestazioni	Esclusivamente per Windows! In una multipiattaforma usare (vedere la riga successiva). NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Contatori di eventi	Raccoglie .NET EventCounters. Consigliato per ASP.NET Core e piattaforme diverse al posto dei contatori delle prestazioni di Windows. Modulo: (SDK 2.8.0 e versioni successive) NuGet:Microsoft.ApplicationInsights.EventCounterCollector
Metriche live (QuickPulse)	Metriche attive abilitate nell'integrazione di Application Insights ASP.NET Core. Modulo:Nessuna classe di modulo separata. NuGet:Microsoft.ApplicationInsights.AspNetCore
Agente di raccolta heartbeat (servizio app)	Invia heartbeat (come metriche personalizzate) con informazioni dettagliate sull'ambiente del servizio app. Integrato tramite l’SDK di base quando è ospitato nel servizio app. Modulo:Nessuna classe di modulo separata. NuGet:Microsoft.ApplicationInsights.AspNetCore
Raccolta Heartbeat (macchine virtuali e set di scalabilità di macchine virtuali)	Invia heartbeat (come metriche personalizzate) con informazioni dettagliate sull'ambiente della macchina virtuale Azure. Integrato tramite l'SDK di base quando ospitato su macchine virtuali Azure e gruppi di scalabilità delle macchine virtuali Azure. Modulo:Nessuna classe di modulo separata. NuGet:Microsoft.ApplicationInsights.AspNetCore
Dati di telemetria di diagnostica	Segnala errori nel codice di strumentazione di Application Insights stesso (ad esempio, se non è possibile accedere ai contatori di prestazioni, genera un'eccezione). I dati di telemetria di traccia vengono visualizzati in Ricerca diagnostica. Modulo: NuGet:Microsoft.ApplicationInsights
Modalità sviluppatore (debugger collegato)	Stesso comportamento disponibile; la classe fa parte del pacchetto di Windows Server. Modulo: NuGet:Microsoft.ApplicationInsights.WindowsServer
Rilevamento delle eccezioni (Web)	Rilevamento automatico delle eccezioni nell'integrazione di Application Insights ASP.NET Core Modulo:Nessuna classe di modulo separata. NuGet:Microsoft.ApplicationInsights.AspNetCore
Rilevamento delle eccezioni (non osservate/non gestite)	Comportamento simile tramite ASP.NET Core runtime/integrazione; i nomi delle classi sono Windows Server specifici. NuGet:Microsoft.ApplicationInsights.WindowsServer
Rilevamento EventSource	Invia eventi EventSource configurati ad Application Insights come tracce. Modulo: NuGet:Microsoft.ApplicationInsights.EventSourceListener
Agente di raccolta ETW	Esclusivo per Windows (ETW). Invia eventi del provider ETW configurati ad Application Insights come tracce. Modulo: NuGet:Microsoft.ApplicationInsights.EtwCollector
API Core (non un modulo)	API Core usata da altri componenti di telemetria e per dati di telemetria personalizzati. Modulo: NuGet:Microsoft.ApplicationInsights

Configurare i moduli di telemetria

ASP.NET

Usare la sezione in ApplicationInsights.config per configurare, aggiungere o rimuovere moduli. Gli esempi seguenti:

• Configurare (abilitare l'inserimento dell'intestazione W3C).
• Configurare (cancellare le impostazioni predefinite e aggiungere un singolo contatore).
• Disabilitare la raccolta di contatori delle prestazioni rimuovendo .

<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

Annotazioni

Il set esatto di moduli presenti in dipende dai pacchetti SDK installati.

ASP.NET Core

Opzione 1: Configurare i moduli di telemetria usando ConfigureTelemetryModule

Per configurare qualsiasi predefinito, usare il metodo di estensione in , come illustrato nell'esempio seguente:

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

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

var app = builder.Build();

Opzione 2: Configurare i moduli di telemetria con ApplicationInsightsServiceOptions

In SDK versioni 2.12.2 e successive, è possibile modificare alcune impostazioni comuni passando a , come in questo esempio:

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

Questa tabella include l'elenco completo delle impostazioni di :

Impostazione	Description	Predefinito
EnablePerformanceCounterCollectionModule	Abilitare/disabilitare .	Vero
Modulo di abilitazione della telemetria di tracciamento delle richieste	Abilitare/disabilitare .	Vero
EnableEventCounterCollectionModule	Abilitare/disabilitare .	Vero
EnableDependencyTrackingTelemetryModule	Abilitare/disabilitare .	Vero
EnableAppServicesHeartbeatTelemetryModule	Abilitare/disabilitare .	Vero
EnableAzureInstanceMetadataTelemetryModule	Abilitare/disabilitare .	Vero
Abilita il flusso di metriche QuickPulse	Abilitare/disabilitare la funzionalità LiveMetrics.	Vero
EnableAdaptiveSampling	Abilita/disabilita il campionamento adattivo.	Vero
AbilitaBattitoCuore	Abilitare/disabilitare la funzionalità heartbeat. Periodicamente (impostazione predefinita di 15 minuti) invia una metrica personalizzata denominata HeartbeatState con informazioni sul runtime, ad esempio .NET versione e informazioni sull'ambiente Azure, se applicabile.	Vero
AddAutoCollectedMetricExtractor	Abilitare/disabilitare . Questo processore di telemetria invia metriche preaggregate relative a richieste/dipendenze prima che venga eseguito il campionamento.	Vero
RequestCollectionOptions.TrackExceptions	Abilitare/disabilitare la segnalazione di rilevamento delle eccezioni non gestite dal modulo di raccolta delle richieste.	False in (perché le eccezioni vengono rilevate con ). True in caso contrario.
EnableDiagnosticsTelemetryModule	Abilitare/disabilitare . Con la disabilitazione vengono ignorate le impostazioni seguenti: , e .	Vero

Per l'elenco più recente, vedere le impostazioni configurabili in .

Raccomandazione di configurazione per Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 e versioni successive

In Microsoft.ApplicationInsights.AspNetCore SDK versione 2.15.0 e versioni successive configurare ogni impostazione disponibile in , inclusa . Utilizzare l'istanza dell'applicazione . Le impostazioni devono trovarsi nella sezione , come illustrato nell'esempio seguente. La sezione seguente di appsettings.json configura la stringa di connessione e disabilita il campionamento adattivo e la raccolta dei contatori delle prestazioni.

{
    "ApplicationInsights": {
    "ConnectionString": "<YOUR-CONNECTION-STRING>",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Se viene utilizzato builder.Services.AddApplicationInsightsTelemetry(aiOptions) per ASP.NET Core 6.0 o services.AddApplicationInsightsTelemetry(aiOptions) per ASP.NET Core 3.1 e versioni precedenti, le impostazioni di Microsoft.Extensions.Configuration.IConfiguration vengono sovrascritte.

Servizio del ruolo di lavoro

Opzione 1: Configurare i moduli di telemetria usando ConfigureTelemetryModule

Application Insights usa moduli di telemetria per raccogliere automaticamente i dati di telemetria relativi a carichi di lavoro specifici senza richiedere il rilevamento manuale.

I moduli di raccolta automatica seguenti sono abilitati per impostazione predefinita. Questi moduli sono responsabili della raccolta automatica dei dati di telemetria. È possibile disabilitarli o configurarli per modificarne il comportamento predefinito.

• DependencyTrackingTelemetryModule
• PerformanceCollectorModule
• QuickPulseTelemetryModule
• AppServicesHeartbeatTelemetryModule (attualmente è presente un problema che interessa questo modulo di telemetria. Per una soluzione alternativa temporanea, vedere GitHub Problema 1689.
• AzureInstanceMetadataTelemetryModule

Per configurare qualsiasi modulo di telemetria predefinito, usare il metodo di estensione in , come illustrato nell'esempio seguente:

    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 = "<YOUR-API-KEY-HERE>";
            });

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

Opzione 2: Configurare i moduli di telemetria con ApplicationInsightsServiceOptions

È possibile modificare alcune impostazioni comuni passando a , come in questo esempio:

using Microsoft.ApplicationInsights.WorkerService;

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

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

Il ApplicationInsightsServiceOptions in questo SDK si trova nello spazio dei nomi Microsoft.ApplicationInsights.WorkerService anziché Microsoft.ApplicationInsights.AspNetCore.Extensions nell'SDK di ASP.NET Core.

Nella tabella seguente sono elencate le impostazioni di uso comune in .

Impostazione	Description	Predefinito
Abilita il flusso di metriche QuickPulse	Abilitare/disabilitare la funzionalità delle metriche attive.	Vero
EnableAdaptiveSampling	Abilita/disabilita il campionamento adattivo.	Vero
AbilitaBattitoCuore	Abilitare/disabilitare la funzionalità Heartbeats, che invia periodicamente (impostazione predefinita 15 minuti) una metrica personalizzata denominata "HeartBeatState" con informazioni sul runtime, ad esempio .NET versione e Azure ambiente, se applicabile.	Vero
AddAutoCollectedMetricExtractor	Abilitare/disabilitare l'estrattore AutoCollectedMetrics, ovvero un processore di telemetria che invia metriche preaggregate relative a Richieste/Dipendenze prima del campionamento.	Vero
EnableDiagnosticsTelemetryModule	Abilitare/disabilitare . Se si disabilita questa impostazione, le impostazioni seguenti verranno ignorate: , e .	Vero

Per l'elenco più aggiornato, vedere le impostazioni configurabili in .

Disabilitare telemetria

ASP.NET

Nel file di configurazione è presente un nodo per ogni modulo. Per disabilitare un modulo, eliminare il nodo o impostarlo come commento.

ASP.NET Core

Se si desidera disabilitare la telemetria in modo condizionale e dinamico, è possibile risolvere l'istanza di TelemetryConfiguration con un contenitore per l'inserimento delle dipendenze ASP.NET Core ovunque nel codice e impostare il flag DisableTelemetry su di esso.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

L'esempio di codice precedente impedisce l'invio di dati di telemetria ad Application Insights. Non impedisce ai moduli di raccolta automatica di raccogliere dati di telemetria. Per rimuovere un modulo di raccolta automatica specifico, vedere moduli di telemetria.

Servizio del ruolo di lavoro

Se si desidera disabilitare i dati di telemetria in modo condizionale e dinamico, è possibile risolvere l'istanza di TelemetryConfiguration con un contenitore di inserimento delle dipendenze ASP.NET Core ovunque nel codice e impostare il flag DisableTelemetry su di esso.

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

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

stringa di connessione

Queste impostazioni determinano la risorsa di Application Insights in cui vengono visualizzati i dati. In genere, si crea una risorsa separata, con un connection string separato, per ognuna delle applicazioni.

Per esempi di codice, vedere Stringhe di connessione in Application Insights.

Se si vuole impostare il connection string in modo dinamico, ad esempio per inviare risultati dall'applicazione a risorse diverse, è possibile omettere il connection string dal file di configurazione e impostarlo nel codice.

ASP.NET

Per impostare il connection string per tutte le istanze di TelemetryClient, inclusi i moduli di telemetria standard, eseguire questo passaggio in un metodo di inizializzazione, ad esempio global.aspx.cs in un servizio ASP.NET:

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "<YOUR-CONNECTION-STRING>";
        var telemetryClient = new TelemetryClient(configuration);

Se si vuole inviare un set specifico di eventi a una risorsa diversa, è possibile impostare la chiave per un oggetto client di telemetria specifico:

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
    tc.TrackEvent("myEvent");
    // ...

Per ottenere una nuova connection string, creare una nuova risorsa nel portale di Application Insights.

ASP.NET Core

In ASP.NET Core, configurare la stringa di connessione in Program.cs durante l'avvio dell'applicazione usando TelemetryConfiguration dal contenitore di iniezione delle dipendenze.

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

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";

app.Run();

Se si vuole inviare un set specifico di eventi a una risorsa diversa, è possibile creare una nuova istanza di TelemetryClient e impostarne il connection string in modo esplicito:

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
tc.TrackEvent("myEvent");
// ...

Fornitore di ApplicationId

Annotazioni

Per ASP.NET, questo provider è disponibile a partire da SDK v2.6.0*.

Lo scopo di questo provider è cercare un ID applicazione in base a un connection string. L'ID applicazione è incluso in e viene usato per determinare la correlazione nel portale.

Questa funzionalità è disponibile impostando .

Interfaccia: IApplicationIdProvider

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

Vengono fornite due implementazioni nell'SDK Microsoft.ApplicationInsights: e .

ApplicationInsightsApplicationIdProvider

Questo wrapper è per l'API del profilo. Limita le richieste e i risultati della cache. Questo provider viene incluso automaticamente quando si installa Microsoft.ApplicationInsights.DependencyCollector o Microsoft.ApplicationInsights.Web.

La classe espone una proprietà facoltativa denominata . Per impostazione predefinita, è impostata su .

Se è necessario configurare un proxy, si consiglia di usare il proxy per l'indirizzo di base e assicurarsi che il percorso includa . In fase di esecuzione, {0} viene sostituito con il connection string per ogni richiesta.

ASP.NET

Configurazione di esempio tramite ApplicationInsights.config

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

Configurazione di esempio tramite codice

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

ASP.NET Core

Annotazioni

In ASP.NET Core non è presente alcun file ApplicationInsights.config. La configurazione viene eseguita tramite inserimento delle dipendenze in Program.cs o Startup.cs.

È possibile eseguire l'override del provider predefinito o personalizzarne l’elemento .

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

DictionaryApplicationIdProvider

Questo provider statico si basa sulle coppie di ID applicazione/connection string configurate.

Questa classe ha la proprietà Defined, ovvero un Dictionary<string,string> di coppie stringa di connessione/ID applicazione.

Questa classe ha la proprietà facoltativa Next, che può essere usata per configurare un altro provider da usare quando viene richiesta una connection string che non esiste nella configurazione.

ASP.NET

Configurazione di esempio tramite ApplicationInsights.config

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

Configurazione di esempio tramite codice

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

ASP.NET Core

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "ConnectionString_1", "ApplicationId_1" },
            { "ConnectionString_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Contenuto della sezione

• Stringa di connessione
• Opzione di configurazione avanzata
• Strumentazione automatica di terze parti

L'oggetto offre molti metodi di configurazione. Essi sono elencati nel frammento di codice seguente con i relativi valori predefiniti.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Per correlare completamente gli eventi in un servizio, assicurarsi di impostare . Con questa opzione impostata, l'SDK può tenere traccia del contesto tra callback asincroni in Node.js.

Consultare le descrizioni nei suggerimenti di tipo integrati dell'IDE o in applicationinsights.ts per informazioni dettagliate e argomenti opzionali secondari.

Annotazioni

Per impostazione predefinita, è configurato per escludere le chiamate a e altri metodi della console. Verranno raccolte solo le chiamate ai logger di terze parti supportati (ad esempio winston e bunyan). È possibile modificare questo comportamento e includere le chiamate ai metodi tramite .

stringa di connessione

Queste impostazioni determinano la risorsa di Application Insights in cui vengono visualizzati i dati. In genere, si crea una risorsa separata, con un connection string separato, per ognuna delle applicazioni.

Per esempi di codice, vedere Stringhe di connessione in Application Insights.

Se si vuole impostare il connection string in modo dinamico, ad esempio per inviare risultati dall'applicazione a risorse diverse, è possibile omettere il connection string dal file di configurazione e impostarlo nel codice.

Usare più stringhe di connessione

È possibile creare più risorse di Application Insights e inviare dati diversi a ciascuna di esse usando le rispettive stringhe di connessione.

Per esempio:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Opzioni di configurazione avanzate

L'oggetto client contiene una proprietà con molte impostazioni facoltative per scenari avanzati. Per impostarli, usare:

client.config.PROPERTYNAME = VALUE;

Queste proprietà sono specifiche del client, pertanto è possibile configurare separatamente dai client creati con .

Proprietà	Description
stringa di connessione	Identificatore per la risorsa di Application Insights.
endpointUrl	Endpoint di ricezione al quale inviare i payload di telemetria.
quickPulseHost	Host Live Metrics Stream al quale inviare i dati di telemetria delle metriche in tempo reale.
proxyHttpUrl	Server proxy per il traffico HTTP dell'SDK. (Facoltativo. Il valore predefinito viene derivato dalla variabile di ambiente ).
proxyHttpsUrl	Server proxy per il traffico HTTPS SDK. (Facoltativo. Il valore predefinito viene derivato dalla variabile di ambiente ).
httpAgent	Un http.Agent da utilizzare per il traffico HTTP dell'SDK. (Facoltativo. Il valore predefinito è non definito).
httpsAgent	Un https.Agent da usare per il traffico HTTPS dell'SDK. (Facoltativo. Il valore predefinito è non definito).
maxBatchSize	Numero massimo di elementi di telemetria da includere in un payload per l'endpoint di inserimento. (Il valore predefinito è .)
maxBatchIntervalMs	Quantità massima di tempo di attesa affinché un payload raggiunga maxBatchSize. (Il valore predefinito è .)
disableAppInsights	Flag che indica se la trasmissione dei dati di telemetria è disabilitata. (Il valore predefinito è .)
percentuale di campionamento	Percentuale di elementi di telemetria rilevati che devono essere trasmessi. (Il valore predefinito è .)
correlationIdRetryIntervalMs	Tempo di attesa prima di ritentare il recupero dell'ID per la correlazione tra componenti. (Il valore predefinito è .)
correlationHeaderExcludedDomains	Elenco di domini da escludere dall'inserimento dell'intestazione di correlazione tra componenti. (Impostazione predefinita. Vedere Config.ts).

Strumentazione automatica di terze parti

Per tenere traccia del contesto tra chiamate asincrone, sono richieste alcune modifiche nelle librerie di terze parti, ad esempio MongoDB e Redis. Per impostazione predefinita, Application Insights usa per applicare delle patch ad alcune di queste librerie. Questa funzionalità può essere disabilitata impostando la variabile di ambiente .

Annotazioni

Impostando questa variabile di ambiente, gli eventi potrebbero non essere associati correttamente all'operazione corretta.

Le singole patch possono essere disabilitate impostando la variabile di ambiente su un elenco delimitato da virgole di pacchetti da disabilitare. Ad esempio, usare per evitare di applicare patch ai pacchetti e .

Attualmente sono instrumentati nove pacchetti: ,,,,,,, e . Per informazioni sulla versione esatta di questi pacchetti con patch, vedere il README di diagnostic-channel-publishers.

Le patch , e generano eventi di traccia di Application Insights a seconda della scelta di abilitare o meno . Il resto genera eventi di dipendenza di Application Insights a seconda della scelta di abilitare o meno .

Aggiungere il monitoraggio sul lato client

.NET

Le sezioni precedenti forniscono indicazioni sui metodi per configurare automaticamente e manualmente il monitoraggio lato server. Per aggiungere il monitoraggio lato client, usare l'SDK JavaScript lato client. È possibile monitorare le transazioni lato client di qualsiasi pagina Web aggiungendo uno script del caricatore SDK JavaScript (Web) prima del tag di chiusura del codice HTML della pagina.

Sebbene sia possibile aggiungere manualmente lo script di caricamento di JavaScript (Web) SDK all'intestazione di ogni pagina HTML, è consigliabile aggiungerlo a una pagina primaria. Questa azione inserisce lo script di caricamento di JavaScript (Web) SDK in tutte le pagine di un sito.

ASP.NET

Per l'app ASP.NET MVC basata su modello di questo articolo, il file da modificare è _Layout.cshtml. È possibile trovarlo in VisualizzazioniCondivise. Per aggiungere il monitoraggio sul lato client, aprire _Layout.cshtml e seguire le istruzioni per l'installazione basata su script di caricamento di JavaScript (Web) SDK riportate nell'articolo sulla configurazione di JavaScript SDK sul lato client.

ASP.NET Core

Se l'applicazione include componenti sul lato client, seguire i passaggi successivi per iniziare a raccogliere dati di telemetria sull'utilizzo usando l'inserimento di script del caricatore SDK JavaScript (Web) in base alla configurazione.

1. In _ViewImports.cshtml, aggiungere iniezione:

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. In _Layout.cshtml inserire alla fine della sezione, ma prima di qualsiasi altro script. Per segnalare dati di telemetria JavaScript personalizzati dalla pagina, inserirli dopo questo frammento di codice:

       @Html.Raw(JavaScriptSnippet.FullScript)
   </head>
   

In alternativa all'uso di FullScript, ScriptBody è disponibile a partire da Application Insights SDK per ASP.NET Core versione 2.14. Usare se è necessario controllare il tag per impostare criteri di sicurezza del contenuto:

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

I nomi di file con estensione cshtml a cui si fa riferimento in precedenza provengono da un modello di applicazione MVC predefinito. In definitiva, se si vuole abilitare correttamente il monitoraggio lato client per l'applicazione, lo script del caricatore dell'SDK JavaScript (Web) deve essere visualizzato nella sezione di ogni pagina dell'applicazione da monitorare. Aggiungere lo script del caricatore SDK (Web) a _Layout.cshtml in un modello di applicazione per abilitare il monitoraggio lato client.

Se il progetto non include _Layout.cshtml, è comunque possibile aggiungere il monitoraggio lato client aggiungendo lo script del caricatore sdk JavaScript (Web) a un file equivalente che controlla tutte le pagine all'interno dell'app. In alternativa, è possibile aggiungere lo script del caricatore SDK JavaScript (Web) a più pagine, ma non è consigliabile.

Annotazioni

L'inserimento di JavaScript offre un'esperienza di configurazione predefinita. Se è necessaria una configurazione oltre l'impostazione della stringa di connessione, è necessario rimuovere l'autoiniezione come descritto e aggiungere manualmente il JavaScript SDK.

Annotazioni

Disponibile come anteprima pubblica. Termini integrativi di utilizzo per le anteprime di Microsoft Azure

La strumentazione Web automatica può essere abilitata per il server del nodo tramite l'inserimento di script del caricatore dell'SDK JavaScript (Web) per configurazione.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

oppure impostando la variabile di ambiente .

La strumentazione Web è abilitata nelle risposte del server del nodo quando vengono soddisfatti tutti i requisiti seguenti:

• La risposta ha il codice di stato .
• Il metodo di risposta è .
• La risposta del server ha html.
• La risposta del server contiene i tag e .
• Se la risposta è compressa, deve avere un solo tipo e il tipo di codifica deve essere uno tra , o .
• La risposta non contiene gli endpoint correnti/di backup della rete CDN della strumentazione Web. (endpoint correnti e di backup della rete CDN della strumentazione Web qui)

L'endpoint della rete CDN di Strumentazione Web può essere modificato impostando la variabile di ambiente . È possibile modificare la stringa di connessione della strumentazione web impostando la variabile di ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Annotazioni

La strumentazione Web può rallentare il tempo di risposta del server, in particolare se le dimensioni della risposta sono elevate o se la risposta è compressa. Nel caso in cui vengano applicati alcuni livelli intermedi, è possibile che la strumentazione Web non funzioni e venga restituita la risposta originale.

API di base per eventi personalizzati e metriche

Inserire alcune righe di codice nell'applicazione per scoprire le operazioni eseguite dagli utenti o per diagnosticare i problemi. È possibile inviare dati di telemetria da app desktop e dispositivi, client Web e server Web. Usare l'API di telemetria di base di Application Insights per inviare metriche e eventi personalizzati e versioni personalizzate dei dati di telemetria standard. Questa API è la stessa API usata dagli agenti di raccolta dati standard di Application Insights.

Riepilogo API

L'API principale è uniforme in tutte le piattaforme, a parte alcune varianti, ad esempio GetMetric (solo .NET).

Metodo	Usato per
TrackPageView	Pagine, schermate, riquadri o moduli.
TrackEvent	Azioni utente e altri eventi. Usato per tenere traccia del comportamento dell'utente o per monitorare le prestazioni.
GetMetric	Metriche zero e multidimensionali, aggregazione configurata centralmente, solo C#.
TrackMetric	Misurazioni delle prestazioni, ad esempio lunghezze della coda, non correlate a eventi specifici.
TrackException	Registrazione delle eccezioni per la diagnostica. Tenere traccia del punto in cui si verificano in relazione ad altri eventi ed esaminare le analisi dello stack.
TrackRequest	Registrazione della frequenza e della durata delle richieste del server per l'analisi delle prestazioni.
TrackTrace	Messaggi del log di diagnostica delle risorse. È anche possibile acquisire log di terze parti.
TrackDependency	Registrazione della durata e della frequenza delle chiamate a componenti esterni da cui dipende l'app.

È possibile associare proprietà e metriche alla maggior parte di queste chiamate di telemetria.

Prerequisiti

Se non si ha ancora un riferimento in Application Insights SDK:

1. Aggiungere Application Insights SDK al progetto.

2. Nel codice del dispositivo o del server Web includere:

   .NET

   using Microsoft.ApplicationInsights;
   

   var applicationInsights = require("applicationinsights");
   

Ottenere un'istanza di TelemetryClient

Ottenere un'istanza di :

Annotazioni

Se si usa Azure Functions v2+ o Azure WebJobs v3+, vedere Monitor Azure Functions.

.NET

Annotazioni

Per le app ASP.NET Core e non HTTP/ruolo di lavoro per .NET/.NET Core, ottenere un'istanza di TelemetryClient dal contenitore di inserimento delle dipendenze, come illustrato nella rispettiva documentazione.

private TelemetryClient telemetry = new TelemetryClient();

Se viene visualizzato un messaggio che indica che questo metodo è obsoleto, vedere microsoft/ApplicationInsights-dotnet#1152 per altre informazioni.

Le richieste HTTP in ingresso vengono acquisite automaticamente. Potrebbe essere necessario creare più istanze di per altri moduli dell'app. Ad esempio, potrebbe essere presente un'istanza della classe middleware per segnalare gli eventi della logica di business. È possibile impostare proprietà come e per identificare il computer. Queste informazioni vengono associate a tutti gli eventi inviati dall'istanza.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

var telemetry = applicationInsights.defaultClient;

È possibile usare per creare una nuova istanza. È consigliabile questo approccio solo per gli scenari che richiedono una configurazione isolata dal singleton .

Annotazioni

è sicuro per i thread.

TrackEvent

In Application Insights un evento personalizzato è un punto dati che è possibile visualizzare in Esplora metriche come conteggio aggregato e in Cerca come singole occorrenze. Non è correlato a MVC o ad altri "eventi".

Inserire chiamate nel codice per contare i vari eventi. Ad esempio, è possibile tenere traccia della frequenza con cui gli utenti scelgono una determinata funzionalità. Oppure potresti voler sapere con quale frequenza raggiungono determinati obiettivi o commettono tipi specifici di errori.

Ad esempio, in un'app di gioco inviare un evento ogni volta che un utente vince il gioco:

.NET

telemetry.TrackEvent("WinGame");

telemetry.trackEvent({name: "WinGame"});

Eventi personalizzati in Log Analytics

I dati di telemetria sono disponibili nella tabella nella scheda Log di Application Insights o nell'esperienza di utilizzo. Gli eventi potrebbero provenire da o dal plug-in Click Analytics Autocollection.

Se il campionamento è in funzione, la proprietà mostra un valore maggiore di . Ad esempio, significa che di 10 chiamate a , il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto degli eventi personalizzati, usare codice come .

Annotazioni

itemCount ha un valore minimo di uno; il record stesso rappresenta un entry.

GetMetric

Per informazioni su come usare in modo efficace la chiamata GetMetric() per acquisire metriche preaggregate in locale per le applicazioni .NET e .NET Core, vedere Raccolta di metriche personalizzata in .NET e .NET Core.

TrackMetric

Annotazioni

non è il metodo preferito per l'invio di metriche. Le metriche devono essere sempre preaggregate in un periodo di tempo prima di essere inviate. Usare uno degli overload per ottenere un oggetto metrica per l'accesso alle funzionalità di pre-aggregazione dell'SDK.

Se si implementa una logica di preaggregazione personalizzata, è possibile usare il metodo per inviare le aggregazioni risultanti. Se l'applicazione richiede l'invio di un elemento di telemetria separato in ogni occasione senza aggregazione nel tempo, è probabile che si verifichi un caso d'uso per i dati di telemetria degli eventi. Vedi .

Application Insights può creare un grafico delle metriche non associate a eventi specifici. Ad esempio, è possibile monitorare la lunghezza della coda a intervalli regolari. Con le metriche, le singole misurazioni sono di minore interesse rispetto alle variazioni e alle tendenze e quindi i grafici statistici sono utili.

Per inviare metriche ad Application Insights, è possibile usare l'API . Esistono due modi per inviare una metrica:

• Valore singolo. Ogni volta che si esegue una misurazione nell'applicazione, si invia il valore corrispondente ad Application Insights.

  Si supponga, ad esempio, di avere una metrica che descrive il numero di elementi in un contenitore. Durante un determinato periodo di tempo, inserire prima tre elementi nel contenitore e quindi rimuovere due elementi. Pertanto, chiameresti due volte. Prima di tutto, passare il valore e quindi passare il valore . Application Insights archivia entrambi i valori.

• Aggregazione. Quando si lavora con le metriche, ogni singola misura è raramente di interesse. È invece importante un riepilogo di ciò che è accaduto durante un determinato periodo di tempo. Un riepilogo di questo tipo è denominato aggregazione.

  Nell'esempio precedente la somma delle metriche di aggregazione per il periodo di tempo è e il conteggio dei valori delle metriche è . Quando si usa l'approccio di aggregazione, si richiama una sola volta per periodo di tempo e si inviano i valori di aggregazione. È consigliabile questo approccio perché può ridurre significativamente il costo e il sovraccarico delle prestazioni inviando meno punti dati ad Application Insights, pur raccogliendo tutte le informazioni pertinenti.

Esempi di valore singolo

Per inviare un singolo valore metrica:

.NET

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 42.0});

Metriche personalizzate in Log Analytics

I dati di telemetria sono disponibili nella tabella in Application Insights Analytics. Ogni riga rappresenta una chiamata a nell'app.

• : somma delle misurazioni. Per ottenere il valore medio, dividere per .
• : numero di misurazioni aggregate in questa chiamata.

Annotazioni

valueCount ha un valore minimo di uno; il record stesso rappresenta un elemento.

Visualizzazioni pagina

Nell'app per dispositivi o per pagine web, la telemetria delle visualizzazioni delle pagine viene inviata automaticamente quando ogni schermata o pagina viene caricata. Tuttavia, è possibile modificare l'impostazione predefinita per tenere traccia delle visualizzazioni di pagina in momenti più o diversi. Ad esempio, in un'app che visualizza schede o riquadri, è possibile tenere traccia di una pagina ogni volta che l'utente apre un nuovo riquadro.

I dati utente e di sessione vengono inviati come proprietà insieme alle visualizzazioni di pagina, così i grafici utenti e di sessione si animano quando sono presenti dati di telemetria di visualizzazione di pagina.

Visualizzazioni pagina personalizzate

.NET

telemetry.TrackPageView("GameReviewPage");

Non applicabile.

Telemetria delle pagine in Log Analytics

In Log Analytics due tabelle mostrano i dati delle operazioni del browser:

• : contiene i dati relativi all'URL e al titolo della pagina.
• : contiene dati sulle prestazioni del client, ad esempio il tempo impiegato per elaborare i dati in ingresso.

Per trovare quanto tempo il browser richiede per elaborare pagine diverse:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Per scoprire la popolarità di browser diversi:

pageViews
| summarize count() by client_Browser

Per associare le visualizzazioni di pagina alle chiamate AJAX, collegare con le dipendenze:

pageViews
| join (dependencies) on operation_Id

TrackRequest

L'SDK del server usa per registrare le richieste HTTP.

È anche possibile chiamarlo manualmente se si desidera simulare le richieste in un contesto in cui non è in esecuzione il modulo del servizio Web.

Il modo consigliato per inviare i dati di telemetria delle richieste è la posizione in cui la richiesta funge da contesto operativo.

Contesto dell'operazione

È possibile correlare gli elementi di telemetria insieme associandoli al contesto dell'operazione. Il modulo standard di rilevamento delle richieste esegue le eccezioni e altri eventi inviati durante l'elaborazione di una richiesta HTTP. In Ricerca e Analisi è possibile trovare facilmente tutti gli eventi associati alla richiesta usando il relativo ID operazione.

Quando si tiene traccia dei dati di telemetria manualmente, il modo più semplice per garantire la correlazione dei dati di telemetria consiste nell'usare questo modello:

.NET

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

Per altre informazioni sulla correlazione, vedere Correlazione dei dati di telemetria in Application Insights.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Insieme all'impostazione di un contesto dell'operazione, crea un elemento di telemetria del tipo specificato. Invia l'elemento di telemetria quando si elimina l'operazione o si chiama esplicitamente . Se si usa come tipo di telemetria, la relativa durata viene impostata sull'intervallo di tempo compreso tra inizio e arresto.

Gli elementi di telemetria segnalati all'interno di un ambito operativo diventano sotto-elementi di tale operazione. È possibile annidare i contesti dell'operazione.

In Ricerca il contesto dell'operazione viene usato per creare l'elenco Elementi correlati .

Screenshot che mostra l'elenco Elementi correlati.

Per altre informazioni sul rilevamento delle operazioni personalizzate, vedere Track custom operations with Application Insights .NET SDK.For more information on custom operations tracking, see Track custom operations with Application Insights .NET SDK.

Richieste in Log Analytics

In Application Insights Analytics le richieste sono visualizzate nella tabella.

Se il campionamento è in funzione, la proprietà mostra un valore maggiore di . Ad esempio, significa che di 10 chiamate a , il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle richieste e della durata media segmentata in base ai nomi delle richieste, usare il codice, ad esempio:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Inviare eccezioni ad Application Insights:

• Per contarli, come indicazione della frequenza di un problema.
• Per esaminare le singole occorrenze.

I report includono le analisi dello stack.

.NET

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Gli SDK rilevano automaticamente molte eccezioni, quindi non è sempre necessario chiamare in modo esplicito.

Eccezioni in Log Analytics

In Application Insights Analytics le eccezioni vengono visualizzate nella tabella.

Se il campionamento è in funzione, la proprietà mostra un valore maggiore di . Ad esempio, significa che di 10 chiamate a , il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle eccezioni segmentate per tipo di eccezione, usare il codice, ad esempio:

exceptions
| summarize sum(itemCount) by type

La maggior parte delle informazioni importanti sullo stack è già estratta in variabili separate, ma è possibile separare la struttura per ottenere di più. Poiché questa struttura è dinamica, è necessario eseguire il cast del risultato al tipo previsto. Per esempio:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Per associare le eccezioni alle richieste correlate, utilizza un join:

exceptions
| join (requests) on operation_Id

TrackTrace

Usare per diagnosticare i problemi mediante l'invio di una traccia di navigazione ad Application Insights. È possibile inviare blocchi di dati di diagnostica ed esaminarli in Cerca.

.NET

In .NET Log adapter usare questa API per inviare log di terze parti al portale.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Registrare un evento di diagnostica, ad esempio l'immissione o l'uscita di un metodo.

Parametro	Description
message	Dati di diagnostica. Può essere molto più lungo di un nome.
properties	Mapping da stringa a stringa. Altri dati vengono usati per filtrare le eccezioni nel portale. Di default è vuoto.
severityLevel	Valori supportati: SeverityLevel.ts.

È possibile cercare il contenuto dei messaggi, ma a differenza dei valori delle proprietà, non è possibile filtrarlo.

Il limite di dimensioni su è molto superiore al limite per le proprietà. Un vantaggio di è che è possibile inserire dati relativamente lunghi nel messaggio. Ad esempio, è possibile codificare i dati POST in questa posizione.

È anche possibile aggiungere un livello di gravità al messaggio. Analogamente ad altri dati di telemetria, è possibile aggiungere valori di proprietà per filtrare o cercare set di tracce diversi. Per esempio:

.NET

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Non applicabile.

In Ricerca è quindi possibile filtrare facilmente tutti i messaggi di un particolare livello di gravità correlato a un determinato database.

Tracce in Log Analytics

In Application Insights Analytics le chiamate a vengono visualizzate nella tabella.

Se il campionamento è in funzione, la proprietà mostra un valore maggiore di . Ad esempio, significa che di 10 chiamate a , il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle chiamate di traccia, usare codice come .

TrackDependency

Usare la chiamata per tenere traccia dei tempi di risposta e delle percentuali di esito positivo delle chiamate a un frammento di codice esterno. I risultati vengono visualizzati nei grafici delle dipendenze nel portale. Il frammento di codice seguente deve essere aggiunto ovunque venga effettuata una chiamata di dipendenza.

Annotazioni

Per .NET e .NET Core, in alternativa è possibile usare il metodo TelemetryClient.StartOperation (estensione) che riempie le proprietà DependencyTelemetry necessarie per la correlazione e altre proprietà come l'ora di inizio e la durata, quindi non è necessario creare un timer personalizzato come negli esempi seguenti. Per altre informazioni, vedere la sezione relativa al rilevamento delle dipendenze in uscita in Tracciare operazioni personalizzate con l'SDK Application Insights .NET.

.NET

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Tenere presente che gli SDK del server includono un modulo di dipendenza che individua e tiene traccia di determinate chiamate di dipendenza automaticamente, ad esempio ai database e alle API REST. È necessario installare un agente nel server per eseguire il funzionamento del modulo.

Questa chiamata viene usata se si desidera tenere traccia delle chiamate che il rilevamento automatico non intercetta.

Per disattivare il modulo di rilevamento delle dipendenze standard in C#, modificare ApplicationInsights.config ed eliminare il riferimento a .

Dipendenze in Log Analytics

In Application Insights Analytics le chiamate sono visualizzate nella tabella.

Se il campionamento è attivo, la proprietà mostra un valore maggiore di 1. Ad esempio, significa che di 10 chiamate a , il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle dipendenze segmentate per componente di destinazione, usare il codice, ad esempio:

dependencies
| summarize sum(itemCount) by target

Per associare le dipendenze alle richieste correlate, è possibile usare un join:

dependencies
| join (requests) on operation_Id

Cancellazione dei dati

In genere, l'SDK invia i dati a intervalli fissi, in genere 30 secondi o ogni volta che il buffer è pieno, che in genere è di 500 elementi. In alcuni casi, potrebbe essere necessario scaricare il buffer. Un esempio è se si usa l'SDK in un'applicazione che si arresta.

.NET

Quando si usa , è consigliabile usare questo modello:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Quando si usa , è consigliabile usare questo modello:

await telemetryClient.FlushAsync()
// No need to sleep

Si consiglia di svuotare sempre durante l'arresto dell'applicazione per garantire che i dati di telemetria non vengano persi.

Annotazioni

Configurazione di Autoflush: Abilitare l'autoflush nel file web.config può causare un degrado delle prestazioni nelle applicazioni .NET strumentate con Application Insights. Con la funzione autoflush abilitata, ogni invocazione dei metodi di comporta l'invio di singoli elementi di telemetria, ognuno dei quali viene inviato come una richiesta web distinta al servizio di raccolta dati. Ciò può causare potenzialmente l'esaurimento della rete e dell'archiviazione nei server Web. Per migliorare le prestazioni, è consigliabile disabilitare il flusso automatico e anche usare ServerTelemetryChannel, progettato per una trasmissione dei dati di telemetria più efficace.

La funzione è asincrona per il canale di telemetria del server.

telemetry.flush();

Utenti autenticati

In un'app Web, gli utenti sono identificati dai cookie per impostazione predefinita. Un utente potrebbe essere conteggiato più volte se accede all'app da un computer o un browser diverso o se elimina i cookie.

Se gli utenti accedono all'app, è possibile ottenere un conteggio più accurato impostando l'ID utente autenticato nel codice del browser. Non è necessario usare il nome di accesso effettivo dell'utente. Deve essere solo un ID univoco per l'utente. Non deve includere spazi o caratteri .

L'ID utente viene impostato anche in un cookie di sessione e inviato al server. Se l'SDK del server è installato, l'ID utente autenticato viene inviato come parte delle proprietà di contesto dei dati di telemetria client e server. È quindi possibile filtrare e cercare su di esso.

Se l'app raggruppa gli utenti negli account, è anche possibile passare un identificatore per l'account. Si applicano le stesse restrizioni relative ai caratteri.

In Esplora metriche è possibile creare un grafico che conta utenti, autenticati e account utente.

È anche possibile cercare punti dati client con nomi utente e account specifici.

Annotazioni

La proprietà EnableAuthenticationTrackingJavaScript nella classe ApplicationInsightsServiceOptions in .NET Core SDK semplifica la configurazione JavaScript necessaria per inserire il nome utente come ID di autenticazione per ogni traccia inviata da Application Insights JavaScript SDK.

Quando questa proprietà è impostata su true, il nome utente dell'utente nella ASP.NET Core viene stampato insieme ai dati di telemetria client-side. Per questo motivo, l'aggiunta manuale di appInsights.setAuthenticatedUserContext non è più necessaria perché è già inserita dall'SDK per ASP.NET Core. L'Auth ID viene inviato anche al server dove l'SDK in .NET Core lo identifica e utilizza per la telemetria lato server, come descritto nel riferimento dell'API JavaScript.

Per le applicazioni JavaScript che non funzionano nello stesso modo di ASP.NET Core MVC, ad esempio app Web SPA, è comunque necessario aggiungere appInsights.setAuthenticatedUserContext manualmente.

Filtrare, cercare e segmentare i dati usando le proprietà

È possibile associare proprietà e misurazioni agli eventi, alle metriche, alle visualizzazioni di pagina, alle eccezioni e ad altri dati di telemetria.

Le proprietà sono valori stringa che è possibile usare per filtrare i dati di telemetria nei report di utilizzo. Ad esempio, se la tua app fornisce diversi giochi, puoi allegare il nome del gioco a ogni evento in modo da poter vedere quali giochi sono più popolari.

Esiste un limite di 8.192 sulla lunghezza della stringa. Per inviare blocchi di dati di grandi dimensioni, usare il parametro message di .

Le metriche sono valori numerici che possono essere presentati graficamente. Ad esempio, potresti voler vedere se c'è un aumento graduale dei punteggi ottenuti dai giocatori. I grafici possono essere segmentati in base alle proprietà inviate con l'evento in modo da poter ottenere grafici separati o in pila per giochi diversi.

I valori delle metriche devono essere maggiori o uguali a 0 per essere visualizzati correttamente.

Esistono alcuni limiti al numero di proprietà, valori delle proprietà e metriche che è possibile usare.

.NET

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Importante

Assicurarsi di non registrare informazioni personali nelle proprietà.

Modo alternativo per impostare proprietà e metriche

Se è più conveniente, è possibile raccogliere i parametri di un evento in un oggetto separato:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Avvertimento

Non riutilizzare la stessa istanza dell'elemento di telemetria ( in questo esempio) per chiamare più volte. Questa procedura potrebbe causare l'invio dei dati di telemetria con una configurazione non corretta.

Misurazioni e proprietà personalizzate in Log Analytics

In Log Analytics, le metriche e le proprietà personalizzate vengono visualizzate negli attributi /customMeasurements e customDimensions di ogni record di telemetria.

Ad esempio, se si aggiunge una proprietà denominata "game" ai dati di telemetria della richiesta, questa query conta le occorrenze di valori diversi di "gioco" e mostra la media della metrica personalizzata "score":

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Si noti che:

• Quando si estrae un valore dal JSON o , ha un tipo dinamico, quindi è necessario effettuare il cast su o .
• Per tenere conto della possibilità di campionamento, usare non .

Eventi di temporizzazione

A volte si vuole creare un grafico del tempo necessario per eseguire un'azione. Ad esempio, potresti voler sapere quanto tempo gli utenti impiegano per prendere in considerazione le scelte in un gioco. Per ottenere queste informazioni, usare il parametro di misurazione.

.NET

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Proprietà predefinite per i dati di telemetria personalizzati

Se desiderate impostare valori predefiniti delle proprietà per alcuni eventi personalizzati che scrivete, configurateli in un'istanza di . Sono collegati a ogni elemento di telemetria inviato da tale client.

.NET

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Le singole chiamate di telemetria possono sovrascrivere i valori predefiniti nei dizionari delle proprietà.

Per aggiungere proprietà a tutti i dati di telemetria, inclusi i dati dei moduli di raccolta standard, implementare .

Disabilitare telemetria

Per arrestare e avviare dinamicamente la raccolta e la trasmissione dei dati di telemetria:

.NET

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

Per disabilitare gli agenti di raccolta standard selezionati, ad esempio contatori delle prestazioni, richieste HTTP o dipendenze, in fase di inizializzazione, concatenare i metodi di configurazione al codice di inizializzazione dell'SDK.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Per disabilitare questi agenti di raccolta dopo l'inizializzazione, utilizzare l'oggetto Configuration: .

Modalità sviluppatore

Durante il debug, è utile che i dati di telemetria vengano accelerati attraverso la pipeline in modo da poter visualizzare immediatamente i risultati. Si ottengono anche altri messaggi che consentono di tracciare eventuali problemi con i dati di telemetria. Disattivarlo nell'ambiente di produzione perché potrebbe rallentare l'app.

.NET

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Per Node.js, puoi abilitare la modalità sviluppatore attivando la registrazione interna tramite e impostando su , il che consente di inviare i dati di telemetria non appena vengono raccolti.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Imposta la chiave di strumentazione per la telemetria personalizzata selezionata

.NET

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

La stringa di connessione dinamica

Per evitare di combinare i dati di telemetria dagli ambienti di sviluppo, test e produzione, è possibile creare risorse di Application Insights separate e modificarne le chiavi, a seconda dell'ambiente.

Anziché ottenere la chiave di strumentazione dal file di configurazione, è possibile impostarla nel codice. Impostare la chiave in un metodo di inizializzazione, ad esempio global.aspx.cs in un servizio ASP.NET:

.NET

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

Non applicabile.

TelemetryContext

dispone di una proprietà Context, che contiene valori inviati insieme a tutti i dati di telemetria. Normalmente vengono impostati dai moduli di telemetria standard, ma è anche possibile impostarli manualmente. Per esempio:

telemetry.Context.Operation.Name = "MyOperationName";

Se si imposta uno di questi valori manualmente, è consigliabile rimuovere la riga pertinente da ApplicationInsights.config in modo che i valori e i valori standard non vengano confusi.

• Componente: l'app e la relativa versione.
• Dispositivo: dati sul dispositivo in cui è in esecuzione l'app. Nelle app Web si tratta del server o del dispositivo client da cui vengono inviati i dati di telemetria.
• InstrumentationKey: risorsa di Application Insights in Azure in cui appaiono i dati di telemetria. In genere viene prelevato da ApplicationInsights.config.
• Posizione: posizione geografica del dispositivo.
• Operazione: nelle applicazioni web, la richiesta HTTP corrente. In altri tipi di app è possibile impostare questo valore per raggruppare gli eventi.
  • ID: valore generato che correla diversi eventi in modo che quando si esamina qualsiasi evento in Ricerca diagnostica, è possibile trovare elementi correlati.
  • Nome: identificatore, in genere l'URL della richiesta HTTP.
  • SyntheticSource: se non null o vuoto, una stringa che indica che l'origine della richiesta è stata identificata come un robot o un test Web. Per impostazione predefinita, viene esclusa dai calcoli in Esplora metriche.
• Sessione: sessione dell'utente. L'ID è impostato su un valore generato, che viene modificato quando l'utente non è stato attivo per un periodo di tempo.
• Utente: informazioni sull'utente.

Limits

Esistono alcuni limiti al numero di metriche ed eventi per applicazione, ovvero per connection string. I limiti dipendono dal piano tariffario scelto.

Risorsa	Limite predefinito	Limite massimo	Note
Totale dati al giorno	100 GB	Contattare il supporto tecnico.	È possibile impostare un limite per ridurre i dati. Se sono necessari più dati, è possibile aumentare il limite nel portale fino a 1.000 GB. Per capacità maggiori di 1.000 GB, inviare un messaggio di posta elettronica a .
Throttling	32.000 eventi/secondo	Contattare il supporto tecnico.	Il limite viene misurato nell'arco di un minuto.
Log di conservazione dei dati	Da 30 a 730 giorni	730 giorni	Questa risorsa è per Log.
Metriche di conservazione dati	90 giorni	90 giorni	Questa risorsa è per Esplora metriche.
Conservazione dettagliata dei risultati dei test a più passaggi di disponibilità	90 giorni	90 giorni	Questa risorsa fornisce risultati dettagliati per ogni passaggio.
Dimensioni massime dei dati di telemetria	64 kB	64 kB
Numero massimo di dati di telemetria per batch	64.000	64.000
Lunghezza nomi di proprietà e metriche	150	150	Vedere schemi di tipo.
Lunghezza stringa valore di proprietà	8,192	8,192	Vedere schemi di tipo.
Lunghezza del messaggio di traccia e di eccezione	32,768	32,768	Vedere schemi di tipo.
Numero di test di disponibilità per ogni risorsa di Application Insights	100	100
Numero di test di disponibilità per gruppo di risorse	800	800	Vedere Azure Resource Manager
Numero massimo di reindirizzamenti per test di disponibilità	10	10
Frequenza minima dei test di disponibilità	300 secondi		Frequenze di test personalizzate o inferiori a 5 minuti richiedono implementazioni TrackAvailability personalizzate.
.NET Profiler e Snapshot Debugger conservazione dei dati	Due settimane	Contattare il supporto tecnico. Il limite massimo di conservazione è di sei mesi.
.NET Profiler dati inviati al giorno	Nessun limite	Nessun limite.
Dati di Snapshot Debugger inviati al giorno	30 snapshot al giorno per ogni app monitorata	Nessun limite.	Il numero di snapshot raccolti per applicazione può essere modificato tramite la configurazione.

Per altre informazioni sui prezzi e sulle quote, vedere Fatturazione di Application Insights.

Per evitare di raggiungere il limite di velocità dei dati usare il campionamento.

Per determinare per quanto tempo vengono conservati i dati, vedere Conservazione e privacy dei dati.

Applicazioni di esempio

Applicazione console .NET Core: Usare questo esempio se si utilizza un'applicazione console scritta in .NET Core (2.0 o versione successiva) o .NET Framework (4.7.2 o versione successiva).

Attività in background ASP.NET Core con servizi ospitati: usa questo esempio se si sta usando ASP.NET Core e si stanno creando attività in background in base a indicazioni ufficiali.

.NET Core Worker Service: usare questo esempio se si dispone di un'applicazione di .NET Worker Service conforme alle linee guida ufficiali.

Risoluzione dei problemi

Vedere gli articoli dedicati sulla risoluzione dei problemi per .NET e Node.js.

Testare la connettività tra l'host dell'applicazione e il servizio di inserimento

Gli SDK e gli agenti di Application Insights inviano dati di telemetria per l'inserimento come chiamate REST agli endpoint di inserimento. È possibile testare la connettività dal server Web o dal computer host dell'applicazione agli endpoint del servizio di inserimento usando client REST non elaborati da comandi PowerShell o curl. Consulta Risolvere la mancanza di telemetria delle applicazioni in Azure Monitor Application Insights.

SDK open source

Leggere e contribuire al codice per .NET e Node.js.

Note di rilascio

• Note sulla versione di Application Insights
• rilasci .NET SDK su GitHub
• Rilasci del Node.js SDK su GitHub

Gli aggiornamenti del servizio riepilogano anche i principali miglioramenti di Application Insights.

Passaggi successivi

• Verificare di eseguire una versione supportata di Application Insights SDK.
• Per informazioni sul modello di dati e sui tipi di Application Insights, vedere il modello di dati.
• Vedere System.Diagnostics.Activity User Guide (Guida dell'utente di System.Diagnostics.Activity) per informazioni su come correlare i dati di telemetria.
• Per esaminare le domande frequenti, vedere:
  • Domande frequenti su ASP.NET
  • Domande frequenti ASP.NET Core
  • Domande frequenti sul servizio di lavoro
  • Domande frequenti suNode.js
  • API per gli eventi personalizzati e le domande frequenti sulle metriche