API de Application Insights para eventos y métricas personalizados

  • Artículo

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

Nota:

El 31 de marzo de 2025 finalizará la compatibilidad con la ingesta de claves de instrumentación. La ingesta de claves de instrumentación seguirá funcionando, pero la característica ya no recibirá actualizaciones ni soporte técnico. Transición a las cadenas de conexión para aprovechar las nuevas funcionalidades.

API summary

La API principal es uniforme en todas las plataformas, excepto por algunas pequeñas variaciones como GetMetric (solo .NET).

Método Se usa para
TrackPageView Páginas, pantallas, paneles o formularios.
TrackEvent Acciones de usuario y otros eventos. Se usa para realizar el seguimiento del comportamiento de los usuarios o para supervisar el rendimiento.
GetMetric Métricas cero y multidimensionales, agregación configurada de forma centralizada, solo en C#.
TrackMetric Las medidas de rendimiento, como las longitudes de cola, no están 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 Registro de la frecuencia y duración de las solicitudes de servidor para el análisis de rendimiento.
TrackTrace Mensajes del registro de diagnóstico de recursos. También puede capturar registros de terceros.
TrackDependency Registro de la duración y 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.

Antes de comenzar

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

Obtención de una instancia de TelemetryClient

Obtenga una instancia de TelemetryClient (excepto en JavaScript en páginas web):

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.

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

C#

private TelemetryClient telemetry = new TelemetryClient();

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

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient es segura para la ejecución de subprocesos.

Para proyectos de ASP.NET y Java, 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 instancia de TelemetryClient en la clase de middleware para notificar eventos de la lógica de negocios. Puede establecer propiedades como UserId y DeviceId para identificar la máquina. Esta información se adjunta a todos los eventos enviados por la instancia.

C#

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

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

En proyectos de Node.js, puede usar new applicationInsights.TelemetryClient(instrumentationKey?) para crear una nueva instancia. Se recomienda este enfoque solo para escenarios que requieran una configuración aislada del singleton defaultClient.

TrackEvent

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

Inserte llamadas a TrackEvent en el código para contabilizar diversos eventos: Por ejemplo, puede que desee 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 determinados objetivos o cometen determinados tipos de errores.

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

JavaScript

appInsights.trackEvent({name:"WinGame"});

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "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. Los eventos pueden provenir de trackEvent(..) o del complemento de recopilación automática de análisis de clics.

Si el muestreo está en uso, en la propiedad itemCount se muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackEvent(), el proceso de muestreo solo transmite una. Para obtener un recuento correcto de los eventos personalizados, utilice un código similar a 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 llamada a GetMetric() para capturar métricas previamente agregadas de forma local para aplicaciones de .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 deben agregarse previamente siempre durante un tiempo antes de enviarse. Use una de las sobrecargas de GetMetric(..) para obtener un objeto de métrica para acceder a las funcionalidades de agregación previa del SDK.

Si va a implementar su propia lógica de agregación previa, puede usar el método TrackMetric() para enviar los agregados resultantes. Si la aplicación requiere el envío de 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. Vea TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights puede crear gráficos de métricas que no estén conectadas a eventos determinados. Por ejemplo, puede supervisar una longitud de cola a intervalos regulares. En el caso de las métricas, las mediciones individuales tienen menos interés que las variaciones y tendencias; por tanto, los gráficos estadísticos resultan útiles.

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

  • Un solo valor. Cada vez que realiza una medición en la aplicación, envía el valor correspondiente a Application Insights.

    Por ejemplo, supongamos que cuenta con una métrica que describe el número de elementos de un contenedor. Durante un período determinado, primero coloca tres elementos en el contenedor y seguidamente retira dos. En consecuencia, llamaría a 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 automáticamente.

  • Agregación. Al trabajar con métricas, las mediciones individuales pocas veces resultan de interés. En su lugar, es importante un resumen de lo que ha ocurrido durante un período de tiempo determinado. Los resúmenes de este tipo se denominan agregaciones.

    En el ejemplo anterior, la suma de las métricas agregadas del período correspondiente es de 1 y el recuento de los valores de las métricas es de 2. Al usar el enfoque de agregación, solo se invoca a TrackMetric una vez por período y se envían los valores agregados. Se recomienda este enfoque, ya que puede reducir significativamente los costos y la sobrecarga de rendimiento al enviar menos puntos de datos a Application Insights, a pesar de seguir recopilado toda la información pertinente.

