Compartir a través de

Supervisión de aplicaciones y servicios de .NET con Application Insights (API clásica)

Nota:

Revise la guía de soporte técnico del SDK de Application Insights para obtener la directiva de soporte técnico del SDK de Classic API.

Precaución

Se recomienda la Distribución de OpenTelemetry de Azure Monitor para nuevas aplicaciones o clientes para potenciar Application Insights de Azure Monitor. La Distribución de OpenTelemetry de Azure Monitor ofrece una funcionalidad y experiencia similares al SDK de Application Insights. Es posible migrar desde el SDK de Application Insights usando las guías de migración para .NET, Node.js, y Python, pero todavía estamos trabajando para agregar unas pocas características más para la compatibilidad con versiones anteriores.

En este artículo se explica cómo habilitar y configurar Application Insights para aplicaciones de ASP.NET, ASP.NET Core y Worker Service (no HTTP). Application Insights puede recopilar la siguiente telemetría de las aplicaciones:

  • Requests
  • Dependencias
  • Excepciones
  • Contadores de rendimiento
  • Seguimientos (registros)
  • Latidos
  • Eventos y métricas personalizados (requiere instrumentación manual)
  • Vistas de página (requiere el SDK de JavaScript para páginas web)
  • Pruebas de disponibilidad (requiere configurar manualmente pruebas de disponibilidad)

Escenarios admitidos

Nota:

El SDK de Application Insights para ASP.NET Core y el SDK para Worker Service pueden supervisar las aplicaciones independientemente de dónde o cómo se ejecuten. Si la aplicación se está ejecutando y tiene conectividad de red a Azure, se pueden recopilar datos de telemetría.

Compatible ASP.NET ASP.NET Core Servicio para trabajadores
Sistema operativo Windows Windows, Linux o macOS Windows, Linux o macOS
Método de hospedaje En proceso (IIS o IIS Express) En el proceso o fuera del proceso Consola o servicio en segundo plano (se ejecuta como un proceso, normalmente a través de la CLI de dotnet o como un servicio de Windows o un demonio de Linux)
Método de implementación Web Deploy, MSI o copia manual de archivos Dependiente del marco o independiente Dependiente del marco o independiente
Servidor web Internet Information Services (IIS) Internet Information Server (IIS) o Kestrel No aplicable (ningún servidor web; diseñado para cargas de trabajo que no son HTTP, como mensajería, tareas en segundo plano y aplicaciones de consola)
Plataforma de hospedaje Azure App Service (Windows), Azure Virtual Machines o servidores locales La característica Web Apps de Azure App Service, Azure Virtual Machines, Docker y Azure Kubernetes Service (AKS) Azure Virtual Machines, Azure Kubernetes Service (AKS), contenedores o cualquier entorno en el que se admita .NET Core
Versión de .NET .NET Framework 4.6.1 y versiones posteriores Todas las versiones de .NET compatibles oficialmente que no están en versión preliminar Todas las versiones de .NET compatibles oficialmente que no están en versión preliminar
IDE Visual Studio Visual Studio, Visual Studio Code o línea de comandos Visual Studio, Visual Studio Code o línea de comandos

Nota:

Un servicio de trabajo es una aplicación en segundo plano de ejecución prolongada que ejecuta tareas fuera de una canalización de solicitud/respuesta HTTP. El SDK de Application Insights para el Servicio de Trabajo se puede usar en el Servicio de Trabajo de .NET Core recién introducido, tareas en segundo plano en ASP.NET Core y aplicaciones de consola como .NET Core y .NET Framework.

El SDK del servicio de trabajo no realiza ninguna recopilación de telemetría por sí misma. En su lugar, incluye otros recopiladores automáticos conocidos de Application Insights, como DependencyCollector, PerfCounterCollector y ApplicationInsightsLoggingProvider. Este SDK expone métodos de extensión en IServiceCollection para habilitar y configurar la recopilación de telemetría.

Adición de Application Insights

Prerrequisitos

Creación de una aplicación web básica

Si aún no tiene una aplicación web en funcionamiento, puede usar las siguientes instrucciones para crear una.

  1. Abre Visual Studio.
  2. Seleccione Crear un nuevo proyecto.
  3. Elija ASP.NET aplicación web (.NET Framework) con C# y seleccione Siguiente.
  4. Escriba un nombre de proyecto y, a continuación, seleccione Crear.
  5. Elija MVC y, a continuación, seleccione Crear.

Agregar Application Insights automáticamente (Visual Studio)

Esta sección le guía a través de la adición automática de Application Insights a una aplicación web basada en plantillas.

Nota:

Hay un problema conocido en Visual Studio 2019: el almacenamiento de la clave de instrumentación o la cadena de conexión en un secreto de usuario se interrumpe para las aplicaciones basadas en .NET Framework. En última instancia, la clave debe codificarse de forma dura en el archivo Applicationinsights.config para solucionar este error.

Desde dentro del proyecto de aplicación web de ASP.NET en Visual Studio:

  1. Seleccione Proyecto>Agregar telemetría de Application Insights>Application Insights SDK (local) (SDK de Application Insights [local])>Siguiente>Finalizar>Cerrar.

  2. Abra el archivo ApplicationInsights.config.

  3. Antes de la etiqueta </ApplicationInsights> de cierre, agregue una línea que contenga la cadena de conexión del recurso de Application Insights. Busque la cadena de conexión en el panel de información general del recurso de Application Insights recién creado.

    <ConnectionString>Copy connection string from Application Insights Resource Overview</ConnectionString>

  4. Seleccione Proyecto>Administrar paquetes NuGet>Actualizaciones. A continuación, actualice el paquete NuGet Microsoft.ApplicationInsights a la versión estable más reciente.

  5. Ejecute la aplicación seleccionando IIS Express. Se abrirá una aplicación ASP.NET básica. A medida que navegas por las páginas del sitio, la telemetría se envía a Application Insights.

Adición manual de Application Insights (sin Visual Studio)

Esta sección le guía a través de la adición manual de Application Insights a una aplicación web basada en plantillas.

  1. Agregue los siguientes paquetes NuGet y sus dependencias al proyecto:

  2. En algunos casos, el archivo ApplicationInsights.config se crea automáticamente. Si el archivo ya está presente, vaya al paso 4.

    En caso de que faltara, créela usted mismo. En el directorio raíz de una aplicación de ASP.NET, cree un archivo denominado ApplicationInsights.config.

  3. Copie la siguiente configuración XML en el archivo recién creado:


    Expandir para ver la configuración 
    <?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. Agregue la cadena de conexión, que se puede realizar de dos maneras:

    • (Recomendado) Establecer la cadena de conexión en la configuración.

      Antes de la etiqueta de cierre </ApplicationInsights> en ApplicationInsights.config, agregue la cadena de conexión para el recurso de Application Insights. Puede localizar la cadena de conexión en el panel de información general del recurso de Application Insights recién creado.

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

    • Establezca la cadena de conexión en el código.

      Proporcione una cadena de conexión en la clase program.cs.

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

  5. En el mismo nivel del proyecto que el archivo ApplicationInsights.config, cree una carpeta con el nombre ErrorHandler con un nuevo archivo de C# denominado AiHandleErrorAttribute.cs. El contenido del archivo tiene ahora este aspecto:

    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. En la carpeta App_Start abra el archivo FilterConfig.cs y cámbielo para que coincida con el ejemplo:

    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. Si Web.config ya está actualizado, omita este paso. De lo contrario, actualice el archivo de la forma siguiente:


    Expandir para ver la configuración 
    <?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>

En este punto, ya ha configurado correctamente la supervisión de aplicaciones del lado servidor. Si ejecuta la aplicación web, verá que la telemetría comienza a aparecer en Application Insights.

Verifique que Application Insights recibe datos de telemetría

Ejecute su aplicación y realice solicitudes. Ahora, la telemetría debería fluir hacia Application Insights. El SDK de Application Insights recopila automáticamente las solicitudes web entrantes en la aplicación, junto con la telemetría siguiente.

Configuración de la telemetría

En esta sección

Métricas en tiempo real

Live metrics se puede usar para comprobar rápidamente si la supervisión de aplicaciones con Application Insights está configurada correctamente. La telemetría puede tardar unos minutos en aparecer en Azure Portal, pero el panel de métricas dinámicas muestra el uso de CPU del proceso en ejecución casi en tiempo real. También puede mostrar otros tipos de telemetría, como las solicitudes, las dependencias y los seguimientos.

Nota:

La característica Live Metrics se habilitará de forma predeterminada si se incorpora mediante las instrucciones recomendadas para aplicaciones .NET.

Habilitación de Live Metrics mediante código en cualquier aplicación .NET

Para configurar Live Metrics manualmente:

  1. Instale el paquete NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

  2. El siguiente código de aplicación de consola de ejemplo muestra la configuración de Live Metrics:

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.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
            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-HERE";
            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();
            }
        }
    }
}

Seguimientos (registros)

En esta sección se explica cómo enviar registros de seguimiento de diagnóstico desde ASP.NET o ASP.NET aplicaciones principales a Application Insights y, a continuación, explorar o buscar esos registros en el portal.

Puede usar registros de seguimiento para identificar los seguimientos asociados a cada solicitud de usuario y correlacionarlos con otros eventos e informes de excepciones.

Application Insights captura los registros de ASP.NET Core y otras aplicaciones de .NET a través de ILogger y de ASP.NET clásico (.NET Framework) a través del SDK y los adaptadores clásicos.

Nota:

  • De manera predeterminada, el proveedor de Application Insights solo envía registros con una gravedad de Warning o superior. Para incluir Information o bajar los registros, actualice la configuración del nivel de registro en appsettings.json.

  • El Microsoft.ApplicationInsights.WorkerService paquete NuGet, que se usa para habilitar Application Insights para servicios en segundo plano, está fuera del ámbito.

  • Para revisar las preguntas más frecuentes (P+F), consulte Registrarse con preguntas más frecuentes sobre .NET.

Elija un enfoque de registro para emitir registros de diagnóstico que Application Insights pueda recopilar.

Instalación del registro en la aplicación

En el caso de las aplicaciones de ASP.NET clásicas que usan el seguimiento de System.Diagnostics, configure un TraceListener de Application Insights en la configuración.

Agregue un agente de escucha a web.config o app.config:

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

Nota:

El módulo de captura de registros es un adaptador útil para registradores de terceros. Sin embargo, si aún no usa NLog, log4Net o System.Diagnostics.Trace, considere la posibilidad de llamar directamente a TrackTrace() de Application Insights .

Configuración de Application Insights para recopilar registros

Opción 1: Agregue Application Insights al proyecto si aún no lo ha hecho. Al agregar Application Insights en Visual Studio, hay una opción para incluir el recopilador de registros.

Opción 2: Haga clic con el botón derecho en el proyecto en el Explorador de soluciones para configurar Application Insights. Seleccione la opción Configurar recopilación de seguimiento .

Nota:

Si falta el menú de Application Insights o la opción del recopilador de registros, consulte el artículo de solución de problemas dedicado.

Instalación manual

Use este método si el tipo de proyecto no es compatible con el instalador de Application Insights (por ejemplo, algunos escenarios de escritorio o consola) o si prefiere un control explícito de nivel de paquete.

  1. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Administrar paquetes NuGet.

  2. Busque Application Insights.

  3. Seleccione uno de los siguientes paquetes:

El paquete NuGet instala los ensamblados necesarios y modifica web.config o app.config, si procede.

Instrucciones de instalación:

Nota:

Expanda cualquiera de las secciones siguientes para obtener instrucciones de instalación específicas del paquete.


ILogger

  1. Instale los Microsoft.Extensions.Logging.ApplicationInsights.

  2. Agregue ApplicationInsightsLoggerProvider:

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

Con el paquete NuGet instalado y el proveedor registrado con la inserción de dependencias, la aplicación está lista para registrarse. Con la inserción de constructores, se necesita ILogger o la alternativa de tipo genérico ILogger<TCategoryName>. Cuando se resuelvan estas implementaciones, ApplicationInsightsLoggerProvider las proporcionará. Las excepciones o los mensajes registrados se enviarán a Application Insights.

Considere el siguiente controlador de ejemplo:

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

Para más información, consulte Registro en ASP.NET Core y ¿Qué tipo de telemetría de Application Insights se genera a partir de registros de ILogger? ¿Dónde puedo ver los registros de ILogger en Application Insights?.

Insertar llamadas de registro de diagnóstico (System.Diagnostics.Trace / log4net / NLog)

Si usa System.Diagnostics.Trace, una llamada típica sería:

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

Si prefiere log4net o NLog, use:

    logger.Warn("Slow response - database01");
Usar eventos de EventSource

Puede configurar eventos System.Diagnostics.Tracing.EventSource que se enviarán a Application Insights como seguimientos.

  1. Instale el paquete NuGet Microsoft.ApplicationInsights.EventSourceListener.

  2. Edite la TelemetryModules sección del archivo ApplicationInsights.config :

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

Para cada origen, puede establecer los parámetros siguientes:

  • Name especifica el nombre de EventSource que se va a recopilar.
  • Nivel especifica el nivel de registro que se va a recopilar: Crítico, Error, Informativo, LogAlways, Detallado o Advertencia.
  • Las palabras clave (opcional) especifican el valor entero de las combinaciones de palabras clave que se van a usar.
Uso de eventos DiagnosticSource

Puede configurar eventos System.Diagnostics.DiagnosticSource que se enviarán a Application Insights como seguimientos.

  1. Instale el paquete NuGet Microsoft.ApplicationInsights.DiagnosticSourceListener.

  2. Edite la TelemetryModules sección del archivo ApplicationInsights.config :

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

Para cada origen de diagnóstico que desees rastrear, agrega una entrada con el atributo Name establecido en el nombre de tu origen de diagnóstico.

Uso de eventos ETW

Puede configurar eventos de Seguimiento de eventos para Windows (ETW) para enviarse a Application Insights como seguimientos.

  1. Instale el paquete NuGet Microsoft.ApplicationInsights.EtwCollector.

  2. Edite la sección "TelemetryModules" del archivo ApplicationInsights.config :

Nota:

Solo se pueden recopilar eventos ETW si el proceso que hospeda el SDK se ejecuta bajo una identidad que sea miembro de Usuarios del registro de rendimiento o Administradores.

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

Para cada origen, puede establecer los parámetros siguientes:

  • ProviderName es el nombre del proveedor ETW que debe recopilarse.
  • ProviderGuid especifica el GUID del proveedor ETW cuya información se va a recopilar. Se puede usar en lugar de ProviderName.
  • Nivel define el nivel de registro que se recopilará. Puede ser Crítico, Error, Informativo, LogAlways, Detallado o Advertencia.
  • Palabras clave (opcional) establece el valor entero de las combinaciones de palabras clave que se van a usar.
Utiliza la Trace API directamente

Puede llamar directamente a la API de seguimiento de Application Insights. Los adaptadores de registro usan esta API. Por ejemplo:

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

Una ventaja de TrackTrace es que puede colocar datos relativamente largos en el mensaje. Por ejemplo, puede codificar los datos POST allí.

También puede agregar un nivel de gravedad al mensaje. Además, al igual que otros datos de telemetría, puede agregar valores de propiedad para ayudar a filtrar o buscar diferentes conjuntos de seguimientos. Por ejemplo:

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

Ahora puede filtrar fácilmente en Búsqueda de transacciones todos los mensajes de un nivel de gravedad determinado relacionado con una base de datos determinada.

Aplicación de consola

Para agregar el registro de Application Insights a las aplicaciones de la consola, primero instala los siguientes paquetes de NuGet:

En el ejemplo siguiente se usa el paquete Microsoft.Extensions.Logging.ApplicationInsights y se muestra el comportamiento predeterminado de una aplicación de consola. El paquete Microsoft.Extensions.Logging.ApplicationInsights debe usarse en una aplicación de consola o siempre que desee una implementación mínima de Application Insights sin el conjunto de características completo, como métricas, seguimiento distribuido, muestreo e inicializadores de telemetría.

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

Para más información, consulte ¿Qué tipo de telemetría de Application Insights se genera a partir de registros de ILogger? ¿Dónde puedo ver los registros de ILogger en Application Insights?

Ámbitos de registro

Nota:

Las instrucciones siguientes se aplican a escenarios de ILogger (solo ASP.NET Core y consola). No se aplica al ASP.NET clásico.

ApplicationInsightsLoggingProvider admite ámbitos de registro, que están habilitados de manera predeterminada.

Si el ámbito es de tipo IReadOnlyCollection<KeyValuePair<string,object>>, todos los pares clave-valor de la colección se agregan a los datos de telemetría de Application Insights como propiedades personalizadas. En el ejemplo siguiente, los registros se capturan como TraceTelemetry y tienen ("MyKey", "MyValue") en las propiedades.

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

Si se usa cualquier otro tipo como ámbito, se almacena en la propiedad Scope en la telemetría de Application Insights. En el siguiente ejemplo, TraceTelemetry tiene una propiedad denominada Scope que contiene el ámbito.

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

Búsqueda de los registros

Ejecute la aplicación en modo de depuración o impleméntela en directo.

En el panel de información general de la aplicación en el portal de Application Insights, seleccione Búsqueda de transacciones , donde puede:

  • Filtre en trazas de registro o en elementos con propiedades específicas.
  • Inspeccione un elemento específico en detalle.
  • Busque otros datos de registro del sistema relacionados con la misma solicitud de usuario (tiene el mismo identificador de operación).
  • Guarde la configuración de una página como favorita.

Nota:

Si la aplicación envía grandes cantidades de datos y usa el SDK de Application Insights para ASP.NET versión 2.0.0-beta3 o posterior, la característica de muestreo adaptable podría funcionar y enviar solo una parte de la telemetría. Aprenda más sobre el muestreo.

Explorar en registros de Azure Monitor

Los registros de ILogger aparecen como telemetría de seguimiento (tabla traces en Application Insights y AppTraces en Log Analytics).

Ejemplo

En Azure Portal, vaya a Application Insights y ejecute lo siguiente:

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

Seguimiento distribuido

Las arquitecturas modernas de nube y microservicios han habilitado servicios sencillos e independientes que reducen los costos al tiempo que aumentan la disponibilidad y el rendimiento. Sin embargo, ha hecho que los sistemas generales sean más difíciles de razonar sobre y depurar. El seguimiento distribuido resuelve este problema proporcionando una herramienta de perfilado de rendimiento que funciona como stack de llamadas para arquitecturas de nube y microservicios.

Azure Monitor proporciona dos experiencias para consumir datos de seguimiento distribuidos: la vista de diagnóstico de transacciones para una sola transacción o solicitud y la vista de mapa de la aplicación para mostrar cómo interactúan los sistemas.

Application Insights puede supervisar cada componente por separado y detectar qué componente es responsable de errores o degradación del rendimiento mediante la correlación de telemetría distribuida. En este artículo se explica el modelo de datos, las técnicas de propagación de contexto, los protocolos y la implementación de tácticas de correlación en diferentes lenguajes y plataformas que usa Application Insights.

** Habilitar el seguimiento distribuido a través de Application Insights mediante la autoinstrumentación o los SDK.

Los agentes y SDK de Application Insights para .NET, .NET Core, Java, Node.jsy JavaScript admiten el seguimiento distribuido de forma nativa.

Con el SDK de Application Insights adecuado instalado y configurado, la información de seguimiento se recopila automáticamente para marcos, bibliotecas y tecnologías populares por los autocoleccionadores de dependencias del SDK. La lista completa de tecnologías admitidas está disponible en la documentación de recopilación automática de dependencias.

Cualquier tecnología también puede ser rastreada de forma manual con una llamada a TrackDependency en TelemetryClient.

Modelo de datos para la correlación de telemetría

Application Insights define un modelo de datos para la correlación de telemetría distribuida. Para asociar la telemetría a una operación lógica, cada elemento de telemetría tiene un campo de contexto denominado operation_Id. Cada elemento de telemetría del seguimiento distribuido comparte este identificador. Por lo tanto, incluso si pierde la telemetría de una sola capa, todavía puede asociar la telemetría notificada por otros componentes.

Una operación lógica distribuida normalmente consta de un conjunto de operaciones más pequeñas que son solicitudes procesadas por uno de los componentes. La telemetría de solicitud define estas operaciones. Cada elemento de telemetría de solicitud tiene su propio id que lo identifica de forma única y global. Y todos los elementos de telemetría (como seguimientos y excepciones) asociados a la solicitud deben establecer en operation_parentId el valor de la solicitud id.

La telemetría de dependencias representa todas las operaciones salientes, como una llamada HTTP a otro componente. También define su propia id que es única a nivel global. La telemetría de solicitudes, que se inicia mediante esta llamada de dependencia, utiliza este id como su operation_parentId.

Puede crear una vista de la operación lógica distribuida mediante operation_Id, operation_parentIdy request.id con dependency.id. Estos campos también definen el orden de causalidad de las llamadas de telemetría.

En un entorno de microservicios, los seguimientos de los componentes pueden ir a diferentes elementos de almacenamiento. Cada componente puede tener su propia cadena de conexión en Application Insights. Para obtener telemetría para la operación lógica, Application Insights consulta los datos de cada elemento de almacenamiento.

Cuando el número de elementos de almacenamiento es grande, necesita una sugerencia sobre dónde buscar a continuación. El modelo de datos de Application Insights define dos campos para resolver este problema: request.source y dependency.target. El primer campo identifica el componente que inició la solicitud de dependencia. El segundo campo identifica qué componente devolvió la respuesta de la llamada de dependencia.

Para obtener información sobre la consulta desde varias instancias dispares, consulte Consulta de datos en áreas de trabajo, aplicaciones y recursos de Log Analytics en Azure Monitor.

Example

Veamos un ejemplo. Una aplicación denominada Precios de acciones muestra el precio actual del mercado de una acción mediante una API externa denominada Stock. La aplicación Precios de acciones tiene una página denominada Página stock que el explorador web cliente abre mediante GET /Home/Stock. La aplicación consulta la API stock mediante la llamada GET /api/stock/valueHTTP.

Puede analizar la telemetría resultante mediante la ejecución de una consulta:

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

En los resultados, todos los elementos de telemetría comparten la raíz operation_Id. Cuando se realiza una llamada Ajax desde la página, se asigna un nuevo identificador único (qJSXU) a la telemetría de dependencia y el identificador de pageView se usa como operation_ParentId. A continuación, la solicitud de servidor usa el identificador de Ajax como operation_ParentId.

tipo de artículo nombre identificación operation_ParentId operation_Id
pageView Página de inventario STYz STYz
dependencia GET /Home/Stock qJSXU STYz STYz
request GET Inicio/Inventario KqKwlrSt9PA= qJSXU STYz
dependencia GET /api/stock/value bBrf2L7mm2g= KqKwlrSt9PA= STYz

Cuando se realiza la llamada GET /api/stock/value a un servicio externo, debe conocer la identidad de ese servidor para que pueda establecer el dependency.target campo de forma adecuada. Cuando el servicio externo no admite la supervisión, target se establece en el nombre de host del servicio. Un ejemplo es stock-prices-api.com. Pero si el servicio se identifica a sí mismo devolviendo un encabezado HTTP predefinido, target contiene la identidad de servicio que permite a Application Insights crear un seguimiento distribuido consultando telemetría desde ese servicio.

Encabezados de correlación mediante TraceContext de W3C

Application Insights realiza la transición al contexto de seguimiento de W3C, que define:

  • traceparent: Contiene el identificador de operación único a nivel global y el identificador único de la llamada.
  • tracestate: incluye el contexto de trazabilidad específico del sistema.

La versión más reciente del SDK de Application Insights admite el protocolo Trace-Context, pero es posible que tenga que participar en él. (Se mantiene la compatibilidad con versiones anteriores con el protocolo de correlación anterior compatible con el SDK de Application Insights).

El protocolo HTTP de correlación, también denominado Request-Id, está en desuso. Este protocolo define dos encabezados:

  • Request-Id: lleva el identificador único global de la llamada.
  • Correlation-Context: lleva la colección de pares nombre-valor de las propiedades del seguimiento distribuido.

Application Insights también define la extensión para el protocolo HTTP de correlación. Usa pares nombre-valor Request-Context para propagar la colección de propiedades utilizadas por el autor o el destinatario de la llamada. El SDK de Application Insights usa este encabezado para establecer los campos dependency.target y request.source.

Los modelos de datos de W3C Trace-Context y de Application Insights se asignan de la siguiente manera:

Application Insights W3C TraceContext
Id de Request y Dependency parent-id
Operation_Id trace-id
Operation_ParentId parent-id del intervalo primario de este intervalo. Este campo debe estar vacío si es un intervalo raíz.

Para más información, consulte Modelo de datos de telemetría de Application Insights.

Habilitar el soporte para el seguimiento distribuido de W3C

El seguimiento distribuido basado en TraceContext de W3C está habilitado de forma predeterminada en todos los SDK recientes de .NET Framework/.NET Core, junto con la compatibilidad con versiones anteriores con el protocolo heredado Request-Id .

Correlación de telemetría

La correlación se controla de forma predeterminada al incorporar una aplicación. No se requieren acciones especiales.

El entorno de ejecución de .NET admite la ejecución distribuida con la ayuda de Activity y DiagnosticSource.

El SDK de Application Insights para .NET usa DiagnosticSource y Activity para recopilar y correlacionar la telemetría.

Dependencias

Dependencias con seguimiento automático

Los SDK de Application Insights para .NET y .NET Core se suministran con DependencyTrackingTelemetryModule, un módulo de telemetría que recopila dependencias automáticamente. El módulo DependencyTrackingTelemetryModule se envía como el paquete NuGet Microsoft.ApplicationInsights.DependencyCollector y se trae automáticamente cuando se usa el paquete NuGet de Microsoft.ApplicationInsights.Web o el paquete NuGet de Microsoft.ApplicationInsights.AspNetCore.

Actualmente, DependencyTrackingTelemetryModule hace un seguimiento automático de las siguientes dependencias:

Dependencias Detalles
HTTP/HTTPS (Protocolo de Transferencia de Hipertexto seguro) Llamadas HTTP/HTTPS locales o remotas.
Llamadas WCF Solo hace un seguimiento automáticamente si se usan enlaces basados en HTTP.
SQL Llamadas realizadas con SqlClient. Consulte la sección Seguimiento avanzado de SQL para obtener una consulta SQL completa para capturar consultas SQL.
Azure Blob Storage, Table Storage o Queue Storage Llamadas realizadas con el cliente de Azure Storage.
SDK cliente de Azure Event Hubs Use el paquete más reciente: https://nuget.org/packages/Azure.Messaging.EventHubs.
SDK cliente de Azure Service Bus Use el paquete más reciente: https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB Se realiza un seguimiento automático si se usa HTTP/HTTPS. El seguimiento de las operaciones en modo directo con TCP se captura automáticamente mediante el paquete de vista previa >= 3.33.0-preview. Para obtener más información, visite la documentación.

Si la dependencia no se recopila automáticamente, puede rastrearla manualmente con una llamada a la función TrackDependency.

Para más información sobre cómo funciona el seguimiento de dependencias, consulte Seguimiento de dependencias en Application Insights.

Configuración de seguimiento automático de dependencias en aplicaciones de consola

Para hacer un seguimiento automático de las dependencias de aplicaciones de consola de .NET, instale el paquete NuGet Microsoft.ApplicationInsights.DependencyCollector e inicialice DependencyTrackingTelemetryModule:

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

Nota:

En el caso de las aplicaciones de consola de .NET Core, TelemetryConfiguration.Active se ha quedado obsoleto.

Seguimiento manual las dependencias

Los siguientes son ejemplos de las dependencias que no se recopilan automáticamente y requieren seguimiento manual:

  • Azure Cosmos DB se rastrea automáticamente solo si se usa HTTP/HTTPS. Application Insights no captura automáticamente el modo TCP para las versiones del SDK anteriores a 2.22.0-Beta1.
  • Redis

Para las dependencias que el SDK no recopila automáticamente, puede realizar un seguimiento manual mediante la API de TrackDependency que utilizan los módulos de recolección automática estándar.

Ejemplo

Si crea su código con un ensamblado que no ha escrito usted mismo, podría cronometrar todas las llamadas al mismo. Este escenario le permitiría averiguar qué contribución hace a los tiempos de respuesta.

Para que estos datos se muestren en los gráficos de dependencia en Application Insights, envíelos mediante TrackDependency:


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

Como alternativa, TelemetryClient proporciona los métodos de extensión StartOperation y StopOperation que pueden usarse para realizar un seguimiento manual de las dependencias, tal como se muestra en Seguimiento de dependencias de salida.

Deshabilitación del módulo de seguimiento de dependencias estándar

Para más información, consulte Módulos de telemetría.

Seguimiento de SQL avanzado para obtener la consulta SQL completa

Para las llamadas SQL, el nombre del servidor y la base de datos siempre se recopilan y almacenan como el nombre de la DependencyTelemetry recopilada. Otro campo denominado datos, puede contener el texto completo de la consulta SQL.

Nota:

Azure Functions requiere una configuración independiente para habilitar la recopilación de texto de SQL. Para obtener más información, consulte Habilitación de la recopilación de consultas SQL.

Para las aplicaciones ASP.NET, el texto completo de la consulta SQL se recopila mediante la instrumentación de código byte, lo que requiere el uso del motor de instrumentación o del paquete NuGet Microsoft.Data.SqlClient en lugar de la biblioteca System.Data.SqlClient. En la siguiente tabla, se describen los pasos específicos de la plataforma para habilitar la recopilación completa de consultas SQL.

Plataforma Pasos necesarios para obtener la consulta SQL completa
Web Apps en Azure App Service En el panel de control de la aplicación web, abra el panel de Application Insights y habilite los comandos SQL de .NET.
Servidor IIS (Máquinas Virtuales de Azure, locales, etc.) Use el paquete de NuGet Microsoft.Data.SqlClient o use el módulo de PowerShell del agente de Application Insights para instalar el motor de instrumentación y reiniciar IIS.
Azure Cloud Services Agregue una tarea de inicio para instalar StatusMonitor.
La aplicación debe incorporarse al SDK de Application Insights en tiempo de compilación mediante la instalación de paquetes NuGet para aplicaciones de ASP.NET o ASP.NET Core.
IIS Express Use el paquete NuGet Microsoft.Data.SqlClient.
WebJobs en Azure App Service Use el paquete NuGet Microsoft.Data.SqlClient.

Además de los pasos específicos de la plataforma anteriores, también debe optar explícitamente por habilitar la colección de comandos SQL al modificar el archivo ApplicationInsights.config con el código siguiente:

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

En los casos anteriores, la forma correcta de validar que el motor de instrumentación está instalado correctamente es comprobar que la versión de SDK de la DependencyTelemetry recopilada sea rddp. El uso de rdddsd o rddf indica que las dependencias se recopilan mediante devoluciones de llamada DiagnosticSource o EventSource, por lo que no se captura la consulta SQL completa.

Excepciones

Las excepciones en las aplicaciones web se pueden notificar con Application Insights. Puede correlacionar las solicitudes con error con excepciones y otros eventos en el cliente y en el servidor, de modo que pueda diagnosticar rápidamente las causas. En esta sección, aprenderá a configurar informes de excepciones, notificar excepciones explícitamente, diagnosticar errores y mucho más.

Configuración de informes de excepciones

Puede configurar Application Insights para notificar las excepciones que se producen en el servidor o en el cliente. En función de la plataforma en la que dependa la aplicación, necesitará la extensión o el SDK adecuados.

Para que se notifiquen las excepciones desde la aplicación de servidor, tenga en cuenta los siguientes escenarios:

Importante

Esta sección se centra en las aplicaciones de .NET Framework desde una perspectiva de ejemplo de código. Algunos de los métodos que funcionan en .NET Framework son obsoletos en el SDK de .NET Core.

Diagnóstico de errores y excepciones

Application Insights incluye una experiencia de administración del rendimiento de las aplicaciones seleccionada para ayudar a diagnosticar errores en las aplicaciones supervisadas.

Para obtener instrucciones detalladas, consulte Investigación de errores, rendimiento y transacciones con Application Insights.

Personalización del seguimiento y del registro de datos

Para obtener datos de diagnóstico específicos de su aplicación, puede insertar código para enviar sus propios datos de telemetría. Sus datos de telemetría o registro personalizados aparecen en la búsqueda de diagnóstico junto con la solicitud, la vista de página y otros datos que se recopilan automáticamente.

Con Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, tiene varias API disponibles:

Para ver estos eventos, en el menú izquierdo, abra Buscar. Seleccione el menú desplegable Tipos de eventos y, a continuación, elija Evento personalizado, Seguimiento o Excepción.

Recorte de pantalla que muestra la pantalla de búsqueda.

Nota:

Si la aplicación genera grandes cantidades de telemetría, el módulo de muestreo adaptable reduce automáticamente el volumen enviado al portal enviando solo una fracción representativa de eventos. Los eventos que forman parte de la misma operación se seleccionan o se deseleccionan como un grupo para que pueda navegar entre eventos relacionados. Para más información, consulte Muestreo en Application Insights.

Consulta de datos POST de solicitud

Los detalles de la solicitud no incluyen los datos enviados a la aplicación en una llamada a POST. Para que se notifiquen estos datos:

  • Agregue el SDK de Application Insights al código de la aplicación.
  • Inserte código en la aplicación para llamar a Microsoft.ApplicationInsights.TrackTrace(). Envíe los datos de POST en el parámetro de mensaje. Hay un límite en cuanto al tamaño permitido, así que debe intentar enviar únicamente los datos fundamentales.
  • Cuando investigue una solicitud con error, busque los seguimientos asociados.