Ejemplos de un solo valor

Para enviar un único valor de métrica:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Métricas personalizadas en Log Analytics

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

  • valueSum: suma de las medidas. Para obtener el valor medio, divídalo por valueCount.
  • valueCount: número de medidas que se agregaron en esta llamada a trackMetric(..).

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 de página web, se envían datos de telemetría de la vista de página de forma predeterminada cuando se carga cada pantalla o página. Sin embargo, puede cambiar el valor predeterminado para realizar el seguimiento de las vistas de páginas en momentos diferentes o adicionales. Por ejemplo, en una aplicación que muestra pestañas o paneles, quizás quiera realizar el 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 con las vistas de páginas, por lo que los gráficos de usuario y de sesión se activan cuando hay datos de telemetría de vistas de páginas.

Vistas de página personalizadas

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Si tiene varias fichas dentro de páginas HTML diferentes, puede especificar también la dirección URL:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

Cronometrar las vistas de página

De manera predeterminada, los tiempos notificados como Tiempo de carga de la vista de página se miden desde que el explorador envía la solicitud hasta que se llama al evento de carga de la página del explorador.

En su lugar, puede:

  • Establecer una duración explícita en la llamada trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Usar las llamadas para cronometrar la vista de página startTrackPage y stopTrackPage.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

El nombre que use como primer parámetro asocia las llamadas inicial y final. El valor predeterminado es el nombre de la página actual.

Las duraciones de carga de página resultantes que se muestran en el Explorador de métricas se derivan del intervalo que media entre las llamadas inicial y final. Depende del usuario qué intervalo se cronometra realmente.

Telemetría de páginas en Log Analytics

En Log Analytics hay dos tablas en las que se 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 que se tardan en procesar los datos entrantes.

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

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

Para descubrir la popularidad de los distintos exploradores:

pageViews
| summarize count() by client_Browser

Para asociar las vistas de página a las llamadas AJAX, realice una combinación con dependencias:

pageViews
| join (dependencies) on operation_Id

TrackRequest

El SDK del servidor utiliza TrackRequest para registrar las solicitudes HTTP.

También puede llamarlo usted mismo si quiere simular solicitudes en un contexto en el que no se está ejecutando el módulo de servicio web.

La forma recomendada de enviar datos de telemetría de solicitudes es que la solicitud actúe como un contexto de operación.

Contexto de operación

Puede correlacionar los elementos de telemetría juntos mediante su asociación con el contexto de la operación. El módulo de seguimiento de solicitud estándar realiza esta operación para excepciones y otros eventos enviados al procesar 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.

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

Al realizar el seguimiento de la telemetría manualmente, la forma más fácil de garantizar la correlación de los datos de telemetría es mediante el uso de este patrón:

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use 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.

Junto con la configuración de un contexto de la 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 cronometrado entre el inicio y la detención.

Los elementos de telemetría notificados dentro de un ámbito de operación se convierten en elementos secundarios de dicha operación. Los contextos de operación pueden estar anidados.

En la Búsqueda, el contexto de la operación se utiliza para crear la lista de elementos relacionados.

Captura de pantalla que muestra la lista de elementos relacionados.

Consulte Seguimiento de las operaciones personalizadas con el SDK de .NET para Application Insights para más información sobre el seguimiento de las operaciones personalizadas.

Solicitudes en Log Analytics

En Analytics de Application Insights, las solicitudes aparecen en la tabla requests.

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

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

TrackException

Enviar excepciones a Application Insights:

Los informes incluyen los seguimientos de la pila.

C#

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

Java

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

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Los SDK capturan muchas excepciones automáticamente, por lo que no siempre es necesario llamar explícitamente a TrackException:

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Excepciones en Log Analytics

En Analytics de Application Insights, las excepciones aparecen en la tabla exceptions.

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