De manera predeterminada, no todas las excepciones que provocan errores en la aplicación aparecen en el portal. Si usa el SDK de JavaScript en las páginas web, verá excepciones del explorador. Sin embargo, la mayoría de las excepciones del lado servidor son interceptadas por IIS, por lo que debe agregar código para capturarlos e informarlos.

Ustedes pueden:

  • Registrar excepciones explícitamente insertando código en los controladores de excepciones para notificar las excepciones.
  • Capturar excepciones automáticamente configurando su marco de ASP.NET. Las adiciones necesarias son diferentes para los distintos tipos de marco.
Notificar excepciones explícitamente

La manera más sencilla de informar consiste en insertar una llamada a trackException() en un controlador de excepciones.

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

Los parámetros de las propiedades y las medidas son opcionales, pero son útiles para filtrar y agregar información adicional. Por ejemplo, si tiene una aplicación que se puede ejecutar varios juegos, podría buscar todos los informes de excepción relacionados con un juego en particular. Puede agregar tantos elementos como desee para cada diccionario.

Excepciones de explorador

Se notifican la mayoría de las excepciones de explorador.

Si la página web incluye archivos de script de redes de entrega de contenido o de otros dominios, asegúrese de que la etiqueta de script tenga el atributo crossorigin="anonymous", y que el servidor envíe encabezados CORS. Este comportamiento le permite obtener un seguimiento de la pila y detalles para las excepciones de JavaScript no controladas de estos recursos.

Reutilización del cliente de telemetría

Nota:

Se recomienda crear una instancia de TelemetryClient una vez y reutilizarla a lo largo de la vida útil de una aplicación.

Con la inserción de dependencias (DI) en .NET, el SDK de .NET adecuado y la configuración correcta de Application Insights para la inserción de dependencias, puede requerir TelemetryClient como un parámetro de constructor.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

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

En el ejemplo anterior, el parámetro TelemetryClient se inserta en la clase ExampleController.

Formularios web

En el caso de los formularios web, el módulo HTTP puede recopilar las excepciones cuando no hay redireccionamientos configurados con CustomErrors. No obstante, si tiene redireccionamientos activos, agregue las siguientes líneas a la función Application_Error en Global.asax.cs.

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

En el ejemplo anterior, _telemetryClient es una variable de ámbito de clase de tipo TelemetryClient.

MVC

A partir del SDK web de Application Insights versión 2.6 (beta 3 y posterior), Application Insights recopila excepciones no controladas producidas automáticamente en los métodos de controladores MVC 5+. Si anteriormente agregó un controlador personalizado para realizar un seguimiento de estas excepciones, puede quitarlo para evitar el seguimiento doble de excepciones.

Hay una serie de escenarios en los que un filtro de excepciones no puede controlar correctamente los errores cuando se producen excepciones:

  • Desde constructores de controlador
  • Desde controladores de mensajes
  • Durante el enrutamiento
  • Durante la serialización del contenido de respuesta
  • Durante el inicio de la aplicación
  • En tareas en segundo plano

Es necesario seguir realizando el seguimiento de todas las excepciones controladas por la aplicación manualmente. Las excepciones no controladas que se originan en los controladores dan lugar normalmente a respuestas 500 "Error interno del servidor". Si dicha respuesta se creó manualmente como resultado de una excepción controlada o sin ninguna excepción en absoluto, se realiza su seguimiento en la telemetría de la solicitud correspondiente con ResultCode 500. Sin embargo, el SDK de Application Insights no puede realizar un seguimiento de una excepción correspondiente.

Compatibilidad con versiones anteriores

Si usa MVC 4 (y anterior) del SDK web de Application Insights 2.5 (y anterior), consulte los siguientes ejemplos para realizar el seguimiento de las excepciones.


Expandir para ver las instrucciones de versiones anteriores

Si la configuración CustomErrors es Off, las excepciones están disponibles para que el módulo HTTP se recopile. Sin embargo, si se establece en RemoteOnly (valor predeterminado) o On, la excepción se borra y no está disponible para que Application Insights se recopile automáticamente. Para corregir este comportamiento, invalide la clase System.Web.Mvc.HandleErrorAttribute y aplique la clase invalidada como se muestra a continuación para las diferentes versiones de MVC (consulte origen de GitHub):

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

Sustituya el atributo HandleError por el nuevo atributo en los controladores:

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

Ejemplo

MVC 3

Registrar AiHandleErrorAttribute como filtro global de Global.asax.cs:

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

Ejemplo

MVC 4, MVC 5

Registrar AiHandleErrorAttribute como filtro global de FilterConfig.cs:

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

Ejemplo

API de la Web

A partir del SDK web de Application Insights versión 2.6 (beta 3 y posterior), Application Insights recopila excepciones no controladas producidas automáticamente en los métodos de controladores para Web API 2+. Si anteriormente agregó un controlador personalizado para realizar un seguimiento de estas excepciones, como se describe en los ejemplos siguientes, puede quitarlo para evitar el seguimiento doble de excepciones.

Hay varios casos que los filtros de excepciones no pueden procesar. Por ejemplo:

  • Excepciones iniciadas por constructores del controlador.
  • Excepciones iniciadas por controladores de mensajes.
  • Excepciones iniciadas durante el enrutamiento.
  • Excepciones iniciadas durante la serialización del contenido de respuesta.
  • Excepción que se produce durante el inicio de la aplicación.
  • Excepción que se produce en tareas en segundo plano.

Es necesario seguir realizando el seguimiento de todas las excepciones controladas por la aplicación manualmente. Las excepciones no controladas que se originan en los controladores dan lugar normalmente a respuestas 500 "Error interno del servidor". Si dicha respuesta se creó manualmente como resultado de una excepción controlada o sin ninguna excepción en absoluto, se realiza su seguimiento en la telemetría de la solicitud correspondiente con ResultCode 500. Sin embargo, el SDK de Application Insights no puede realizar un seguimiento de una excepción correspondiente.

Compatibilidad con versiones anteriores

Si usa Web API 1 (y anterior) del SDK web de Application Insights 2.5 (y anterior), consulte los siguientes ejemplos para realizar el seguimiento de las excepciones.


Expandir para ver las instrucciones de versiones anteriores

API web 1.x

Invalidar System.Web.Http.Filters.ExceptionFilterAttribute:

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

Podría agregar este atributo invalidado a controladores específicos o agregarlo a la configuración de filtros globales en la clase WebApiConfig:

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

Ejemplo

API web 2.x

Agregar una implementación de IExceptionLogger:

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

Agregue este fragmento de código a los servicios en WebApiConfig:

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

Ejemplo

Como alternativa, puede:

  • Sustituir el único ExceptionHandler por una implementación personalizada de IExceptionHandler. Solo se llama a este controlador de excepciones cuando el marco es aún capaz de seleccionar el mensaje de respuesta que se enviará, no cuando se anula la conexión, por ejemplo.
  • Use filtros de excepción, como se describe en la sección anterior de controladores de Web API 1.x, que no se llaman en todos los casos.

WCF

Agregue una clase que extienda Attribute e implemente IErrorHandler y IServiceBehavior.

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

Agregue el atributo a las implementaciones de servicio:

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

Ejemplo

Contadores de rendimiento de excepciones

Si instaló el agente de Application Insights de Azure Monitor en el servidor, puede obtener un gráfico de la tasa de excepciones medida por .NET. Se incluyen las excepciones de .NET controladas y no controladas.

Abra una pestaña del Explorador de métricas y agregue un nuevo gráfico. En Contadores de rendimiento, seleccione Tasa de excepciones.

.NET framework calcula la tasa contando el número de excepciones producidas en un intervalo y dividiéndolo por la duración del intervalo de tiempo.

Este recuento es diferente del recuento de Excepciones calculado por el portal de Application Insights contando los informes de TrackException. Los intervalos de muestreo son diferentes y el SDK no envía informes de TrackException para todas las excepciones, controladas y no controladas.

Colección de métricas personalizadas

Los SDK de .NET y .NET Core de Application Insights de Azure Monitor tienen dos métodos diferentes para recopilar métricas personalizadas:

  • El método TrackMetric(), que carece de agregación previa.
  • El método GetMetric(), que tiene una agregación previa.

Se recomienda usar la agregación, por lo que TrackMetric()ya no es el método preferido para recopilar métricas personalizadas. En este artículo se le guiará por el uso del método GetMetric() y parte de la lógica en la que se basa su funcionamiento.


Expandir para obtener más información sobre la agregación previa frente a la API que no es de agregación previa

El método TrackMetric() envía datos de telemetría sin procesar que denotan una métrica. No es eficaz enviar un elemento de telemetría único para cada valor. El método TrackMetric() también es ineficaz en términos de rendimiento porque cada TrackMetric(item) pasa a través de la canalización del SDK de inicializadores y procesadores de telemetría.

A diferencia de TrackMetric(), GetMetric() controla la agregación local por usted y, a continuación, solo envía una métrica de resumen agregada a un intervalo fijo de un minuto. Si necesita supervisar de cerca algunas métricas personalizadas en el nivel de segundos o incluso en el de milisegundos, puede hacerlo y además solo se incurre en el costo de almacenamiento y tráfico de red de la supervisión en cada minuto. Este comportamiento también reduce en gran medida el riesgo de que se produzca una limitación, ya que se reduce considerablemente el número total de elementos de telemetría que se deben enviar para una métrica agregada.

En Application Insights, las métricas personalizadas recopiladas mediante TrackMetric() y GetMetric() no están sujetas a muestreo. El muestreo de métricas importantes puede dar lugar a escenarios en los que las alertas creadas en torno a esas métricas no son confiables. Si nunca se realiza el muestreo de las métricas personalizadas, normalmente puede estar seguro de que se activará una alerta cuando se infrinjan los umbrales de alerta. Dado que no se muestrean las métricas personalizadas, existen algunas posibles preocupaciones.

El seguimiento de las tendencias de una métrica cada segundo o en un intervalo aún más granular puede dar lugar a:

  • Aumento de los costos de almacenamiento de datos. Hay un costo asociado con la cantidad de datos que se envían a Azure Monitor. Cuantos más datos envíe, mayor será el costo total de la supervisión.
  • Aumento del tráfico de red o sobrecarga del rendimiento. En algunos escenarios esta sobrecarga podría tener un costo monetario y de rendimiento de la aplicación.
  • Riesgo de limitación de la ingesta de datos. Azure Monitor descarta ["limita"] puntos de datos cuando la aplicación envía un número elevado de datos de telemetría en un intervalo de tiempo corto.

La limitación es un problema, ya que puede provocar la pérdida de alertas. La condición para desencadenar una alerta puede producirse localmente y, con posterioridad, anularse en el punto de conexión de ingesta debido a que se envían demasiados datos. No se recomienda usar TrackMetric() para .NET y .NET Core a menos que implemente su propia lógica de agregación local. Si intenta realizar un seguimiento de cada instancia en la que se produce un evento durante un período de tiempo determinado, es posible que sea mejor opción TrackEvent(). Tenga en cuenta que, a diferencia de las métricas personalizadas, los eventos personalizados están sujetos a muestreo. Todavía puede usar TrackMetric() incluso sin escribir su propia agregación local. Pero si lo hace, tenga en cuenta los problemas.

En resumen, se recomienda GetMetric() porque realiza la agregación previa, acumula valores de todas las llamadas Track() y envía un resumen o agregado una vez cada minuto. El método GetMetric() puede reducir significativamente los costos y la sobrecarga de rendimiento, ya que envía menos puntos de datos, pero recopila toda la información pertinente.

Introducción a GetMetric

En los ejemplos, vamos a usar una aplicación básica de servicio de trabajo de .NET Core 3.1. Si desea replicar el entorno de prueba que se usa con estos ejemplos, siga los pasos 1 a 6 en la aplicación del servicio de trabajo de .NET Core. En estos pasos se agrega Application Insights a una plantilla de proyecto de servicio de trabajo básica. Estos conceptos se aplican a cualquier aplicación general en la que se pueda usar el SDK, incluidas las aplicaciones web y las aplicaciones de consola.

Envío de métricas

Reemplace el contenido del archivo worker.cs por el siguiente código:

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

Al ejecutar el código de ejemplo, verá que el bucle while se ejecuta repetidamente sin que se envíen datos de telemetría en la ventana de salida de Visual Studio. Se envía un único elemento de telemetría alrededor de la marca de 60 segundos, que en nuestra prueba tiene el siguiente aspecto:

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

Este único elemento de telemetría representa un agregado de 41 medidas de métricas distintas. Dado que se envía el mismo valor una y otra vez, tenemos una desviación estándar (stDev) de 0 con valores idénticos de máximo (max) y mínimo (min). La propiedad value representa una suma de todos los valores individuales agregados.

Nota:

El método GetMetric no admite el seguimiento del último valor (por ejemplo, gauge) o el seguimiento de histogramas o distribuciones.

Si examinamos el recurso de Application Insights en la experiencia de Registros (Analytics), el elemento de telemetría individual tendrá un aspecto al de la siguiente captura de pantalla.

Recorte de pantalla en el que se muestra la vista de consultas de Log Analytics.

Nota:

Aunque el elemento de telemetría sin procesar no contenía una propiedad ni campo de suma explícitos, creamos uno automáticamente para usted. En este caso, las propiedades value y valueSum representan lo mismo.

También puede acceder a la telemetría de métricas personalizada en la sección Métricas del portal como métricas basadas en registros y personalizadas. La captura de pantalla siguiente es un ejemplo de una métrica basada en registros.

Recorte de pantalla que muestra la vista del Explorador de métricas.

Almacenamiento en caché de referencias de métricas para uso de alto rendimiento

Los valores de métricas se podrían observar con frecuencia en algunos casos. Por ejemplo, un servicio de alto rendimiento que procesa 500 solicitudes por segundo podría querer emitir 20 métricas de datos de telemetría por cada solicitud. El resultado significa un seguimiento de 10 000 valores por segundo. En dichos escenarios de alto rendimiento, es posible que los usuarios necesiten ayudar al SDK evitando algunas búsquedas.

Por ejemplo, en el ejemplo anterior se realizó una búsqueda de un manipulador de la métrica ComputersSold y, a continuación, se supervisó un valor observado de 42. En su lugar, el manipulador se podría almacenar en caché para las invocaciones de varios seguimientos:

//...

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

Además de almacenar en caché el manipulador de la métrica, en el ejemplo anterior también se redujo Task.Delay a 50 milisegundos para que el bucle se ejecute con más frecuencia. El resultado es 772 TrackValue() invocaciones.

Métricas multidimensionales

Los ejemplos de la sección anterior muestran métricas de dimensión cero. Las métricas también pueden ser multidimensionales. Actualmente se admiten hasta 10 dimensiones.

Este es un ejemplo de cómo crear una métrica de una dimensión:

//...

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

La ejecución del código de ejemplo durante al menos 60 segundos da como resultado el envío de tres elementos de telemetría distintos a Azure. Cada elemento representa la agregación de uno de los tres factores de forma. Como antes, puede examinarlos en mayor profundidad en la vista de Registros (Analytics).

Recorte de pantalla que muestra la vista de Log Analytics de la métrica multidimensional.

En el explorador de métricas:

Recorte de pantalla que muestra las métricas personalizadas.

Tenga en cuenta que no puede dividir la métrica por su nueva dimensión personalizada ni ver su dimensión personalizada con la vista de métricas.

Recorte de pantalla que muestra la compatibilidad con la separación.

De manera predeterminada, las métricas multidimensionales dentro del explorador de métricas no están activadas en recursos de Application Insights.

Habilitar métricas multidimensionales

Para habilitar las métricas multidimensionales para un recurso de Application Insights, seleccione Uso y costos estimados>Métricas personalizadas>Habilitar la creación de alertas sobre las dimensiones de las métricas personalizadas>Aceptar. Para obtener más información, consulte dimensiones de métricas personalizadas y de agregación previa.

Después de realizar ese cambio y enviar la nueva telemetría multidimensional, puede seleccionar Aplicar división.

Nota:

Solo las métricas recién enviadas después de activar la característica en el portal tienen las dimensiones almacenadas.

Recorte de pantalla que muestra la aplicación de la separación.

Vea las agregaciones de métricas para cada dimensión FormFactor.

Recorte de pantalla que muestra los factores de forma.

Uso de MetricIdentifier cuando hay más de tres dimensiones

Actualmente, se admiten 10 dimensiones. El uso de más de tres dimensiones requiere el uso de MetricIdentifier:

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

Configuración de métricas personalizadas

Si quiere modificar la configuración de la métrica, debe realizar las modificaciones donde se inicializa la métrica.

Nombres de dimensión especiales

Las métricas no usan el contexto de telemetría del TelemetryClient usado para acceder a ellas. La mejor solución a esta limitación es utilizar nombres de dimensiones especiales disponibles como constantes en la clase MetricDimensionNames.

Los agregados de métrica enviados por la siguiente métrica Special Operation Request Sizeno tienen Context.Operation.Name establecido en Special Operation. El método TrackMetric() o cualquier otro método TrackXXX() tiene OperationName establecido correctamente en Special Operation.

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

En este caso, use los nombres de dimensión especiales que aparecen en la clase MetricDimensionNames para especificar los valores de TelemetryContext.

Por ejemplo, cuando el agregado de métricas resultante de la siguiente instrucción se envía al punto de conexión en la nube de Application Insights, su campo de datos Context.Operation.Name se establece en Special Operation:

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

El valor de esta dimensión especial se copia en TelemetryContext y no se usa como una dimensión normal. Si también desea mantener una dimensión de operación para la exploración normal de métricas, debe crear una dimensión independiente para ese propósito:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");
Límites de las dimensiones y las series temporales

Para evitar que el subsistema de telemetría agote accidentalmente los recursos, puede controlar el número máximo de series de datos por métrica. Los límites predeterminados son no más de 1,000 series de datos totales por métrica y no más de 100 valores diferentes por dimensión.

Importante

Use valores cardinales bajos para las dimensiones a fin de evitar la limitación.

En el contexto de los límites de dimensiones y series temporales, utilice Metric.TrackValue(..) para asegurarse de que se observan los límites. Si ya se han alcanzado los límites, Metric.TrackValue(..) devuelve False y no se realiza un seguimiento del valor. En caso contrario, devuelve True. Este comportamiento resulta útil si los datos de una métrica se originan a partir de la entrada de usuario.

El constructor MetricConfiguration toma algunas opciones para administrar series diferentes dentro de la métrica respectiva y un objeto de una clase que implementa IMetricSeriesConfiguration, que especifica el comportamiento de agregación para cada serie individual de la métrica:

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 does not track the metric, and returns false.
  • seriesCountLimit es el número máximo de series temporales de datos que puede contener una métrica. Una vez alcanzado este límite, las llamadas a TrackValue() que normalmente generarían una nueva serie devolverán false.
  • valuesPerDimensionLimit limita el número de valores distintos por dimensión de forma similar.
  • restrictToUInt32Values determina si solo se debe realizar el seguimiento de los valores enteros no negativos.

Este es un ejemplo de cómo enviar un mensaje para saber si se han superado los límites:

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

Seguimiento de operaciones personalizadas

Los SDK de Application Insights realizan un seguimiento automático de las solicitudes HTTP entrantes y las llamadas a servicios dependientes, como las solicitudes HTTP y las consultas SQL. El seguimiento y la correlación de solicitudes y dependencias proporcionan visibilidad sobre la capacidad de respuesta y confiabilidad de toda la aplicación en todos los microservicios que combinan esta aplicación.

Hay una clase de patrones de aplicación que no se pueden admitir genéricamente. La supervisión correcta de estos patrones requiere la instrumentación manual de código. En esta sección se tratan algunos patrones que pueden requerir instrumentación manual, como el procesamiento de colas personalizado y la ejecución de tareas en segundo plano de larga duración.

En esta sección se proporcionan instrucciones sobre cómo realizar un seguimiento de las operaciones personalizadas con el SDK de Application Insights.

Información general

Una operación es una parte de trabajo lógica ejecutada por una aplicación. Tiene un nombre, una hora de inicio, una duración, un resultado y un contexto de ejecución como el nombre de usuario, las propiedades y el resultado. Si la operación B inició la operación A, la operación B se establece como un elemento primario de A. Una operación solo puede tener un elemento primario, pero puede tener muchas operaciones secundarias. Para más información sobre las operaciones y la correlación de telemetría, consulte Correlación de telemetría de Azure Application Insights.

En el SDK de .NET para Application Insights se describe la operación mediante la clase abstracta OperationTelemetry y sus descendientes RequestTelemetry y DependencyTelemetry.

Seguimiento de operaciones de entrada

El SDK web de Application Insights recopila automáticamente solicitudes HTTP para ASP.NET aplicaciones que se ejecutan en una canalización de IIS y todas las aplicaciones ASP.NET Core. Hay soluciones compatibles con la comunidad para otras plataformas y marcos. Si la aplicación no es compatible con ninguna de las soluciones estándar o compatibles con la comunidad, puede instrumentarla manualmente.

Otro ejemplo que requiere seguimiento personalizado es el trabajo que recibe elementos de la cola. En algunas colas, se realiza un seguimiento de la llamada para agregar un mensaje a esta cola como dependencia. La operación de alto nivel que describe el procesamiento de mensajes no se recopila automáticamente.

Veamos cómo se puede realizar un seguimiento de estas operaciones.

En un nivel alto, la tarea consiste en crear RequestTelemetry y establecer propiedades conocidas. Una vez finalizada la operación, realice un seguimiento de la telemetría. En el ejemplo siguiente se muestra esta tarea.

Solicitud HTTP en una aplicación autohospedada de Owin

En este ejemplo, el contexto de seguimiento se propaga según el protocolo HTTP para la correlación. Debe esperar recibir los encabezados que se describen ahí.


Expandir para ver el código 
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);
    }
}

El Protocolo HTTP para la correlación también declara el encabezado Correlation-Context. Aquí se omite por motivos de simplicidad.

Instrumentación de colas

El contexto de seguimiento de W3C y el protocolo HTTP para la correlación pasan los detalles de la correlación con las solicitudes HTTP, pero cada protocolo de cola tiene que definir cómo se pasan los mismos detalles junto con el mensaje de cola. Algunos protocolos de cola, como AMQP, permiten pasar más metadatos. Otros protocolos, como Azure Storage Queue, requieren que el contexto se codifique en la carga del mensaje.

Nota:

El seguimiento entre componentes aún no se admite con las colas.

Con HTTP, si el productor y el consumidor envían telemetría a distintos recursos de Application Insights, la experiencia de diagnósticos de transacción y el mapa de aplicación muestran transacciones y asignaciones de un extremo a otro. En el caso de las colas, esta funcionalidad aún no se admite.

Cola de Service Bus

Para información sobre el seguimiento, consulte Seguimiento distribuido y correlación mediante la mensajería de Azure Service Bus.

Cola de Azure Storage

En el ejemplo siguiente se muestra cómo realizar el seguimiento de operaciones de cola de Azure Storage y poner en correlación la telemetría entre el productor, el consumidor y Azure Storage.

La cola de Storage tiene una API HTTP. El recopilador de dependencias de Application Insights realiza un seguimiento de todas las llamadas a la cola para las solicitudes HTTP. Está configurado de forma predeterminada en aplicaciones ASP.NET y ASP.NET Core. Con otros tipos de aplicaciones, consulte la documentación de aplicaciones de consola.

Es posible que también quiera poner en correlación el identificador de operación de Application Insights con el identificador de solicitud de Storage. Para obtener información sobre cómo establecer y obtener un cliente de solicitud de Storage y un identificador de solicitud de servidor, vea Supervisión, diagnóstico y solución de problemas de Azure Storage.

Como las colas de Storage admiten la API de HTTP, Application Insights realiza el seguimiento automático de todas las operaciones en la cola. En muchos casos, esta instrumentación debe ser suficiente. Para correlacionar seguimientos en el lado del consumidor con seguimientos de productor, debe pasar algún contexto de correlación de forma similar a cómo lo hacemos en el protocolo HTTP para Correlación.

En este ejemplo se muestra cómo realizar un seguimiento de la operación Enqueue. Ustedes pueden:

  • Poner en correlación los reintentos (si existen): Todos tienen un elemento primario común que es la operación Enqueue. En caso contrario, se realiza su seguimiento como elementos secundarios de la solicitud de entrada. Si hay varias solicitudes lógicas a la cola, podría ser difícil buscar qué llamada generó los reintentos.
  • Poner en correlación los registros de Azure Storage (si es necesario y cuando sea necesario): Se hace con la telemetría de Application Insights.

La operación Enqueue es el elemento secundario de una operación primaria. Un ejemplo es una solicitud HTTP entrante. La llamada de dependencia HTTP es el elemento secundario de la operación Enqueue y el descendiente de la solicitud de entrada.

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

Para reducir la cantidad de telemetría que notifica la aplicación o si no desea realizar un seguimiento de laEnqueue operación por otros motivos, use la API de Activity directamente:

  • Cree (e inicie) una nueva Activity en lugar de iniciar la operación de Application Insights. No es necesario asignar ninguna propiedad en ella, excepto el nombre de la operación.
  • Serialice yourActivity.Id en la carga del mensaje en lugar de operation.Telemetry.Id. También se puede usar Activity.Current.Id.

Del mismo modo, se pueden instrumentar otras operaciones de cola. Una operación de lectura se debe instrumentalizar de una manera similar a la de una operación de quitar de la cola. La instrumentación de las operaciones de administración de cola no es necesaria. Application Insights realiza un seguimiento de las operaciones como HTTP y, en la mayoría de los casos, es suficiente.

Al instrumentar la eliminación de mensajes, asegúrese de establecer los identificadores de operación (correlación). Como alternativa, puede usar la API de Activity. A continuación, no es necesario establecer identificadores de operación en los elementos de telemetría porque el SDK de Application Insights lo hace por usted:

  • Cree una nueva Activity después de que tenga un elemento de la cola.
  • Use Activity.SetParentId(message.ParentId) para poner en correlación los registros de consumidor y productor.
  • Inicie el Activity.
  • Realice un seguimiento de las operaciones de puesta en cola, proceso y eliminación mediante Start/StopOperation asistentes. Hágalo desde el mismo flujo de control asincrónico (contexto de ejecución). De esta forma, se correlacionan correctamente.
  • Detenga el Activity.
  • Use Start/StopOperation o llame manualmente a Track telemetría.
Tipos de dependencia

Application Insights usa el tipo de dependencia para personalizar las experiencias de la interfaz de usuario. En el caso de las colas, se reconocen los siguientes tipos de DependencyTelemetry que mejoran la experiencia de diagnósticos de transacción:

  • Azure queue para colas de Azure Storage
  • Azure Event Hubs para Azure Event Hubs
  • Azure Service Bus para Azure Service Bus
Procesamiento por lotes

En algunas colas, se pueden quitar de la cola varios mensajes con una solicitud. El procesamiento de estos mensajes es presumiblemente independiente y pertenece a las diferentes operaciones lógicas. No es posible correlacionar la operación de Dequeue con un mensaje determinado que se está procesando.

Cada mensaje debe procesarse en su propio flujo de control asincrónico. Para más información, vea la sección Seguimiento de dependencias de salida.

Tareas en segundo plano de ejecución prolongada

Algunas aplicaciones inician operaciones de larga duración que podrían deberse a solicitudes de usuario. Desde la perspectiva de seguimiento e instrumentación, no es diferente de la instrumentación de solicitudes o dependencias:

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

En este ejemplo, telemetryClient.StartOperation crea DependencyTelemetry y rellena el contexto de correlación. Supongamos que tiene una operación principal creada por las solicitudes de entrada que programaron la operación. Siempre que BackgroundTask se inicie en el mismo flujo de control asincrónico que una solicitud de entrada, se correlaciona con esa operación principal. BackgroundTask y todos los elementos de telemetría anidados se correlacionan automáticamente con la solicitud que la causó incluso después de que finalice la solicitud.

Cuando la tarea se inicia desde el subproceso en segundo plano que no tiene ninguna operación (Activity) asociada, BackgroundTask no tiene ningún elemento primario. Sin embargo, puede tener operaciones anidadas. Todos los elementos de telemetría notificados desde la tarea se correlacionan con el DependencyTelemetry creado en BackgroundTask.

Seguimiento de dependencias realizadas

Puede realizar un seguimiento de su propio tipo de dependencia o una operación que no sea compatible con Application Insights.

El método Enqueue de la cola de Service Bus o la cola de Storage puede servir como ejemplo de este seguimiento personalizado.

El enfoque general para el seguimiento de dependencias personalizado es:

  • Llame al método TelemetryClient.StartOperation (extensión) que rellena las propiedades DependencyTelemetry necesarias para la correlación y otras propiedades, como inicio, marca de tiempo y duración.
  • Establezca otras propiedades personalizadas en el DependencyTelemetry, como el nombre y cualquier otro contexto que necesite.
  • Realice una llamada de dependencia y espere.
  • Detenga la operación con StopOperation cuando haya terminado.
  • Controle las excepciones.
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.
        }
    }
}

Desechar una operación hace que la operación se detenga, por lo que puede hacerlo en lugar de llamar a StopOperation.

Advertencia

En algunos casos, una excepción no controlada podría impedir que se llame a finally, por lo que es posible que no se realice un seguimiento de las operaciones.

Seguimiento y procesamiento de operaciones paralelas

Al llamar a StopOperation solo se detiene la operación que se inició. Si la operación en ejecución actual no coincide con la que desea detener, StopOperation no hace nada. Esta situación puede ocurrir si inicia varias operaciones en paralelo en el mismo contexto de ejecución.

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;

Asegúrese de llamar siempre a StartOperation y de procesar la operación en el mismo método async para aislar las operaciones que se ejecutan en paralelo. Si la operación es sincrónica o no asincrónica, encapsule el proceso y realice un seguimiento con Task.Run.

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

Operaciones de ApplicationInsights frente a System.Diagnostics.Activity

System.Diagnostics.Activity representa el contexto de seguimiento distribuido y lo utilizan las plataformas y las bibliotecas para crear y propagar el contexto dentro y fuera del proceso, así como correlacionar los elementos de telemetría. Activity funciona junto con System.Diagnostics.DiagnosticSource como mecanismo de notificación entre la plataforma o la biblioteca para notificar eventos interesantes, como solicitudes entrantes o salientes, excepciones, etc.

Las actividades son características de nivel superior en Application Insights. La recopilación automática de dependencias y solicitudes depende en gran medida de ellas junto con los eventos DiagnosticSource. Si creara Activity en su aplicación, no se crearía la telemetría de Application Insights. Application Insights debe recibir eventos DiagnosticSource y conocer los nombres y las cargas de los eventos para convertir Activity en telemetría.

Cada operación de Application Insights (solicitud o dependencia) conlleva un elemento Activity. Cuando se llama a StartOperation, crea Activity debajo. StartOperation es el método recomendado para realizar el seguimiento de las telemetrías de solicitudes o de dependencias manualmente y asegurarse de que todo está correlacionado.

Contadores en Application Insights

Application Insights admite contadores de rendimiento y contadores de eventos. En esta guía se proporciona información general sobre ambos, incluidos su propósito, configuración y uso en aplicaciones .NET.

Información general

  • Los Contadores de rendimiento están integrados en el sistema operativo Windows y ofrecen métricas predefinidas, como el uso de CPU, el consumo de memoria y la actividad de disco. Estos contadores son ideales para supervisar las métricas de rendimiento estándar con una configuración mínima. Ayudan a realizar un seguimiento del uso de recursos o a solucionar problemas de cuellos de botella de nivel del sistema en aplicaciones basadas en Windows, pero no admiten métricas personalizadas específicas de la aplicación.

  • Los Contadores de eventos funcionan en varias plataformas, como Windows, Linux y macOS. Permiten a los desarrolladores definir y supervisar métricas ligeras y personalizables específicas de la aplicación, lo que proporciona más flexibilidad que los contadores de rendimiento. Los contadores de eventos son útiles cuando las métricas del sistema son insuficientes o cuando se necesita telemetría detallada en aplicaciones multiplataforma. Requieren implementación y configuración explícitas, lo que hace que la configuración sea más intensiva.

Contadores de rendimiento

Windows proporciona varios contadores de rendimiento, como los que se usan para obtener las estadísticas de uso del disco, la memoria y el procesador. También puede definir sus propios contadores de rendimiento.

La aplicación admite la recopilación de contadores de rendimiento si se ejecuta en Internet Information Server (IIS) en un host local o en una máquina virtual con acceso administrativo. Las aplicaciones que se ejecutan como Azure Web Apps no pueden acceder directamente a los contadores de rendimiento, pero Application Insights recopila un subconjunto de contadores disponibles.

Sugerencia

Al igual que otras métricas, puede establecer una alerta para advertirle si un contador supera un límite especificado. Para establecer una alerta, abra el panel Alertas y seleccione Agregar alerta.

Prerrequisitos

Conceda permiso a la cuenta de servicio del grupo de aplicaciones para supervisar los contadores de rendimiento agregándola al grupo Usuarios del monitor de sistema.

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

Visualización de contadores

El panel Métricas muestra el conjunto predeterminado de contadores de rendimiento.

Contadores predeterminados para aplicaciones web de ASP.NET:

  • % Proceso\Tiempo del procesador
  • % Proceso\Tiempo de procesador normalizado
  • Memoria\Bytes disponibles
  • Solicitudes de ASP.NET/segundo
  • Excepciones de .NET Common Language Runtime (CLR) producidas por segundo
  • Tiempo de Ejecución de Solicitudes en Aplicaciones ASP.NET
  • Bytes privados del proceso
  • Proceso\Bytes/sec de datos de E/S
  • ASP.NET Aplicaciones\Solicitudes en cola de aplicaciones
  • Procesador(_Total)\% de tiempo del procesador