exceptions
| summarize sum(itemCount) by type

La mayor parte de la información importante sobre pilas ya se extrajo en variables independientes, pero puede desmontar la estructura details para obtener más. 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.

En Java, el agente de Java para Application Insights recopila y envía registros automáticamente al portal.

C#

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

Java

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

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

JavaScript del lado cliente/explorador

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

Registre un evento de diagnóstico, como la entrada o la salida de un método.

Parámetro Descripción
message Datos de diagnóstico. Puede ser mucho más largo que un nombre.
properties Asignación de cadena a cadena. Datos adicionales que se usan 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 propiedades. Una ventaja de TrackTrace es que puede colocar datos relativamente largos en el mensaje. Por ejemplo, aquí puede codificar datos POST.

También puede agregar un nivel de gravedad al mensaje. Y, al igual que con otra telemetría, puede agregar valores de propiedad para ayudar a filtrar o buscar distintos conjuntos de seguimientos. Por ejemplo:

C#

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

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

En Búsqueda, puede filtrar fácilmente todos los mensajes de un determinado nivel de gravedad relativos a una determinada base de datos.

Seguimientos en Log Analytics

En Analytics de Application Insights, las llamadas a TrackTrace se muestran en la tabla traces.

Si el muestreo está en uso, en la propiedad itemCount se muestra un valor mayor que 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackTrace(), el proceso de muestreo solo transmite una. Para obtener un recuento correcto de las llamadas de seguimiento, utilice un código similar a traces | summarize sum(itemCount).

TrackDependency

Utilice la llamada a TrackDependency 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 se muestran en los gráficos de dependencia del portal. Es necesario agregar el fragmento de código siguiente siempre que se realice una llamada de dependencia.

Nota:

En el caso de .NET y .NET Core, también puede usar el método TelemetryClient.StartOperation (extensión) que rellena las propiedades DependencyTelemetry que son 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 de salida en Seguimiento de las operaciones personalizadas con el SDK de .NET para Application Insights.

C#

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

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

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

En Java, se puede realizar un seguimiento automático de muchas llamadas de dependencia mediante el agente de Java para Application Insights.

Utilizará esta llamada si desea hacer un seguimiento de las llamadas no captadas por el seguimiento automatizado.

Para desactivar el módulo de seguimiento de dependencias estándar en C#, edite ApplicationInsights.config y elimine la referencia a DependencyCollector.DependencyTrackingTelemetryModule. Para Java, consulte Supresión de la telemetría específica recopilada automáticamente.

Dependencias en Log Analytics

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

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

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 cuando el búfer está lleno (normalmente 500 elementos). En algunos casos, es posible que desee vaciar el búfer. Un ejemplo es si usa el SDK en una aplicación que se cierra.

.NET

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.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

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

Nota

Los SDK de Java y JavaScript se vacían automáticamente al cerrar la aplicación.

Usuarios autenticados

En una aplicación web, los usuarios se identifican mediante cookies de manera 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 su aplicación, puede obtener un recuento más preciso estableciendo el identificador del usuario autenticado en el código del explorador:

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

En una aplicación MVC web de ASP.NET, por ejemplo:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

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 está instalado el SDK del servidor, el identificador de usuario autenticado se envía como parte de las propiedades de contexto tanto de la telemetría del cliente como del servidor. A continuación, puede filtrar y buscar en ella.

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

appInsights.setAuthenticatedUserContext(validatedId, accountId);

En el Explorador de métricas, puede crear un gráfico que cuente los Usuarios autenticados y las Cuentas de usuario.

También puede buscar puntos de datos de cliente con cuentas y nombres de usuario 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 para JavaScript de Application Insights.

Cuando esta propiedad se establece en true, se imprime el nombre de usuario del usuario de ASP.NET Core junto con los datos de telemetría del lado cliente. Por este motivo, ya no sería necesario agregar appInsights.setAuthenticatedUserContext manualmente porque ya lo ha insertado el SDK para ASP.NET Core. El identificador de autenticación también se enviará al servidor en el que el SDK de .NET Core lo identificará y lo usará para cualquier telemetría del lado servidor, tal y como se describe en la referencia de la API de JavaScript.