Adición de contadores

Si el contador de rendimiento que quiere no está incluido en la lista de métricas, puede agregarlo.

Opción 1: Configuración en ApplicationInsights.config

  1. Averigüe qué contadores están disponibles en el servidor mediante este comando de PowerShell en el servidor local:

    Get-Counter -ListSet *

    Para obtener más información, consulte Get-Counter.

  2. Abierto ApplicationInsights.config.

    He agregado Application Insights a mi aplicación durante el desarrollo:

    1. Edite ApplicationInsights.config en el proyecto.
    2. Vuelva a implementarlo en los servidores.

  3. Edite la directiva del recopilador de rendimiento:

    
    <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>

Capture tanto contadores estándar como contadores que implemente usted mismo. \Objects\Processes es un ejemplo de contador estándar que está disponible en todos los sistemas Windows. \Sales(photo)\# Items Sold es un ejemplo de contador personalizado que podría implementarse en un servicio web.

El formato es \Category(instance)\Counter o, para las categorías que no tienen instancias, simplemente \Category\Counter.

El parámetro ReportAs es necesario para los nombres de contador que no coinciden con [a-zA-Z()/-_ \.]+.

Si especifica una instancia, se convierte en una dimensión CounterInstanceName de la métrica notificada.

Opción 2: Configuración en el código

Consulte la sección siguiente.

Recopilación de contadores de rendimiento en el código para aplicaciones web de ASP.NET o aplicaciones de consola de .NET/.NET Core

Para recopilar contadores de rendimiento del sistema y enviarlos a Application Insights, puede adaptar el siguiente fragmento:

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

También puede hacer lo mismo con las métricas personalizadas que haya creado:

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

Contadores de rendimiento para aplicaciones que se ejecutan en Azure Web Apps y contenedores de Windows en Azure App Service

Las aplicaciones de ASP.NET y ASP.NET Core implementadas en Azure Web Apps se ejecutan en un entorno de espacio aislado especial. Las aplicaciones implementadas en Azure App Service pueden usar un contenedor de Windows u hospedarse en un entorno de espacio aislado. Si la aplicación se implementa en un contenedor de Windows, todos los contadores de rendimiento estándar estarán disponibles en la imagen de contenedor.

Este entorno de espacio aislado no permite el acceso directo a los contadores de rendimiento del sistema. Sin embargo, un subconjunto limitado de contadores se expone como variables de entorno, como se describe en Contadores de rendimiento expuestos como variables de entorno. Solo un subconjunto de contadores está disponible en este entorno. Para obtener la lista completa, consulte Contadores de rendimiento expuestos como variables de entorno.

El SDK de Application Insights para ASP.NET y ASP.NET Core detecta si el código se implementa en una aplicación web y un contenedor que no sea de Windows. La detección determina si recopila contadores de rendimiento en un entorno de espacio aislado o si utiliza el mecanismo de recopilación estándar cuando se hospeda en un contenedor o una máquina virtual Windows.

Consultas de Log Analytics para contadores de rendimiento

Puede buscar y mostrar informes de contador de rendimiento en Log Analytics.

El esquema performanceCounters expone category, el nombre de counter y el nombre de instance de cada contador de rendimiento. En la telemetría de cada aplicación, solo verá los contadores de dicha aplicación. Por ejemplo, para ver qué contadores están disponibles:

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

Aquí, Instance hace referencia a la instancia de contador de rendimiento, no al rol ni a la instancia de máquina de servidor. El nombre de la instancia del contador de rendimiento normalmente segmenta contadores, como el tiempo de procesador, por el nombre del proceso o la aplicación.

Para obtener un gráfico de la memoria disponible en un período reciente:

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

Al igual que otros datos de telemetría, performanceCounters también tiene una columna cloud_RoleInstance que indica la identidad de la instancia del servidor host en el que se ejecuta la aplicación. Por ejemplo, para comparar el rendimiento de una aplicación en distintas máquinas:

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

Preguntas más frecuentes sobre los contadores de rendimiento

Para revisar las preguntas más frecuentes (P+F), consulte Preguntas más frecuentes sobre los contadores de rendimiento.

Contadores de eventos

EventCounter es el mecanismo de .NET/.NET Core para publicar y consumir contadores o estadísticas. Los contadores de eventos se admiten en todas las plataformas de sistema operativo (Windows, Linux y macOS). Se puede considerar como un equivalente multiplataforma para performanceCounters que solo se admite en los sistemas Windows.

Aunque los usuarios pueden publicar los contadores de eventos personalizados para satisfacer sus necesidades, .NET publica un conjunto de estos contadores de forma predeterminada. En este documento se describen los pasos necesarios para recopilar y ver contadores de eventos (definidos por el sistema o definidos por el usuario) en Azure Application Insights.

Sugerencia

Al igual que otras métricas, puede establecer una alerta para advertirle si un contador supera un límite especificado. Para establecer una alerta, abra el panel Alertas y seleccione Agregar alerta.

Uso de Application Insights para recopilar contadores de eventos

Application Insights admite la recopilación de EventCounters con su EventCounterCollectionModule, que forma parte del paquete NuGet Microsoft.ApplicationInsights.EventCounterCollector lanzado recientemente. EventCounterCollectionModule se habilita automáticamente al usar AspNetCore o WorkerService. EventCounterCollectionModule recopila contadores con una frecuencia de recopilación no configurable de 60 segundos. No se requieren permisos especiales para recopilar contadores de eventos. Para aplicaciones ASP.NET Core, también quiere agregar el paquete Microsoft.ApplicationInsights.AspNetCore.

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

Contadores predeterminados recopilados

A partir de la versión 2.15.0 del SDK de AspNetCore o SDK de WorkerService, no se recopila ningún contador de forma predeterminada. El propio módulo está habilitado, por lo que los usuarios pueden agregar los contadores deseados para recopilarlos.

Para obtener una lista de los contadores conocidos que se hayan publicado en el Runtime de .NET, consulte el documento de los Contadores disponibles.

Personalización de los contadores que se van a recopilar

El ejemplo siguiente muestra cómo agregar/quitar contadores. Esta personalización se llevaría a cabo como parte de la configuración de su servicio de aplicación después de que se haya habilitado la recopilación de telemetría de Application Insights mediante AddApplicationInsightsTelemetry() o AddApplicationInsightsWorkerService(). A continuación se muestra un ejemplo de código de una aplicación ASP.NET Core. Para otros tipos de aplicaciones, consulte Configuración de módulos de telemetría.

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

Deshabilitación del módulo de recopilación EventCounter

EventCounterCollectionModule se puede deshabilitar mediante ApplicationInsightsServiceOptions.

En el ejemplo siguiente se usa el SDK de ASP.NET Core.

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

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

También se puede usar un enfoque similar para el SDK de servicio para trabajadores, pero se debe cambiar el espacio de nombres tal y como se muestra en el ejemplo siguiente.

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

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

Consultas de Log Analytics para contadores de eventos

Puede buscar y mostrar informes de contadores de eventos en Log Analytics, en la tabla customMetrics.

Por ejemplo, ejecute la siguiente consulta para ver qué contadores se recopilan y están disponibles para consulta:

customMetrics | summarize avg(value) by name

Para un gráfico de un contador específico (por ejemplo, ThreadPool Completed Work Item Count) en el período más reciente, ejecute la consulta siguiente.

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

Al igual que otros datos de telemetría, customMetrics también tiene una columna cloud_RoleInstance que indica la identidad de la instancia del servidor host en el que se ejecuta la aplicación. La consulta anterior muestra el valor del contador por instancia y se puede usar para comparar el rendimiento de diferentes instancias del servidor.

Preguntas más frecuentes sobre los contadores de eventos

Para revisar las preguntas más frecuentes (P+F), consulte Preguntas más frecuentes sobre los contadores de eventos.

Filtrado y enriquecimiento de telemetría

En esta sección

Filtrado y preprocesamiento de telemetría

Puede escribir código para filtrar, modificar o enriquecer la telemetría antes de enviarla desde el SDK. El procesamiento incluye datos enviados desde los módulos de telemetría estándar, como la recopilación de solicitudes HTTP y la recopilación de dependencias.

  • El filtrado puede modificar o descartar la telemetría antes de enviarla desde el SDK mediante la implementación de ITelemetryProcessor. Por ejemplo, podría reducir el volumen de telemetría excluyendo las solicitudes de robots. A diferencia del muestreo, tiene control total sobre lo que se envía o descarta, pero afecta a las métricas basadas en registros agregados. Dependiendo de cómo descarte elementos, también podría perder la capacidad de navegar entre elementos relacionados.

  • Agregue o modifique propiedades a cualquier telemetría enviada desde su aplicación mediante la implementación de un ITelemetryInitializer. Por ejemplo, podría agregar valores calculados o números de versión por los que filtrar los datos en el portal.

  • El muestreo reduce el volumen de telemetría sin afectar a las estadísticas. Mantiene juntos los puntos de datos relacionados para que pueda navegar entre ellos al diagnosticar un problema. En el portal, los recuentos totales se multiplican para compensar el muestreo.

Nota:

La API del SDK se usa para enviar métricas y eventos personalizados.

Filtros

Esta técnica proporciona control directo sobre lo que se incluye o se excluye del flujo de telemetría. El filtrado se puede usar para quitar elementos de telemetría que se envíen a Application Insights. Puede usar el filtrado con muestreo o por separado.

Para filtrar la telemetría, escriba un procesador de telemetría y regístrelo con TelemetryConfiguration. Toda la telemetría pasa por el procesador. Puede elegir quitarlo de la secuencia o asignarlo al siguiente procesador de la cadena. La telemetría de los módulos estándar, como el recopilador de solicitudes HTTP y el recopilador de dependencias, se incluye junto con la telemetría que usted mismo ha rastreado. Por ejemplo, puede filtrar para dejar fuera la telemetría acerca de las solicitudes de robots o las llamadas de dependencia correctas.

Advertencia

El filtrado de la telemetría enviada desde el SDK mediante procesadores puede sesgar las estadísticas que ve en el portal y dificultar el seguimiento de los elementos relacionados.

En su lugar, considere la posibilidad de usar el muestreo.

ITelemetryProcessor e ITelemetryInitializer

¿Cuál es la diferencia entre los procesadores de telemetría y los inicializadores de telemetría?

  • Hay algunas superposiciones en lo que puede hacer con ellos. Ambos se pueden usar para agregar o modificar propiedades de telemetría, aunque se recomienda usar inicializadores para ese propósito.
  • Los inicializadores de telemetría siempre se ejecutan antes de los procesadores de telemetría.
  • Se puede llamar a inicializadores de telemetría más de una vez. Por convención, no establecen ninguna propiedad que ya esté configurada.
  • Los procesadores de telemetría permiten reemplazar o descartar completamente un elemento de telemetría.
  • Se llama a todos los inicializadores de telemetría registrados para cada elemento de telemetría. Para los procesadores de telemetría, el SDK garantiza llamar al primer procesador de telemetría. Si se llama o no al resto de los procesadores se decide mediante los procesadores de telemetría anteriores.
  • Use inicializadores de telemetría para enriquecer la telemetría con más propiedades o invalidar una existente. Use un procesador de telemetría para filtrar la telemetría.

Agregar o modificar propiedades

Use inicializadores de telemetría para enriquecer la telemetría con información adicional o para invalidar las propiedades de telemetría establecidas por los módulos de telemetría estándar.

Por ejemplo, Application Insights para un paquete web recopila telemetría sobre solicitudes HTTP. De forma predeterminada, marca cualquier solicitud con un código >de respuesta =400 como error. Si en su lugar quiere tratar 400 como correcto, puede proporcionar un inicializador de telemetría que establezca la propiedad de éxito.

Si proporciona un inicializador de telemetría, este se invoca cada vez que se llama a alguno de los métodos Track*(). Este inicializador incluye los Track() métodos llamados por los módulos de telemetría estándar. Por convención, estos módulos no establecen ninguna propiedad ya establecida por un inicializador. Se llama a los inicializadores de telemetría antes de llamar a los procesadores de telemetría, por lo que los enriquecimientos realizados por inicializadores son visibles para los procesadores.

Inicializadores de telemetría

Para enriquecer la telemetría con información adicional o invalidar las propiedades de telemetría establecidas por los módulos de telemetría estándar, use inicializadores de telemetría.

Los inicializadores de telemetría establecen propiedades de contexto que se envían junto con todos los elementos de telemetría. Puede escribir sus propios inicializadores para establecer propiedades de contexto.

Los inicializadores estándar están todos establecidos por los paquetes NuGet web o WindowsServer:

Inicializador Description
AccountIdTelemetryInitializer Establece la propiedad AccountId.
AuthenticatedUserIdTelemetryInitializer Establece la propiedad AuthenticatedUserId como establecida por el SDK de JavaScript.
AzureRoleEnvironmentTelemetryInitializer Actualiza las propiedades RoleName y RoleInstance del contexto Device de todos los elementos de telemetría con información extraída del entorno de tiempo de ejecución de Azure.
BuildInfoConfigComponentVersionTelemetryInitializer Actualiza la propiedad Version del contexto Component para todos los elementos de telemetría con el valor extraído del archivo BuildInfo.config generado por MS Build.
ClientIpHeaderTelemetryInitializer Actualiza la propiedad Ip del contexto Location de todos los elementos de telemetría en función del encabezado HTTP X-Forwarded-For de la solicitud.
DeviceTelemetryInitializer Actualiza las siguientes propiedades del contexto Device para todos los elementos de telemetría:

• Type se establece en PC.
• Id se establece en el nombre de dominio del equipo donde se ejecuta la aplicación web.
• OemName se establece en el valor extraído del campo Win32_ComputerSystem.Manufacturer con WMI.
• Model se establece en el valor extraído del campo Win32_ComputerSystem.Model con WMI.
• NetworkType se establece en el valor extraído de la propiedad NetworkInterface.
• Language se establece en el nombre de la propiedad CurrentCulture.
DomainNameRoleInstanceTelemetryInitializer Actualiza la propiedad RoleInstance del contexto Device para todos los elementos de telemetría con el nombre de dominio del equipo donde se ejecuta la aplicación web.
OperationNameTelemetryInitializer Actualiza la propiedad Name de RequestTelemetry y la propiedad Name del contexto Operation de todos los elementos de telemetría según el método HTTP, así como los nombres del controlador MVC de ASP.NET y la acción que se invoca para procesar la solicitud.
OperationIdTelemetryInitializer o OperationCorrelationTelemetryInitializer Actualiza la propiedad de contexto Operation.Id de todos los elementos de telemetría de los que se realiza el seguimiento al controlar una solicitud con el RequestTelemetry.Id generado automáticamente.
SessionTelemetryInitializer Actualiza la propiedad Id del contexto Session de todos los elementos de telemetría con valores extraídos de la cookie ai_session que genera el código de instrumentación de JavaScript ApplicationInsights que se ejecuta en el explorador del usuario.
SyntheticTelemetryInitializer o SyntheticUserAgentTelemetryInitializer Actualiza las propiedades de los contextos User, Session, y Operation de todos los elementos de telemetría rastreados al administrar una solicitud de un origen sintético, como una prueba de disponibilidad o un bot de motor de búsqueda. De forma predeterminada, el Explorador de métricas no muestra telemetría sintética.

Conjunto de <Filters> que identifica las propiedades de las solicitudes.
UserTelemetryInitializer Actualiza las propiedades Id y AcquisitionDate del contexto User de todos los elementos de telemetría con valores extraídos de la cookie ai_user que genera el código de instrumentación de JavaScript de Application Insights que se ejecuta en el explorador del usuario.
WebTestTelemetryInitializer Establece el id. de usuario, el id. de sesión y las propiedades de origen sintético para las solicitudes HTTP que proceden de las pruebas de disponibilidad.

Conjunto de <Filters> que identifica las propiedades de las solicitudes.

Nota:

En el caso de las aplicaciones de .NET que se ejecutan en Azure Service Fabric, puede incluir el paquete NuGet Microsoft.ApplicationInsights.ServiceFabric. Este paquete incluye una propiedad FabricTelemetryInitializer, que agrega propiedades de Service Fabric a elementos de telemetría. Para obtener más información, consulte la página de GitHub sobre las propiedades que agrega este paquete de NuGet.

Agregar ITelemetryInitializer

En este blog se describe un proyecto para diagnosticar problemas de dependencia mediante el envío automático de pings normales a dependencias.

  1. Definición del inicializador

    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. Cargar el inicializador

Opción 1: Configuración en el código

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

Opción 2: Configuración en ApplicationInsights.config

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

Vea más de este ejemplo.

Nota:

Asegúrese de que el archivo applicationinsights.config está en el directorio de salida y contiene los cambios recientes.

ITelemetryInitializers de ejemplo

Adición de una propiedad personalizada

El inicializador de ejemplo siguiente agrega una propiedad personalizada a cada telemetría de seguimiento.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}
Adición de un nombre de rol en la nube y una instancia de rol en la nube