Sin embargo, para las aplicaciones de JavaScript que no funcionan de la misma manera que ASP.NET Core MVC (como las aplicaciones web SPA), deberá agregar appInsights.setAuthenticatedUserContext manualmente.

Filtrado, búsqueda y segmentación de los datos mediante propiedades

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

propiedades son valores de cadena que se pueden usar para filtrar los datos de telemetría en los informes de uso. Por ejemplo, si su aplicación proporciona varios juegos, puede adjuntar el nombre del juego a cada evento para así poder ver cuáles son los juegos más populares.

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

métricas son valores numéricos que se pueden presentar de forma gráfica. Por ejemplo, puede que quiera ver si hay un aumento gradual en las puntuaciones que alcanzan sus jugadores. Los gráficos se pueden segmentar por las propiedades enviadas con el evento, para que pueda separar o apilar los gráficos de 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.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

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

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

Nota

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

Método alternativo para establecer propiedades y métricas

Si le resulta más cómodo, 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 vuelva a usar la misma instancia del elemento de telemetría (event en este ejemplo) para llamar a Track*() varias veces. Esta práctica puede hacer que se envíe la telemetría con una configuración incorrecta.

Medidas y propiedades personalizadas en Log Analytics

En Log Analytics, las métricas y propiedades personalizadas se muestran en los atributos customMeasurements 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)

Tenga en lo siguiente:

  • Al extraer un valor del código JSON customDimensions o customMeasurements, este tiene un tipo dinámico, por lo que debe convertirlo con tostring o todouble.
  • Para tener en cuenta la posibilidad del muestreo, debería usar sum(itemCount) y no count().

Eventos de temporización

Seguro que en ocasiones le gustaría representar el tiempo que se tarda en realizar alguna acción. Por ejemplo, puede que quiera 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.

C#

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

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

Propiedades predeterminadas para la telemetría personalizada

Si quiere establecer valores de propiedad predeterminados para algunos de los eventos personalizados que escriba, establézcalos en una instancia de TelemetryClient. Se adjuntarán a cada elemento de telemetría enviado desde ese cliente.

C#

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

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

Para los clientes web de JavaScript, use los inicializadores de telemetría de JavaScript.

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

Muestreo, filtrado y procesamiento de los datos de telemetría

Consulte Filtrar y preprocesar la telemetría en el SDK de Application Insights.

Deshabilitar la telemetría

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

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Para deshabilitar los recopiladores estándar seleccionados (por ejemplo, contadores de rendimiento, solicitudes HTTP o dependencias), elimine o convierta en comentarios las líneas correspondientes en el archivo ApplicationInsights.config. Un ejemplo es si quiere enviar sus propios datos de TrackRequest.

Node.js

telemetry.config.disableAppInsights = true;

Para deshabilitar los recopiladores estándar seleccionados (por ejemplo, los contadores de rendimiento, las solicitudes HTTP o las dependencias) en tiempo de inicialización, encadene métodos de configuración al código de inicialización del SDK.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Para deshabilitar estos recopiladores después de la inicialización, utilice el objeto de configuración: applicationInsights.Configuration.setAutoCollectRequests(false).

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 puede recibir otros mensajes que le ayuden a realizar el seguimiento de los posibles problemas con la telemetría. Desactívelo en producción, ya que puede ralentizar la aplicación.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Para Node.js, puede habilitar el modo de desarrollador habilitando el registro interno mediante setInternalLogging y estableciendo maxBatchSize en 0, lo que hace que la telemetría se envíe tan pronto como se recopile.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Establecimiento de la clave de instrumentación para datos de telemetría personalizados seleccionados

C#

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

Copia de la clave de instrumentación

Para evitar la mezcla de telemetría de entornos de desarrollo, pruebas y producción, puede crear recursos separados 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 de ASP.NET:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

En una página web, podría configurarla a partir del estado del servidor web, en lugar de codificarla literalmente en el script. Por ejemplo, en una página web generada en una aplicación ASP.NET:

JavaScript en Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient tiene la 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 los puede establecer usted mismo. Por ejemplo:

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