Paso 1: Escribir un Inicializador de Telemetría Personalizada

El siguiente inicializador de ejemplo establece el nombre de rol en la nube a cada una de las telemetrías de las que se ha realizado un seguimiento.

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

Paso 2: Cargar un inicializador en TelemetryConfiguration

En el archivo ApplicationInsights.config :

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

Un método alternativo para ASP.NET aplicaciones web consiste en crear instancias del inicializador en el código. En el ejemplo siguiente se muestra código en el archivo Global.aspx.cs :

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }
Controlar la dirección IP del cliente utilizada para mapeos de geolocalización

El inicializador de ejemplo siguiente establece la dirección IP del cliente, que se utiliza para la asignación de geolocalización, en lugar de la dirección IP del socket del cliente, durante la recopilación de telemetría.

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

Procesadores de telemetría

Los procesadores de telemetría pueden filtrar y modificar cada elemento de telemetría justo antes de que se envíe desde el SDK al portal.

  1. Implemente ITelemetryProcessor.

    Los procesadores de telemetría crean una cadena de procesamiento. Al crear una instancia de un procesador de telemetría, se le asigna una referencia al siguiente procesador de la cadena. Cuando se pasa un punto de datos de telemetría al método de proceso, realiza su trabajo y, a continuación, llama a (o no llama) al siguiente procesador de telemetría de la cadena.

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

  2. Agregue el procesador.

    Inserte este fragmento de código en ApplicationInsights.config:

    <TelemetryProcessors>
  <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
    <!-- Set public property -->
    <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
  </Add>
</TelemetryProcessors>

    Puede pasar valores de cadena desde el archivo .config proporcionando propiedades con nombre públicas en la clase.

    Advertencia

    Asegúrese de que el nombre de tipo y los nombres de propiedad en el archivo .config coincidan con los nombres de clase y propiedad en el código. Si el archivo .config hace referencia a un tipo o propiedad inexistentes, el SDK puede no enviar datos de telemetría de forma silenciosa.

    Como alternativa, puede inicializar el filtro en el código. En una clase de inicialización adecuada, por ejemplo, AppStart en Global.asax.cs, inserte el procesador en la cadena:

    Nota:

    El ejemplo de código siguiente está obsoleto, pero está disponible aquí para la posteridad. Considere la posibilidad de empezar a trabajar con OpenTelemetry o migrar 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();

    Los clientes de telemetría creados después de este punto usan sus procesadores.

    Procesador de telemetría de muestreo adaptivo (desde 2.0.0-beta3)

    Esta funcionalidad está habilitada de forma predeterminada. Si la aplicación envía una cantidad considerable de datos de telemetría, este procesador quita algunos de ellos.

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

    El parámetro proporciona el destino que el algoritmo intenta alcanzar. Cada instancia del SDK funciona de forma independiente. Por lo tanto, si el servidor es un clúster de varias máquinas, el volumen real de telemetría se multiplica en consecuencia.

    Aprenda más sobre el muestreo.

    Procesador de telemetría de muestreo de tasa fija (desde 2.0.0-beta1)

    También hay un procesador de telemetría de muestreo estándar (desde la versión 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>

Filtros de ejemplo

Solicitudes sintéticas

Filtre los bots y las pruebas web. Aunque el Explorador de métricas ofrece la opción de filtrar orígenes sintéticos, esta opción reduce el tamaño de la ingesta y el tráfico filtrándolos directamente en el SDK.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}
Error de autenticación

Filtre las solicitudes con una respuesta "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);
}
Filtrar las rápidas llamadas de dependencia remota

Si desea diagnosticar solo las llamadas lentas, filtre las rápidas.

Nota:

Este filtrado sesga las estadísticas que ve en el portal.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

Muestreo

Para obtener información sobre cómo configurar el muestreo para aplicaciones de ASP.NET, consulte Muestreo en Application Insights.

Enriquecimiento de datos a través de HTTP

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

Administración de componentes del SDK

En esta sección

Puede personalizar el SDK de Application Insights para ASP.NET, ASP.NET Core y el servicio de trabajo para cambiar la configuración predeterminada.

El SDK de Application Insights para .NET consta de numerosos paquetes de NuGet. El paquete principal proporciona la API para enviar telemetría a Application Insights. Numerosos paquetes proporcionan módulos e inicializadores de telemetría para hacer un seguimiento automático de la telemetría de la aplicación y su contexto. Si ajusta el archivo de configuración, puede habilitar o deshabilitar los módulos e inicializadores de telemetría. También puede establecer parámetros para algunos de ellos.

El archivo de configuración se llama ApplicationInsights.config o ApplicationInsights.xml. El nombre depende del tipo de la aplicación. Se agrega automáticamente al proyecto cuando se instalan la mayoría de las versiones del SDK.

De forma predeterminada, cuando se usa la experiencia automatizada de los proyectos de plantilla de Visual Studio que admiten Agregar>Telemetría de Application Insights, se crea el archivo ApplicationInsights.config en la carpeta raíz del proyecto. Después de la compilación, se copia en la carpeta bin. También es agregado a una aplicación web por el Agente de Application Insights en un servidor IIS.

Importante

El archivo de configuración se omite si se usa la extensión para sitios web de Azure o la extensión para máquinas virtuales de Azure y conjuntos de escalado de máquinas virtuales de Azure .

No hay un archivo equivalente para controlar el SDK en una página web.

Canales de telemetría

Los canales de telemetría son una parte integral de los SDK de Application Insights. Administran el almacenamiento en búfer y la transmisión de telemetría al servicio Application Insights. Las versiones de los SDK de .NET y .NET Core tienen dos canales de telemetría integrados: InMemoryChannel y ServerTelemetryChannel. En esta sección se describe cada canal y se muestra cómo personalizar el comportamiento del canal.

Nota:

Para revisar las preguntas más frecuentes (P+F), consulte Preguntas más frecuentes sobre los canales de telemetría.

¿Cuáles son los canales de telemetría?

Los canales de telemetría son responsables de almacenar en búfer los elementos de telemetría y enviarlos al servicio Application Insights, donde se almacenan con finalidades de consultas y análisis. Un canal de telemetría es cualquier clase que implementa la interfaz Microsoft.ApplicationInsights.ITelemetryChannel.

El método Send(ITelemetry item) de un canal de telemetría se invoca después de llamar a todos los inicializadores y procesadores de telemetría. Por lo tanto, los elementos descartados por un procesador de telemetría no llegan al canal. Normalmente el método Send() no envía los elementos al back-end de manera instantánea. Por lo general, los almacena en búfer y los envía en lotes a fin de que la transmisión sea eficaz.

Evite llamar a Flush(), a menos que sea fundamental enviar datos de telemetría almacenados en búfer inmediatamente. Úselo solo en escenarios como el apagado de la aplicación, el control de excepciones o cuando se usan procesos de corta duración, como trabajos en segundo plano o herramientas de línea de comandos. En aplicaciones web o servicios de larga duración, el SDK controla el envío de telemetría automáticamente. Llamar a Flush() innecesariamente puede causar problemas de rendimiento.

Live Metrics Stream también tiene un canal personalizado que sustenta el streaming en vivo de la telemetría. Este canal es independiente del canal de telemetría normal, por lo que no se cubre en este documento.

Canales de telemetría integrados

Los SDK de .NET Core y .NET de Application Insights se envían con dos canales integrados:

  • InMemoryChannel: Un canal ligero que almacena en búfer los elementos en la memoria hasta que se envían. Los elementos se almacenan en búfer en la memoria y se vacían una vez cada 30 segundos, o cada vez que se almacenan en búfer 500 elementos. Este canal ofrece garantías de confiabilidad mínimas porque no reintenta el envío de telemetría tras un error. Este canal tampoco mantiene elementos en el disco. Por lo tanto, los elementos no enviados se pierden permanentemente al cerrar la aplicación, independientemente de si se cierra de forma adecuada o no. Este canal implementa un método Flush() que puede usarse para vaciar por la fuerza todos los elementos de telemetría que hay en la memoria de manera sincrónica. Resulta adecuado para las aplicaciones de ejecución breve en las que es ideal realizar un vaciado sincrónico.

    El canal forma parte del mayor paquete Microsoft.ApplicationInsights de NuGet y es el que usa el SDK de manera predeterminada cuando no hay nada más configurado.

  • ServerTelemetryChannel: Un canal más avanzado que tiene directivas de reintento y la capacidad de almacenar datos en un disco local. Este canal reintenta el envío de telemetría si se producen errores transitorios. Asimismo, usa el almacenamiento en disco local para mantener los elementos en el disco durante las interrupciones de red o grandes volúmenes de telemetría. Debido a estos mecanismos de reintento y el almacenamiento en disco local, este canal se considera más confiable. Se recomienda para todos los escenarios de producción. Es la opción predeterminada para las aplicaciones ASP.NET y ASP.NET Core que están configuradas según la documentación oficial. Este canal está optimizado para escenarios de servidor con procesos de larga ejecución. El método Flush() que implementa este canal no es sincrónico.

    Este canal se incluye con el paquete Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel de NuGet y se adquiere automáticamente cuando se utiliza el paquete Microsoft.ApplicationInsights.AspNetCore o Microsoft.ApplicationInsights.Web de NuGet.

Configuración de un canal de telemetría

Para configurar un canal de telemetría, debe establecerlo en la configuración de telemetría activa. En el caso de las aplicaciones de ASP.NET, la configuración implica establecer la instancia del canal de telemetría en TelemetryConfiguration.Active o bien modificar ApplicationInsights.config. Para las aplicaciones de ASP.NET Core, la configuración implica agregar el canal al contenedor de inserción de dependencias.

En las secciones siguientes, se muestran ejemplos de configuración del valor StorageFolder para el canal en distintos tipos de aplicaciones. StorageFolder es solo uno de los valores configurables. Para obtener la lista completa de valores de configuración, consulte la sección Valores configurables en los canales más adelante en este artículo.

Opción 1: Configuración en el código

El código siguiente configura una instancia de ServerTelemetryChannel con StorageFolder establecido en una ubicación personalizada. Agregue este código al principio de la aplicación, normalmente en el método Application_Start() de 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;
}

Opción 2: Configuración en ApplicationInsights.config

En la sección siguiente de ApplicationInsights.config se muestra el canal configurado ServerTelemetryChannel con StorageFolder establecido en una ubicación personalizada:

    <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>

Configuración en código para aplicaciones de consola

En el caso de las aplicaciones de consola, el código es el mismo para .NET y .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Detalles de funcionamiento de ServerTelemetryChannel

ServerTelemetryChannel almacena los elementos que llegan de un búfer en memoria. Los elementos se serializan, comprimen y almacenan en una instancia Transmission una vez cada 30 segundos o cuando se almacenan en búfer 500 elementos. Una sola instancia de Transmissioncontiene hasta 500 elementos y representa un lote de datos de telemetría que se envía a través de una sola llamada HTTPS al servicio de Application Insights.

De forma predeterminada, se puede enviar un máximo de 10 instancias de Transmission en paralelo. Si llegan datos de telemetría a velocidades más rápidas, o si el back-end de Application Insights o la red funcionan con lentitud, las instancias de Transmission se almacenan en memoria. La capacidad predeterminada de este búfer Transmission en memoria es de 5 MB. Cuando se supera la capacidad en memoria, las instancias Transmission se almacenan en el disco local hasta un límite de 50 MB.

Las instancias de Transmission también se almacenan en el disco local cuando hay problemas de red. Solo los elementos que se almacenan en un disco local sobreviven a un bloqueo de la aplicación. Se envían siempre que la aplicación se inicia de nuevo. Si los problemas de red persisten, ServerTelemetryChannel usa una lógica de retroceso exponencial que oscila entre 10 segundos y 1 hora antes de volver a intentar enviar la telemetría.

Valores configurables en los canales

Para obtener la lista completa de valores configurables de cada canal, consulte:

A continuación, le mostramos la configuración que se usa con más frecuencia para ServerTelemetryChannel:

  • MaxTransmissionBufferCapacity: cantidad máxima de memoria, en bytes, que usa el canal para las transmisiones de búfer en memoria. Cuando se alcanza esta capacidad, los nuevos elementos se almacenan directamente en el disco local. El valor predeterminado es de 5 MB. Si se establece un valor mayor, se produce menos uso del disco, pero recuerde que los elementos en memoria se pierden si la aplicación se bloquea.

  • MaxTransmissionSenderCapacity: el número máximo de instancias Transmission que se envían a Application Insights al mismo tiempo. El valor predeterminado es 10. Este valor puede configurarse en un número mayor, lo que se recomienda cuando se genera un gran volumen de telemetría. El gran volumen normalmente tiene lugar durante las pruebas de carga o cuando se desactiva el muestreo.

  • StorageFolder: Carpeta que usa el canal para almacenar elementos en el disco según sea necesario. En Windows, se usa %LOCALAPPDATA% o %TEMP% si no se especifica ninguna otra ruta de acceso de forma explícita. En entornos distintos de Windows, de forma predeterminada se usan las siguientes ubicaciones (en orden): %TMPDIR%, /var/tmp/ o /tmp/.

¿Qué canal debería usar?

Recomendamos ServerTelemetryChannel para la mayoría de los escenarios de producción que impliquen aplicaciones de larga ejecución. Para más información sobre el vaciado de telemetría, lea Acerca del uso Flush().

Cuándo usar Flush()

El método Flush() envía cualquier telemetría almacenada en búfer inmediatamente. Sin embargo, solo se debe usar en escenarios específicos.

Utilice Flush() si:

  • La aplicación está a punto de apagarse y quiere asegurarse de que la telemetría se envía antes de salir.
  • Está en un controlador de excepciones y necesita garantizar que se entregue la telemetría.
  • Está escribiendo un proceso de corta duración, como un trabajo en segundo plano o una herramienta de la CLI que sale rápidamente.

Evite el uso de Flush() en aplicaciones de larga duración, como los servicios web. El SDK administra automáticamente el almacenamiento en búfer y la transmisión. Llamar a Flush() innecesariamente puede causar problemas de rendimiento y no garantiza que se envíen todos los datos, especialmente cuando se usa ServerTelemetryChannel, que no se vacía sincrónicamente.

Módulos de telemetría

Application Insights recopila automáticamente información de telemetría sobre cargas de trabajo específicas sin necesidad de seguimiento manual por parte del usuario.

Los siguientes módulos de recopilación automática están habilitados de forma predeterminada. Puede deshabilitarlos o configurarlos para modificar su comportamiento predeterminado.

Cada módulo de telemetría recopila un tipo específico de datos y usa la API principal para enviar dichos datos. Los módulos los instalan diferentes paquetes NuGet, que también agregan las líneas necesarias al archivo .config.

Area Description
Seguimiento de solicitudes Recopila telemetría de las solicitudes (tiempo de respuesta, código de resultado) para las solicitudes web entrantes.

Módulo:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
Seguimiento de dependencias Recopila telemetría sobre las dependencias salientes (llamadas HTTP, llamadas SQL). Para trabajar en IIS, instale el agente de Application Insights. También puede escribir el seguimiento de dependencias personalizado mediante TrackDependency API. Admite la auto instrumentación con App Service y máquinas virtuales y la supervisiónde conjuntos de escalado de máquinas virtuales.

Módulo:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.DependencyCollector
Contadores de rendimiento Recopila contadores de rendimiento de Windows (CPU, memoria, carga de red de las instalaciones de IIS). Especifique qué contadores (incluidos los personalizados). Para más información, consulte Recopilación de contadores de rendimiento del sistema.

Módulo:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
NuGet:Microsoft.ApplicationInsights.PerfCounterCollector
Contadores de eventos Recopila EventCounters de .NET. Recomendado para ASP.NET Core y multiplataforma en lugar de contadores de rendimiento de Windows.

Módulo:EventCounterCollectionModule (SDK ≥ 2.8.0)
Live Metrics (QuickPulse) Recopila telemetría para el panel Live Metrics.

Módulo:QuickPulseTelemetryModule
Latidos (App Service) Envía latidos y métricas personalizadas para el entorno de App Service.

Módulo:AppServicesHeartbeatTelemetryModule
Latidos (máquinas virtuales y conjuntos de escalado de máquinas virtuales) Envía latidos y métricas personalizadas para el entorno de máquina virtual de Azure.

Módulo:AzureInstanceMetadataTelemetryModule
Telemetría de diagnóstico Notifica errores en el código de instrumentación de Application Insights (por ejemplo, contadores que faltan, excepciones ITelemetryInitializer). La telemetría de seguimiento aparece en la Búsqueda de diagnóstico.

Módulo:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet:Microsoft.ApplicationInsights

Nota: Si solo instala este paquete, el archivo ApplicationInsights.config no se crea automáticamente.
Modo de desarrollador (depurador asociado) Fuerza a TelemetryChannel a enviar elementos inmediatamente cuando se adjunta el depurador. Reduce la latencia, pero aumenta la sobrecarga de CPU o red.