Si establece cualquiera de estos valores manualmente, considere la posibilidad de quitar la línea pertinente del archivo ApplicationInsights.config, de modo que no se confundan sus valores con los valores estándar.

  • Component: la aplicación y su versión.
  • Device: datos sobre el dispositivo donde se ejecuta la aplicación. En aplicaciones web, es el servidor o el dispositivo de 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 del archivo ApplicationInsights.config.
  • Ubicación: la ubicación geográfica del dispositivo.
  • Operation: en las aplicaciones web, es la solicitud HTTP actual. En otros tipos de aplicaciones, puede establecer este valor para agrupar eventos.
    • ID: valor generado que correlaciona distintos eventos, de modo que cuando inspeccione cualquier evento en Búsqueda de diagnóstico, pueda encontrar elementos relacionados.
    • Name: un identificador, generalmente la dirección URL de la solicitud HTTP.
    • SyntheticSource: si no es un valor nulo ni está vacío, esta cadena indica que el origen de la solicitud se ha identificado como un robot o una prueba web. De manera 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 cambia cuando el usuario lleva un tiempo sin estar activo.
  • Usuario: información del usuario.

límites

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.
Limitaciones 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 8192 8192 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
Retención de datos de Profiler e Instantánea 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 del generador de perfiles Sin límite Ilimitado.
Datos enviados de Instantánea por día 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 las cuotas, consulte Facturación de Application Insights.

Para evitar llegar al límite de velocidad de datos, utilice el muestreo.

Para determinar cuánto tiempo se conservan los datos, consulte el artículo sobre retención de datos y privacidad.

Documentos de referencia

Código del SDK

Preguntas más frecuentes

Esta sección proporciona respuestas a preguntas comunes.

¿Por qué me faltan datos de telemetría?

Los TelemetryChannels perderán la telemetría almacenada en búfer si no se vacía antes de que se cierre una aplicación.

Para evitar la pérdida de datos, vacíe TelemetryClient cuando se cierre una aplicación.

Para obtener más información, consulte Vaciado de datos.

¿Qué excepciones pueden generar las llamadas a Track_()?

Ninguno. No es necesario agruparlas en cláusulas try-catch. Si el SDK encuentra problemas, registrará los mensajes en la salida de la consola de depuración y, si los mensajes pasan, en la Búsqueda de diagnóstico.

¿Hay una API de REST para obtener datos desde el portal?

Sí, la API de acceso a datos. Otras formas de extraer datos incluyen Power BI, si ha migrado a un recurso basado en el área de trabajo, o una exportación continua si todavía está en un recurso clásico.

¿Por qué se omiten mis llamadas a las API de métricas y eventos personalizados?

El SDK de Application Insights no es compatible con la instrumentación automática. Si la instrumentación automática está habilitada, se omitirán las llamadas a Track() y otras API de métricas y eventos personalizados.

Desactive la instrumentación automática en Azure Portal de la pestaña Application Insights de la página App Service o establezca ApplicationInsightsAgent_EXTENSION_VERSION en disabled.

¿Por qué los recuentos de los gráficos de búsqueda y métrica no son iguales?

El muestreo reduce el número de elementos de telemetría (como solicitudes y eventos personalizados) que se envían desde su aplicación al portal. En el gráfico de búsqueda, ve el número de elementos recibidos. En los gráficos de métrica que muestran un recuento de eventos, ve el número de eventos originales que se han producido.

Cada elemento que se transmite lleva una propiedad itemCount que muestra cuántos eventos originales representa ese elemento. Para ver el muestreo en funcionamiento, puede ejecutar esta consulta en Log Analytics:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

¿Cómo puedo establecer una alerta sobre un evento?

Las alertas de Azure solo se establecen sobre métricas. Cree una métrica personalizada que cruce un umbral de valor cada vez que se produzca el evento. A continuación, establezca una alerta sobre la métrica. Recibirá una notificación cada vez que la métrica cruce el umbral en cualquier dirección. No recibirá una notificación hasta el primer cruce, independientemente de si el valor inicial es alto o bajo. Siempre hay una latencia de unos minutos.

Pasos siguientes