Módulo:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet:Application Insights Windows Server
Seguimiento de excepciones (Web) Realiza un seguimiento de las excepciones no controladas en las aplicaciones web. Consulte Errores y excepciones.

Módulo:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
NuGet:Microsoft.ApplicationInsights.Web
Seguimiento de excepciones (no observado o no controlado) Realiza un seguimiento de las excepciones de tareas no observadas y las excepciones no controladas para roles de trabajo, servicios de Windows y aplicaciones de consola.

Módulos:
 • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule
 • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule
NuGet:Microsoft.ApplicationInsights.WindowsServer
Seguimiento de EventSource Envía eventos EventSource configurados a Application Insights como seguimientos.

Módulo:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet:Microsoft.ApplicationInsights.EventSourceListener
Recopilador ETW Envía eventos de proveedor ETW configurados a Application Insights como seguimientos.

Módulo:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet:Microsoft.ApplicationInsights.EtwCollector
API principal (no un módulo) API principal que usan otros componentes de telemetría y para la telemetría personalizada.

Módulo:Microsoft.ApplicationInsights package
NuGet:Microsoft.ApplicationInsights
Nota: Si solo instala este paquete, el archivo ApplicationInsights.config no se crea automáticamente.

Configuración de módulos de telemetría

Use la sección TelemetryModules de ApplicationInsights.config para configurar, agregar o quitar módulos. Los ejemplos siguientes:

  • Configure DependencyTrackingTelemetryModule (habilite la inserción de encabezados W3C).
  • Configure EventCounterCollectionModule (borre los valores predeterminados y agregue un único contador).
  • Deshabilite la colección perf-counter quitando PerformanceCollectorModule.
<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>

Nota:

El conjunto exacto de módulos presentes en ApplicationInsights.config depende de los paquetes del SDK que haya instalado.

Deshabilitar la telemetría

Hay un nodo en el archivo de configuración para cada módulo. Para deshabilitar un módulo, elimine el nodo o conviértalo en comentario.

Cadena de conexión

Esta configuración determina el recurso de Application Insights en el que aparecen los datos. Normalmente, se crea un recurso independiente, con una cadena de conexión independiente, para cada una de las aplicaciones.

Consulte Cadenas de conexión en Application Insights para obtener ejemplos de código.

Si desea establecer la cadena de conexión dinámicamente, por ejemplo, para enviar resultados de la aplicación a distintos recursos, puede omitir la cadena de conexión del archivo de configuración y establecerla en el código en su lugar.

Para establecer la cadena de conexión para todas las instancias de TelemetryClient, incluidos los módulos de telemetría estándar, realice este paso en un método de inicialización, como global.aspx.cs en un servicio ASP.NET:

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        var telemetryClient = new TelemetryClient(configuration);

Si solo quiere enviar un conjunto específico de eventos a un recurso diferente, puede establecer la clave para un cliente de telemetría específico:


    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

Para obtener una nueva cadena de conexión, cree un nuevo recurso en el portal de Application Insights.

Proveedor ApplicationId

Nota:

Para ASP.NET, este proveedor está disponible a partir del SDK v2.6.0*.

El propósito de este proveedor es buscar un identificador de aplicación basado en una cadena de conexión. El identificador de aplicación se incluye en RequestTelemetry y DependencyTelemetry y se usa para determinar la correlación en el portal.

Esta funcionalidad está disponible estableciendo TelemetryConfiguration.ApplicationIdProvider.

Interfaz: IApplicationIdProvider

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

Se proporcionan dos implementaciones en el SDK Microsoft.ApplicationInsights: ApplicationInsightsApplicationIdProvider y DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Este contenedor es para nuestra API Profile. Limita las solicitudes y los resultados de la memoria caché. Este proveedor se incluye automáticamente al instalar Microsoft.ApplicationInsights.DependencyCollector o Microsoft.ApplicationInsights.Web.

La clase expone una propiedad opcional denominada ProfileQueryEndpoint. De forma predeterminada, se establece en https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Si necesita configurar un proxy, le recomendamos que use la dirección base y asegúrese de que la ruta de acceso incluya /api/profiles/{0}/appId. En el runtime, {0} se reemplaza por la clave de instrumentación de cada solicitud.

Ejemplo de configuración con 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>

Ejemplo de configuración mediante código

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Este proveedor estático se basa en los pares de clave de instrumentación e identificador de aplicación configurados.

Esta clase tiene la propiedad Defined, que es un elemento Dictionary<string,string> de pares de clave de instrumentación e identificador de aplicación.

Esta clase tiene la propiedad opcional Next, que se puede usar para configurar otro proveedor que se usará cuando se solicita una cadena de conexión que no existe en la configuración.

Ejemplo de configuración con ApplicationInsights.config

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

Ejemplo de configuración mediante código

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

Configuración de la recopilación de instantáneas

Para obtener información sobre cómo configurar la recopilación de instantáneas para aplicaciones ASP.NET y ASP.NET Core, consulte Habilitación de Snapshot Debugger para aplicaciones .NET en Azure Service Fabric, Cloud Services y Virtual Machines.

Adición de la supervisión del lado cliente

En las secciones anteriores se proporcionan instrucciones sobre métodos para configurar automática y manualmente la supervisión de servidor. Para agregar la supervisión de cliente, use el SDK de JavaScript del lado cliente. Puede supervisar las transacciones del lado cliente de cualquier página web agregando una Script de cargador del SDK de JavaScript (Web) antes de la etiqueta de cierre </head> del HTML de la página.

Aunque es posible agregar manualmente el Script del cargador del SDK de JavaScript (Web) al encabezado de cada página HTML, se recomienda agregar el Script del cargador del SDK de JavaScript (Web) a una página principal. Esa acción inserta el script de carga del SDK de JavaScript (Web) en todas las páginas de un sitio.

Para la aplicación MVC de ASP.NET basada en plantilla de este artículo, el archivo que debe editar es _Layout.cshtml. Puede encontrarlo en Vistas>compartidas. Para agregar la supervisión de cliente, abra _Layout.cshtml y siga las Instrucciones de instalación basadas en el Script del cargador del SDK de JavaScript (Web) del artículo sobre configuración del SDK de JavaScript del lado cliente.

API principal para eventos y métricas personalizados

Inserte algunas líneas de código en la aplicación para averiguar qué hacen los usuarios con él o para ayudar a diagnosticar problemas. Puede enviar telemetría desde aplicaciones de dispositivo y escritorio, clientes web y servidores web. Use la API de telemetría principal de Application Insights para enviar eventos y métricas personalizados y sus propias versiones de telemetría estándar. Esta API es la misma API que usan los recopiladores de datos estándar de Application Insights.

Resumen de LA API

La API principal es uniforme en todas las plataformas, aparte de algunas variaciones como GetMetric (solo .NET).

Método Se utiliza para
TrackPageView Páginas, pantallas, paneles o formularios.
TrackEvent Acciones del usuario y otros eventos. Se usa para realizar un seguimiento del comportamiento del usuario o para supervisar el rendimiento.
GetMetric Métricas cero y multidimensionales, agregación configurada centralmente, solo en C#.
TrackMetric Medidas de rendimiento como las longitudes de cola no relacionadas con eventos específicos.
TrackException Excepciones de registro para diagnóstico. Permite realizar el seguimiento del lugar donde se producen en relación con otros eventos y examinar los seguimientos de pila.
TrackRequest Registrar la frecuencia y la duración de las solicitudes de servidor para el análisis de rendimiento.
TrackTrace Mensajes de registro de diagnóstico de recursos. También puede capturar registros de terceros.
TrackDependency Registrar la duración y la frecuencia de las llamadas a componentes externos de los que depende la aplicación.

Puede adjuntar propiedades y métricas a la mayoría de estas llamadas de telemetría.

Prerrequisitos

Si aún no tiene una referencia en el SDK de Application Insights:

  1. Agregue el SDK de Application Insights al proyecto.

  2. En el código del dispositivo o del servidor web, incluya:

    using Microsoft.ApplicationInsights;

Obtención de una instancia de TelemetryClient

Obtener una instancia de TelemetryClient:

Nota:

Si usa Azure Functions v2+ o Azure WebJobs v3+, consulte Supervisión de Azure Functions.

Nota:

En el caso de las aplicaciones de ASP.NET Core y aplicaciones que no son HTTP o de trabajo para .NET y .NET Core, obtenga una instancia de TelemetryClient del contenedor de inserción de dependencias, tal como se explica en la documentación correspondiente.

private TelemetryClient telemetry = new TelemetryClient();

Si ve un mensaje que indica que este método está obsoleto, consulte microsoft/ApplicationInsights-dotnet#1152 para obtener más información.

Las solicitudes HTTP entrantes se capturan automáticamente. Es posible que quiera crear más instancias de TelemetryClient para otros módulos de la aplicación. Por ejemplo, puede tener una TelemetryClient instancia en la clase de middleware para notificar eventos de lógica de negocios. Puede establecer propiedades como UserId e DeviceId identificar la máquina. Esta información se adjunta a todos los eventos que envía la instancia.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Nota:

TelemetryClient es segura para la ejecución de subprocesos.

TrackEvent

En Application Insights, un evento personalizado es un punto de datos que puede mostrar en el Explorador de métricas como un recuento agregado y en Búsqueda de diagnóstico como repeticiones individuales. (No está relacionado con MVC u otros 'eventos' de framework).

Inserte TrackEvent invocaciones en tu código para contar varios eventos. Por ejemplo, puede que quiera realizar un seguimiento de la frecuencia con la que los usuarios eligen una característica determinada. O bien, es posible que quiera saber con qué frecuencia logran ciertos objetivos o cometen determinados tipos de errores.

Por ejemplo, en una aplicación de juego, envía un evento cada vez que un usuario gana el juego:

telemetry.TrackEvent("WinGame");

Eventos personalizados en Log Analytics

Los datos de telemetría están disponibles en la tabla customEvents de la pestaña Registros de Application Insights o en la experiencia de uso. Es posible que los eventos provengan de trackEvent(..) o del complemento Autocollection de Click Analytics.

Si el muestreo está en funcionamiento, la itemCount propiedad muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de 10 llamadas a trackEvent(), el proceso de muestreo transmite solo uno de ellos. Para obtener un recuento correcto de eventos personalizados, use código como customEvents | summarize sum(itemCount).

Nota:

itemCount tiene un valor mínimo de uno; el propio registro representa una entrada.

GetMetric

Para obtener información sobre cómo usar eficazmente la GetMetric() llamada para capturar métricas preagregadas localmente para aplicaciones .NET y .NET Core, consulte Recopilación de métricas personalizadas en .NET y .NET Core.

TrackMetric

Nota:

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric no es el método preferido para enviar métricas. Las métricas siempre deben estar preagregadas durante un período de tiempo antes de enviarse. Use una de las sobrecargas de GetMetric(..) para obtener un objeto de métrica para acceder a las capacidades de agregación previa del SDK.

Si está implementando su propia lógica de preagregación, puede usar el método TrackMetric() para enviar los agregados resultantes. Si la aplicación requiere enviar un elemento de telemetría independiente en cada ocasión sin agregación a lo largo del tiempo, es probable que tenga un caso de uso para la telemetría de eventos. Consulte TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights puede trazar métricas que no están asociadas a eventos concretos. Por ejemplo, podría supervisar una longitud de cola a intervalos regulares. Con las métricas, las mediciones individuales son de menor interés que las variaciones y tendencias, por lo que los gráficos estadísticos son útiles.

Para enviar métricas a Application Insights, puede usar la TrackMetric(..) API. Hay dos maneras de enviar una métrica:

  • Valor único. Cada vez que realice una medición en la aplicación, envíe el valor correspondiente a Application Insights.

    Por ejemplo, supongamos que tiene una métrica que describe el número de elementos de un contenedor. Durante un período de tiempo determinado, primero se colocan tres elementos en el contenedor y, a continuación, se quitan dos elementos. En consecuencia, llamarías TrackMetric dos veces. En primer lugar, pasaría el valor 3 y, a continuación, pasaría el valor -2. Application Insights almacena ambos valores.

  • Agregación. Al trabajar con métricas, cada medida rara vez es de interés. En su lugar, es importante un resumen de lo que ha ocurrido durante un período de tiempo determinado. Este resumen se denomina agregación.

    En el ejemplo anterior, la suma de métricas agregadas para ese período de tiempo es 1 y el recuento de los valores de métrica es 2. Cuando se usa el enfoque de agregación, se invoca TrackMetric solo una vez por período de tiempo y se envían los valores agregados. Se recomienda este enfoque porque puede reducir significativamente el costo y la sobrecarga de rendimiento enviando menos puntos de datos a Application Insights, a la vez que recopila toda la información pertinente.

Ejemplos de valores únicos

Para enviar un único valor de métrica:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Métricas personalizadas en Log Analytics

La telemetría está disponible en la tabla customMetrics de Análisis de Application Insights. Cada fila representa una llamada a trackMetric(..) en la aplicación.

  • valueSum: la suma de las medidas. Para obtener el valor medio, divida por valueCount.
  • valueCount: número de medidas agregadas en esta trackMetric(..) llamada.

Nota:

valueCount tiene un valor mínimo de uno; el propio registro representa una entrada.

Vistas de página

En una aplicación de dispositivo o página web, la telemetría de la vista de página se envía de forma predeterminada cuando se carga cada pantalla o página. Pero puede cambiar el valor predeterminado para realizar un seguimiento de las vistas de página en más o diferentes momentos. Por ejemplo, en una aplicación que muestra pestañas o paneles, es posible que desee realizar un seguimiento de una página cada vez que el usuario abra un nuevo panel.

Los datos de usuario y de sesión se envían como propiedades junto a las visualizaciones de página, por lo que los gráficos de usuario y de sesión cobran vida cuando hay telemetría de vistas de página.

Vistas de página personalizadas

telemetry.TrackPageView("GameReviewPage");

Telemetría de página en Log Analytics

En Log Analytics, dos tablas muestran datos de las operaciones del explorador:

  • pageViews: contiene datos sobre la dirección URL y el título de la página.
  • browserTimings: contiene datos sobre el rendimiento del cliente, como el tiempo necesario para procesar los datos entrantes.

Para averiguar cuánto tiempo tarda el explorador en procesar páginas diferentes:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Para descubrir la popularidad de diferentes exploradores:

pageViews
| summarize count() by client_Browser

Para asociar vistas de página a llamadas AJAX, únase a las dependencias:

pageViews
| join (dependencies) on operation_Id

TrackRequest

El SDK del servidor usa TrackRequest para registrar solicitudes HTTP.

También puede llamarlo usted mismo si desea simular solicitudes en un contexto en el que no tiene el módulo de servicio web en ejecución.

La manera recomendada de enviar telemetría de solicitudes es donde la solicitud actúa como contexto de operación.

Contexto de la operación

Puede correlacionar los elementos de telemetría asociandolos con el contexto de la operación. El módulo estándar de seguimiento de solicitudes lo hace para excepciones y otros eventos que se envían mientras se procesa una solicitud HTTP. En Búsqueda y análisis, puede encontrar fácilmente cualquier evento asociado a la solicitud mediante su identificador de operación.

Al realizar un seguimiento manual de la telemetría, la manera más fácil de garantizar la correlación de telemetría es mediante este patrón:

// 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.

Para más información sobre la correlación, consulte Correlación de telemetría en Application Insights.

Junto con la configuración de un contexto de operación, StartOperation crea un elemento de telemetría del tipo que especifique. Envía el elemento de telemetría al eliminar la operación, o si llama explícitamente a StopOperation. Si usa RequestTelemetry como tipo de telemetría, su duración se establece en el intervalo de tiempo entre inicio y detención.

Los elementos de telemetría reportados dentro de un ámbito de operación se convierten en subelementos de dicha operación. Los contextos de operación se pueden anidar.

En Buscar, el contexto de la operación se usa para crear la lista Elementos relacionados .

Captura de pantalla que muestra la lista Elementos relacionados.

Para más información sobre el seguimiento de operaciones personalizadas, consulte Seguimiento de operaciones personalizadas con el SDK de .NET de Application Insights.

Solicitudes en Log Analytics

En Análisis de Application Insights, las solicitudes se muestran en la tabla requests.

Si el muestreo está en funcionamiento, la itemCount propiedad muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de 10 llamadas a trackRequest(), el proceso de muestreo transmite solo uno de ellos. Para obtener un recuento correcto de solicitudes y la duración media segmentadas por nombres de solicitud, use código como:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Envío de excepciones a Application Insights:

Los informes incluyen los seguimientos de la pila.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Los SDK detectan muchas excepciones automáticamente, por lo que no siempre tiene que llamar TrackException explícitamente.

Excepciones en Log Analytics

En Análisis de Application Insights, las excepciones aparecen en la tabla exceptions.

Si el muestreo está en funcionamiento, la itemCount propiedad muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de 10 llamadas a trackException(), el proceso de muestreo transmite solo uno de ellos. Para obtener un recuento correcto de excepciones segmentadas por tipo de excepción, use código como:

exceptions
| summarize sum(itemCount) by type

La mayoría de la información importante de la pila ya se ha extraído en variables independientes, pero puedes descomponer la estructura details para obtener más información. Puesto que se trata de una estructura dinámica, debería convertir el resultado al tipo que espere. Por ejemplo:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Para asociar las excepciones a sus respectivas solicitudes, use una combinación:

exceptions
| join (requests) on operation_Id

TrackTrace

Utilice TrackTrace para ayudar a diagnosticar problemas mediante el envío de un ''trazo de exploración'' a Application Insights. Puede enviar fragmentos de datos de diagnóstico e inspeccionarlos en búsqueda de diagnóstico.

Los adaptadores de registro de .NET usan esta API para enviar registros de terceros al portal.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Registre un evento de diagnóstico, como entrar o salir de un método.

Parámetro Description
message Datos de diagnóstico. Puede ser mucho más largo que un nombre.
properties Asignación de cadena a cadena. Se usan más datos para filtrar excepciones en el portal. El valor predeterminado es vacío.
severityLevel Valores admitidos: SeverityLevel.ts.

Puede buscar en el contenido del mensaje, pero, a diferencia de los valores de propiedades, no puede filtrar por él.

El límite de tamaño en message es mucho mayor que el límite en las propiedades. Una ventaja de TrackTrace es que puede colocar datos relativamente largos en el mensaje. Por ejemplo, puede codificar los datos POST allí.

También puede agregar un nivel de gravedad al mensaje. Y, al igual que otros datos de telemetría, puede agregar propiedades para ayudar a filtrar o buscar diferentes conjuntos de trazas. Por ejemplo:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

En Buscar, puede filtrar fácilmente todos los mensajes de un nivel de gravedad determinado relacionado con una base de datos determinada.

Seguimientos en Log Analytics

En Análisis de Application Insights, las llamadas a TrackTrace aparecen en la tabla traces.

Si el muestreo está en funcionamiento, la itemCount propiedad muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de 10 llamadas a trackTrace(), el proceso de muestreo transmite solo uno de ellos. Para obtener un recuento correcto de llamadas de seguimiento, use código como traces | summarize sum(itemCount).

TrackDependency

Use la TrackDependency llamada para realizar un seguimiento de los tiempos de respuesta y las tasas de éxito de las llamadas a un fragmento de código externo. Los resultados aparecen en los gráficos de dependencias en el portal. El siguiente fragmento de código debe agregarse siempre que se realice una llamada de dependencia.

Nota:

Para .NET y .NET Core, también puede usar el TelemetryClient.StartOperation método (extensión) que rellena las DependencyTelemetry propiedades necesarias para la correlación y otras propiedades, como la hora de inicio y la duración, por lo que no es necesario crear un temporizador personalizado como con los ejemplos siguientes. Para más información, consulte la sección sobre el seguimiento de dependencias salientes en Seguimiento de operaciones personalizadas con el SDK de .NET de Application Insights.

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

Recuerde que los SDK de servidor incluyen un módulo de dependencias que detecta y realiza un seguimiento de determinadas llamadas de dependencia automáticamente, por ejemplo, a bases de datos y API REST. Tiene que instalar un agente en el servidor para que el módulo funcione.

Esta llamada se usa si desea realizar un seguimiento de las llamadas que el seguimiento automatizado no detecta.

Para desactivar el módulo estándar de seguimiento de dependencias en C#, edite ApplicationInsights.config y elimine la referencia a DependencyCollector.DependencyTrackingTelemetryModule.

Dependencias en Log Analytics

En Analytics de Application Insights, las llamadas a trackDependency se muestran en la tabla dependencies.

Si el muestreo está en funcionamiento, la itemCount propiedad muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de 10 llamadas a trackDependency(), el proceso de muestreo transmite solo uno de ellos. Para obtener un recuento correcto de dependencias segmentadas por componente de destino, use código como:

dependencies
| summarize sum(itemCount) by target

Para asociar las dependencias a sus respectivas solicitudes, use una combinación:

dependencies
| join (requests) on operation_Id

Datos de vaciado

Normalmente, el SDK envía datos a intervalos fijos, normalmente 30 segundos o cada vez que el búfer está lleno, que suele ser de 500 elementos. En algunos casos, es posible que quiera vaciar el búfer. Un ejemplo es si usa el SDK en una aplicación que se cierra.

Cuando se usa Flush(), se recomienda este patrón:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Cuando se usa FlushAsync(), se recomienda este patrón:

await telemetryClient.FlushAsync()
// No need to sleep

Se recomienda siempre el vaciado como parte del apagado de la aplicación para garantizar que no se pierdan datos de telemetría.

Nota:

Revisión de la configuración de Autoflush: activar autoflush en tu web.config archivo puede provocar una degradación del rendimiento en las aplicaciones .NET instrumentadas con Application Insights. Con la funcionalidad de autoflush habilitada, cada invocación de los métodos System.Diagnostics.Trace.Trace* da como resultado que los elementos de telemetría individuales se envíen como solicitudes web individuales al servicio de recopilación de datos. Esto puede provocar el agotamiento de la red y el almacenamiento en los servidores web. Para mejorar el rendimiento, se recomienda deshabilitar la autoflush y, además, usar ServerTelemetryChannel, diseñado para una transmisión de datos de telemetría más eficaz.

La función es asincrónica para el canal de telemetría del servidor.

Usuarios autenticados

En una aplicación web, los usuarios se identifican mediante cookies de forma predeterminada. Se puede contar al usuario más de una vez si accede a la aplicación desde un equipo o explorador diferente, o si elimina las cookies.

Si los usuarios inician sesión en la aplicación, puede obtener un recuento más preciso estableciendo el identificador de usuario autenticado en el código del explorador. No es necesario usar el nombre de inicio de sesión real del usuario. Solo tiene que ser un identificador único para ese usuario. No debe incluir espacios ni ninguno de los caracteres ,;=|.

El identificador de usuario también se establece en una cookie de sesión y se envía al servidor. Si se instala el SDK del servidor, el identificador de usuario autenticado se envía como parte de las propiedades de contexto de la telemetría del cliente y del servidor. A continuación, puede filtrar y buscar en él.

Si la aplicación agrupa usuarios en cuentas, también puede pasar un identificador para la cuenta. Se aplican las mismas restricciones de caracteres.

En el Explorador de métricas, puede crear un gráfico que cuente usuarios, autenticados y cuentas de usuario.

También puede buscar puntos de datos de cliente con nombres de usuario y cuentas específicos.

Nota:

La propiedad EnableAuthenticationTrackingJavaScript de la clase ApplicationInsightsServiceOptions del SDK de .NET Core simplifica la configuración de JavaScript necesaria para insertar el nombre de usuario como identificador de autenticación para cada seguimiento enviado por el SDK de JavaScript de Application Insights.

Cuando esta propiedad se establece en true, el nombre del usuario en ASP.NET Core se imprime junto con la telemetría del cliente. Por este motivo, ya no es necesario agregar appInsights.setAuthenticatedUserContext manualmente porque ya está insertado por el SDK para ASP.NET Core. El identificador de autenticación también se envía al servidor donde el SDK de .NET Core identifica y lo usa para cualquier telemetría del lado servidor, como se describe en la referencia de la API de JavaScript.

Para las aplicaciones de JavaScript que no funcionan de la misma manera que ASP.NET Core MVC, como las aplicaciones web SPA, aún necesita agregar appInsights.setAuthenticatedUserContext manualmente.

Filtrar, buscar y segmentar los datos mediante propiedades

Puede adjuntar propiedades y medidas a los eventos, métricas, vistas de página, excepciones y otros datos de telemetría.

Las propiedades son valores de cadena que puede usar para filtrar la telemetría en los informes de uso. Por ejemplo, si la aplicación proporciona varios juegos, puedes adjuntar el nombre del juego a cada evento para que puedas ver qué juegos son más populares.

Hay un límite de 8192 en la longitud de la cadena. Si desea enviar grandes fragmentos de datos, use el parámetro message de TrackTrace.

Las métricas son valores numéricos que se pueden presentar gráficamente. Por ejemplo, es posible que quiera ver si hay un aumento gradual en las puntuaciones que logran los jugadores. Los gráficos se pueden segmentar por las propiedades que se envían con el evento para que pueda obtener gráficos independientes o apilados para diferentes juegos.

Los valores de métrica deben ser mayores o iguales que 0 para mostrarse correctamente.

Hay algunos límites en el número de propiedades, valores de propiedad y métricas que puede usar.

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

Importante

Asegúrese de no registrar información de identificación personal en las propiedades.

Forma alternativa de establecer propiedades y métricas

Si es más conveniente, puede recopilar los parámetros de un evento en un objeto independiente:

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

Advertencia

No reutilice la misma instancia de elemento de telemetría (event en este ejemplo) para llamar Track*() varias veces. Esta práctica puede hacer que la telemetría se envíe con una configuración incorrecta.

Medidas y propiedades personalizadas en Log Analytics

En Log Analytics, las métricas personalizadas y las propiedades se muestran en los customMeasurements atributos y customDimensions de cada registro de telemetría.

Por ejemplo, si agrega una propiedad llamada "game" a la telemetría de solicitudes, esta consulta cuenta el número de apariciones de diferentes valores de "game" y muestra la media de la métrica personalizada "score":

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Observe que:

  • Al extraer un valor de customDimensions o customMeasurements JSON, tiene un tipo dinámico, por lo que debe convertirlo tostring o todouble.
  • Para tener en cuenta la posibilidad de muestreo, use sum(itemCount) no count().

Eventos de cronometraje

A veces desea trazar el tiempo necesario para realizar una acción. Por ejemplo, es posible que quieras saber cuánto tiempo tardan los usuarios en considerar las opciones de un juego. Para obtener esta información, use el parámetro de medida.

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

Propiedades predeterminadas para la telemetría personalizada

Si desea establecer valores de propiedad predeterminados para algunos de los eventos personalizados que escriba, establézcalos en una instancia de TelemetryClient. Se adjuntan a todos los elementos de telemetría que se envían desde ese cliente.

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

Las llamadas de telemetría individuales pueden invalidar los valores predeterminados en sus diccionarios de propiedades.

Para agregar propiedades a todos los datos de telemetría, incluidos los datos de los módulos de recopilación estándar, implemente ITelemetryInitializer.

Deshabilitar la telemetría

Para detener e iniciar dinámicamente la recopilación y transmisión de telemetría:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Modo de desarrollador

Durante la depuración, resulta útil enviar los datos de telemetría por la canalización para así poder ver los resultados inmediatamente. También obtendrá otros mensajes que le ayudarán a realizar un seguimiento de los problemas con la telemetría. Desactívelo en producción, ya que puede ralentizar la aplicación.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Establecimiento de la clave de instrumentación para la telemetría personalizada seleccionada

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Cadena de conexión dinámica

Para evitar mezclar la telemetría de entornos de desarrollo, prueba y producción, puede crear recursos independientes de Application Insights y cambiar sus claves, en función del entorno.

En lugar de obtener la clave de instrumentación del archivo de configuración, puede establecerla en el código. Establezca la clave en un método de inicialización, como global.aspx.cs en un servicio ASP.NET:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

TelemetryContext

TelemetryClient tiene una propiedad Context, que contiene valores que se envían junto con todos los datos de telemetría. Normalmente se establecen mediante los módulos de telemetría estándar, pero también puede establecerlos usted mismo. Por ejemplo:

telemetry.Context.Operation.Name = "MyOperationName";

Si establece cualquiera de estos valores usted mismo, considere la posibilidad de quitar la línea pertinente de ApplicationInsights.config para que los valores y los valores estándar no se confundan.

  • Componente: la aplicación y su versión.
  • Dispositivo: datos sobre el dispositivo en el que se ejecuta la aplicación. En las aplicaciones web, es el servidor o dispositivo cliente desde el que se envía la telemetría.
  • InstrumentationKey: el recurso de Application Insights en Azure donde aparece la telemetría. Normalmente se recoge de ApplicationInsights.config.
  • Ubicación: ubicación geográfica del dispositivo.
  • Operación: en aplicaciones web, la petición HTTP actual. En otros tipos de aplicaciones, puede establecer este valor para agrupar eventos.
    • Id. : valor generado que correlaciona diferentes eventos para que, al inspeccionar cualquier evento en la búsqueda de diagnóstico, puede encontrar elementos relacionados.
    • Nombre: un identificador, normalmente la dirección URL de la solicitud HTTP.
    • SyntheticSource: si no es null o está vacío, una cadena que indica que el origen de la solicitud se ha identificado como un robot o una prueba web. De forma predeterminada, se excluye de los cálculos en el Explorador de métricas.
  • Sesión: sesión del usuario. El identificador se establece en un valor generado, que se cambia cuando el usuario no ha estado activo durante un tiempo.
  • Usuario: información del usuario.

Limits

Hay algunos límites en el número de métricas y eventos por aplicación; es decir, por clave de instrumentación. Los límites dependen del plan de precios que elija.

Resource Límite predeterminado Límite máximo Notas
Total de datos por día 100 GB Póngase en contacto con el soporte técnico. Puede establecer un límite para reducir los datos. Si necesita más datos, puede aumentar el límite en el portal, hasta 1000 GB. Para capacidades mayores de 1000 GB, envíe un correo electrónico a AIDataCap@microsoft.com.
Throttling 32 000 eventos por segundo Póngase en contacto con el soporte técnico. El límite se mide por minuto.
Registros de retención de datos De 30 a 730 días 730 días Este recurso es para Registros.
Métricas de retención de datos 90 días 90 días Este recurso es para el Explorador de métricas.
Retención de resultados detallados de la prueba de disponibilidad de varios pasos 90 días 90 días Este recurso proporciona resultados detallados de cada paso.
Tamaño máximo de elementos de telemetría 64 KB 64 KB
Número máximo de elementos de telemetría por lote 64 000 64 000
Longitud de nombres de propiedades y métricas 150 150 Consulte esquemas de tipos.
Longitud de cadena del valor de propiedad 8,192 8,192 Consulte esquemas de tipos.
Longitud del mensaje de seguimiento y excepción 32,768 32,768 Consulte esquemas de tipos.
Recuento de pruebas de disponibilidad por recurso de Application Insights 100 100
Recuento de pruebas de disponibilidad por grupo de recursos 800 800 Consulte Azure Resource Manager
Redirecciones máximas de pruebas de disponibilidad por prueba 10 10
Frecuencia mínima de pruebas de disponibilidad 300 segundos Las frecuencias de prueba personalizadas o de menos de 5 minutos requieren implementaciones personalizadas de TrackAvailability.
Retención de datos de .NET Profiler y Snapshot Debugger Dos semanas Póngase en contacto con el servicio de soporte técnico. El límite máximo de retención es de seis meses.
Datos enviados por día de .NET Profiler Sin límite Ilimitado.
Datos enviados al día de Snapshot Debugger 30 instantáneas por día por aplicación supervisada Ilimitado. El número de instantáneas recopiladas por aplicación se puede modificar mediante la configuración.

Para más información sobre los precios y cuotas, consulte Facturación de Application Insights.

Para evitar alcanzar el límite de velocidad de datos, use el muestreo.

Para determinar cuánto tiempo se conservan los datos, consulte Retención y privacidad de los datos.

Aplicaciones de ejemplo

Aplicación de consola de .NET Core: use este ejemplo si usa una aplicación de consola escrita en .NET Core (2.0 o posterior) o .NET Framework (4.7.2 o superior).

ASP.NET Core tareas en segundo plano con Servicios hospedados: utilice este ejemplo si está en ASP.NET Core y está creando tareas en segundo plano de acuerdo con las instrucciones oficiales.

Servicio de trabajo de .NET Core: use este ejemplo si tiene una aplicación de servicio de trabajo de .NET de acuerdo con las instrucciones oficiales.

Solución de problemas

Consulte el artículo de solución de problemas dedicado.

Prueba de la conectividad entre el host de la aplicación y el servicio de ingesta

Tanto los SDK como los agentes de Application Insights envían telemetría para ingerirse como llamadas REST a nuestros puntos de conexión de ingesta. Puede probar la conectividad desde su servidor web o la máquina que aloja la aplicación a los puntos finales del servicio de ingesta utilizando clientes REST de bajo nivel mediante comandos de PowerShell o curl. Consulte Solución de problemas de telemetría de aplicaciones que faltan en Azure Monitor Application Insights.

SDK de código abierto

Lectura y contribución al código.

Para obtener las actualizaciones y correcciones de errores más recientes, consulte las notas de la versión.

Notas de lanzamiento

Para la versión 2.12 y versiones posteriores: Kits de desarrollo de software (SDK) de .NET, incluidos ASP.NET, ASP.NET Core y adaptadores de logging

Nuestras actualizaciones del servicio también resumen las principales mejoras de Application Insights.

Pasos siguientes

Documentos de referencia

  • Last updated on