API de Application Insights para eventos y métricas personalizadosApplication Insights API for custom events and metrics

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.Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. Puede enviar datos de telemetría desde aplicaciones de escritorio y de dispositivo y desde clientes y servidores web.You can send telemetry from device and desktop apps, web clients, and web servers. Use la API de telemetría principal de Azure Application Insights para enviar métricas y eventos personalizados, así como sus propias versiones de telemetría estándar.Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. Esta API es la misma que usan los recopiladores de datos estándar de Application Insights.This API is the same API that the standard Application Insights data collectors use.

API summaryAPI summary

La API central es uniforme en todas las plataformas, excepto por algunas pequeñas variaciones como GetMetric (solo .NET).The core API is uniform across all platforms, apart from a few variations like GetMetric(.NET only).

MétodoMethod Se usa paraUsed for
TrackPageView Páginas, pantallas, hojas o formularios.Pages, screens, blades, or forms.
TrackEvent Acciones de usuario y otros eventos.User actions and other events. Se usa para realizar el seguimiento del comportamiento de los usuarios o para supervisar el rendimiento.Used to track user behavior or to monitor performance.
GetMetric Cero y métricas multidimensionales, agregación configurada de forma centralizada, solo en C#.Zero and multi-dimensional metrics, centrally configured aggregation, C# only.
TrackMetric Las medidas de rendimiento, como las longitudes de cola, no están relacionadas con eventos específicos.Performance measurements such as queue lengths not related to specific events.
TrackException Excepciones de registro para diagnóstico.Logging exceptions for diagnosis. Permite realizar el seguimiento del lugar donde se producen en relación con otros eventos y examinar los seguimientos de pila.Trace where they occur in relation to other events and examine stack traces.
TrackRequest Registro de la frecuencia y duración de las solicitudes de servidor para el análisis de rendimiento.Logging the frequency and duration of server requests for performance analysis.
TrackTrace Mensajes del registro de diagnóstico de recursos.Resource Diagnostic log messages. También puede capturar registros de terceros.You can also capture third-party logs.
TrackDependency Registro de la duración y frecuencia de las llamadas a componentes externos de los que depende la aplicación.Logging the duration and frequency of calls to external components that your app depends on.

Puede adjuntar propiedades y métricas a la mayoría de estas llamadas de telemetría.You can attach properties and metrics to most of these telemetry calls.

Antes de comenzarBefore you start

Si aún no tiene una referencia en el SDK de Application Insights:If you don't have a reference on Application Insights SDK yet:

Obtención de una instancia de TelemetryClientGet a TelemetryClient instance

Obtenga una instancia de TelemetryClient (excepto en JavaScript en páginas web):Get an instance of TelemetryClient (except in JavaScript in webpages):

En el caso de las aplicaciones ASP.NET Core y aplicaciones que no son HTTP o de trabajo para .NET/.NET Core, se recomienda obtener una instancia de TelemetryClient del contenedor de inserción de dependencias, tal como se explica en la documentación correspondiente.For ASP.NET Core apps and Non HTTP/Worker for .NET/.NET Core apps, it is recommended to get an instance of TelemetryClient from the dependency injection container as explained in their respective documentation.

Si usa AzureFunctions v2 o superior o Azure WebJobs v3 o superior, siga este documento: https://docs.microsoft.com/azure/azure-functions/functions-monitoring#version-2x-and-higherIf you use AzureFunctions v2+ or Azure WebJobs v3+ - follow this document: https://docs.microsoft.com/azure/azure-functions/functions-monitoring#version-2x-and-higher

C#C#

private TelemetryClient telemetry = new TelemetryClient();

Los usuarios que reciban mensajes que indiquen que el método está obsoleto pueden visitar microsoft/ApplicationInsights-dotnet#1152 para obtener más detalles.For anyone seeing this method is obsolete messages please visit microsoft/ApplicationInsights-dotnet#1152 for further details.

Visual BasicVisual Basic

Private Dim telemetry As New TelemetryClient

JavaJava

private TelemetryClient telemetry = new TelemetryClient();

Node.jsNode.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient es seguro para subprocesos.TelemetryClient is thread-safe.

Para proyectos ASP.NET y Java, las solicitudes HTTP entrantes se capturan automáticamente.For ASP.NET and Java projects, incoming HTTP Requests are automatically captured. Puede que quiera crear instancias adicionales de TelemetryClient para otro módulo de la aplicación.You might want to create additional instances of TelemetryClient for other module of your app. Por ejemplo, puede tener una instancia de TelemetryClient en la clase de middleware para notificar eventos de la lógica de negocios.For instance, you may have one TelemetryClient instance in your middleware class to report business logic events. Puede establecer propiedades como UserId y DeviceId para identificar la máquina.You can set properties such as UserId and DeviceId to identify the machine. Esta información se adjunta a todos los eventos enviados por la instancia.This information is attached to all events that the instance sends.

C#C#

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

JavaJava

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

En proyectos de Node.js, puede usar new applicationInsights.TelemetryClient(instrumentationKey?) para crear una nueva instancia, pero esto solo se recomienda para escenarios que requieren configuración aislada del singleton defaultClient.In Node.js projects, you can use new applicationInsights.TelemetryClient(instrumentationKey?) to create a new instance, but this is recommended only for scenarios that require isolated configuration from the singleton defaultClient.

TrackEventTrackEvent

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.In Application Insights, a custom event is a data point that you can display in Metrics Explorer as an aggregated count, and in Diagnostic Search as individual occurrences. (No está relacionado con MVC ni con "eventos" de otro marco).(It isn't related to MVC or other framework "events.")

Inserte llamadas a TrackEvent en el código para contabilizar diversos eventos:Insert TrackEvent calls in your code to count various events. la frecuencia con la que los usuarios eligen una determinada característica, con la que logran unos determinados objetivos o con la que cometen determinados tipos de errores.How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

Por ejemplo, en una aplicación de juego, envíe un evento cada vez que un usuario gane el juego:For example, in a game app, send an event whenever a user wins the game:

JavaScriptJavaScript

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

C#C#

telemetry.TrackEvent("WinGame");

Visual BasicVisual Basic

telemetry.TrackEvent("WinGame")

JavaJava

telemetry.trackEvent("WinGame");

Node.jsNode.js

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

Eventos personalizados en AnalyticsCustom events in Analytics

La telemetría está disponible en la tabla customEvents de Analytics de Application Insights.The telemetry is available in the customEvents table in Application Insights Analytics. Cada fila representa una llamada a trackEvent(..) en la aplicación.Each row represents a call to trackEvent(..) in your app.

Si el muestreo está en uso, en la propiedad itemCount se muestra un valor mayor que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackEvent(), el proceso de muestreo solo transmite una.For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. Para obtener un recuento correcto de eventos personalizados, debería usar código como customEvents | summarize sum(itemCount).To get a correct count of custom events, you should therefore use code such as customEvents | summarize sum(itemCount).

GetMetricGetMetric

Para obtener información sobre cómo usar eficazmente la llamada a GetMetric() para capturar métricas previamente agregadas de forma local para aplicaciones .NET y .NET Core, visite la documentación de GetMetric.To learn how to effectively use the GetMetric() call to capture locally pre-aggregated metrics for .NET and .NET Core applications visit the GetMetric documentation.

TrackMetricTrackMetric

Nota

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric no es el método preferido para el envío de métricas.Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is not the preferred method for sending metrics. Las métricas deben agregarse previamente siempre durante un tiempo antes de enviarse.Metrics should always be pre-aggregated across a time period before being sent. Use una de las sobrecargas GetMetric(..) para obtener un objeto de métrica para acceder a funcionalidades de agregación previa del SDK.Use one of the GetMetric(..) overloads to get a metric object for accessing SDK pre-aggregation capabilities. Si va a implementar su propia lógica de agregación previa, puede usar el método TrackMetric() para enviar los agregados resultantes.If you are implementing your own pre-aggregation logic, you can use the TrackMetric() method to send the resulting aggregates. Si su 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 en su caso haya que usar la telemetría de eventos; consulte TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).If your application requires sending a separate telemetry item at every occasion without aggregation across time, you likely have a use case for event telemetry; see TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights puede crear gráficos de métricas que no estén conectadas a eventos concretos.Application Insights can chart metrics that are not attached to particular events. Por ejemplo, puede supervisar una longitud de cola a intervalos regulares.For example, you could monitor a queue length at regular intervals. 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.With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Para enviar las métricas a Application Insights, puede usar la API TrackMetric(..).In order to send metrics to Application Insights, you can use the TrackMetric(..) API. Hay dos formas de enviar una métrica:There are two ways to send a metric:

  • Valor único.Single value. Cada vez que realiza una medición en la aplicación, envía el valor correspondiente a Application Insights.Every time you perform a measurement in your application, you send the corresponding value to Application Insights. Por ejemplo, suponga que cuenta con una métrica que describe el número de elementos de un contenedor.For example, assume that you have a metric describing the number of items in a container. Durante un período determinado, primero coloca tres elementos en el contenedor y seguidamente retira dos.During a particular time period, you first put three items into the container and then you remove two items. En consecuencia, llamaría a TrackMetric dos veces: la primera, para pasar el valor 3 y a continuación el valor -2.Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. Application Insights almacena ambos valores en su nombre.Application Insights stores both values on your behalf.

  • Agregación.Aggregation. Al trabajar con métricas, las mediciones individuales pocas veces resultan de interés.When working with metrics, every single measurement is rarely of interest. En su lugar, lo importante son los resúmenes de acontecimientos durante un período determinado.Instead a summary of what happened during a particular time period is important. Los resúmenes de este tipo se denominan agregaciones.Such a summary is called aggregation. 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.In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 2. Al usar el método de agregación, solo invocará TrackMetric una vez por período y enviará los valores agregados.When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. Este es el método que se recomienda usar, ya que puede reducir significativamente los costos y la sobrecarga de rendimiento gracias a que envía menos puntos de datos a Application Insights, a pesar de seguir recopilado toda la información pertinente.This is the recommended approach since it can significantly reduce the cost and performance overhead by sending fewer data points to Application Insights, while still collecting all relevant information.

EjemplosExamples

Valores únicosSingle values

Para enviar un único valor de métrica:To send a single metric value:

JavaScriptJavaScript

appInsights.trackMetric("queueLength", 42.0);

C#C#

var sample = new MetricTelemetry();
sample.Name = "metric name";
sample.Value = 42.3;
telemetryClient.TrackMetric(sample);

JavaJava

telemetry.trackMetric("queueLength", 42.0);

Node.jsNode.js

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

Métricas personalizadas en AnalyticsCustom metrics in Analytics

La telemetría está disponible en la tabla customMetrics de Analytics de Application Insights.The telemetry is available in the customMetrics table in Application Insights Analytics. Cada fila representa una llamada a trackMetric(..) en la aplicación.Each row represents a call to trackMetric(..) in your app.

  • valueSum: es la suma de las medidas.valueSum - This is the sum of the measurements. Para obtener el valor medio, divídalo por valueCount.To get the mean value, divide by valueCount.
  • valueCount: el número de medidas que se agregaron en esta llamada a trackMetric(..).valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

Vistas de páginaPage views

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.In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. Sin embargo, puede cambiar esta frecuencia para que se realice el seguimiento de las vistas de página en momentos diferentes o adicionales.But you can change that to track page views at additional or different times. Por ejemplo, en una aplicación que muestra pestañas u hojas, quizás quiera realizar el seguimiento de una página siempre que el usuario abra una nueva hoja.For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

Los datos de usuario y de sesión se envían como propiedades junto con las vistas de página, por lo que los gráficos de usuario y de sesión se activan cuando hay datos de telemetría de vistas de página.User and session data is sent as properties along with page views, so the user and session charts come alive when there is page view telemetry.

Vistas de página personalizadasCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

JavaJava

telemetry.trackPageView("GameReviewPage");

Si tiene varias fichas dentro de páginas HTML diferentes, puede especificar también la dirección URL:If you have several tabs within different HTML pages, you can specify the URL too:

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

Cronometrar las vistas de páginaTiming page views

De forma 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 página del explorador.By default, the times reported as Page view load time are measured from when the browser sends the request, until the browser's page load event is called.

En su lugar, puede:Instead, you can either:

  • Establecer una duración explícita en la llamada trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Usar las llamadas para cronometrar la vista de página startTrackPage y stopTrackPage.Use the page view timing calls startTrackPage and stopTrackPage.

JavaScriptJavaScript

// 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.The name that you use as the first parameter associates the start and stop calls. El valor predeterminado es el nombre de la página actual.It defaults to the current page name.

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.The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. Depende del usuario qué intervalo se cronometra realmente.It's up to you what interval you actually time.

Telemetría de páginas en AnalyticsPage telemetry in Analytics

En Analytics hay dos tablas en las que se muestran datos de operaciones de explorador:In Analytics two tables show data from browser operations:

  • La tabla pageViews contiene datos sobre la URL y el título de la página.The pageViews table contains data about the URL and page title
  • La tabla browserTimings contiene datos sobre el rendimiento del cliente, como el tiempo que se tarda en procesar los datos entrantes.The browserTimings table contains data about client performance, such as the time taken to process the incoming data

Para averiguar cuánto tarda el explorador en procesar diferentes páginas:To find how long the browser takes to process different pages:

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

Para descubrir la popularidad de distintos exploradores:To discover the popularities of different browsers:

pageViews
| summarize count() by client_Browser

Para asociar las vistas de página a las llamadas AJAX, realice una combinación con dependencias:To associate page views to AJAX calls, join with dependencies:

pageViews
| join (dependencies) on operation_Id 

TrackRequestTrackRequest

El SDK del servidor usa TrackRequest para registrar las solicitudes de HTTP.The server SDK uses TrackRequest to log HTTP requests.

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.You can also call it yourself if you want to simulate requests in a context where you don't have the web service module running.

Sin embargo, lo que se recomienda para enviar telemetría de solicitudes es que la solicitud actúe como contexto de operación.However, the recommended way to send request telemetry is where the request acts as an operation context.

Contexto de operaciónOperation context

Puede correlacionar los elementos de telemetría juntos mediante su asociación con el contexto de la operación.You can correlate telemetry items together by associating them with operation context. El módulo de seguimiento de solicitud estándar realiza esta operación para excepciones y otros eventos enviados al procesar una solicitud HTTP.The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. En Búsqueda y Análisis, puede encontrar fácilmente cualquier evento asociado a la solicitud mediante su identificador de operación.In Search and Analytics, you can easily find any events associated with the request using its operation ID.

Para más información sobre la correlación, vea Correlación de telemetría en Application Insights.See Telemetry correlation in Application Insights for more details on correlation.

Al realizar el seguimiento de la telemetría manualmente, la forma más fácil de garantizar la correlación de telemetría es mediante el uso de este patrón:When tracking telemetry manually, the easiest way to ensure telemetry correlation by using this pattern:

C#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.Along with setting an operation context, StartOperation creates a telemetry item of the type that you specify. Envía el elemento de telemetría al eliminar la operación, o si llama explícitamente a StopOperation.It sends the telemetry item when you dispose the operation, or if you explicitly call 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.If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

Los elementos de telemetría notificados dentro de un ámbito de operación se convierten en "elementos secundarios" de dicha operación.Telemetry items reported within a scope of operation become 'children' of such operation. Los contextos de operación pueden estar anidados.Operation contexts could be nested.

En la Búsqueda, el contexto de la operación se utiliza para crear la lista de Elementos relacionados:In Search, the operation context is used to create the Related Items list:

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.See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Solicitudes en AnalyticsRequests in Analytics

En Analytics de Application Insights, las solicitudes aparecen en la tabla requests.In Application Insights Analytics, requests show up in the requests table.

Si el muestreo está en uso, en la propiedad de itemCount se mostrará un valor superior a 1.If sampling is in operation, the itemCount property will show a value greater than 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackRequest(), el proceso de muestreo solo transmite una.For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. Para obtener un recuento correcto de solicitudes y la duración media segmentada por nombres de solicitudes, use código como el siguiente:To get a correct count of requests and average duration segmented by request names, use code such as:

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

TrackExceptionTrackException

Enviar excepciones a Application Insights:Send exceptions to Application Insights:

Los informes incluyen los seguimientos de la pila.The reports include the stack traces.

C#C#

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

JavaJava

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

JavaScriptJavaScript

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

Node.jsNode.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.The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

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

Excepciones en AnalyticsExceptions in Analytics

En Analytics de Application Insights, las excepciones aparecen en la tabla exceptions.In Application Insights Analytics, exceptions show up in the exceptions table.

Si el muestreo está en uso, en la propiedad itemCount se muestra un valor mayor que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackException(), el proceso de muestreo solo transmite una.For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. Para obtener un recuento correcto de excepciones segmentadas por tipo de excepción, use código como el siguiente:To get a correct count of exceptions segmented by type of exception, use code such as:

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.Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. Puesto que se trata de una estructura dinámica, debería convertir el resultado al tipo que espere.Since this structure is dynamic, you should cast the result to the type you expect. Por ejemplo:For example:

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

Para asociar las excepciones a sus respectivas solicitudes, use una combinación:To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id

TrackTraceTrackTrace

Use TrackTrace para ayudar a diagnosticar problemas mediante el envío de una ''ruta de exploración'' a Application Insights.Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. Puede enviar fragmentos de datos de diagnóstico e inspeccionarlos en Búsqueda de diagnóstico.You can send chunks of diagnostic data and inspect them in Diagnostic Search.

Los adaptadores de registro de .NET usan esta API para enviar registros de terceros al portal.In .NET Log adapters use this API to send third-party logs to the portal.

En Java, para registradores estándar como Log4J o Logback, utilice los appenders de Log4j o Logback de Application Insights para enviar registros de terceros al portal.In Java for Standard loggers like Log4J, Logback use Application Insights Log4j or Logback Appenders to send third-party logs to the portal.

C#C#

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

JavaJava

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

Node.jsNode.js

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

JavaScript del lado cliente/exploradorClient/Browser-side JavaScript

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

Registre un evento de diagnóstico, como la entrada o la salida de un método.Log a diagnostic event such as entering or leaving a method.

ParámetroParameter DescripciónDescription
message Datos de diagnóstico.Diagnostic data. Puede ser mucho más largo que un nombre.Can be much longer than a name.
properties Asignación de cadena a cadena: Datos adicionales que se usan para filtrar excepciones en el portal.Map of string to string: Additional data used to filter exceptions in the portal. El valor predeterminado es vacío.Defaults to empty.
severityLevel Valores admitidos: SeverityLevel.tsSupported values: SeverityLevel.ts

Puede buscar en el contenido del mensaje, pero (a diferencia de los valores de propiedad) no puede filtrar por él.You can search on message content, but (unlike property values) you can't filter on it.

El límite de tamaño en message es mucho mayor que el límite en propiedades.The size limit on message is much higher than the limit on properties. Una ventaja de TrackTrace es que puede colocar datos relativamente largos en el mensaje.An advantage of TrackTrace is that you can put relatively long data in the message. Por ejemplo, aquí puede codificar datos POST.For example, you can encode POST data there.

Además, puede agregar un nivel de gravedad al mensaje.In addition, you can add a severity level to your message. Y, al igual que con otra telemetría, puede agregar valores de propiedad para ayudar a filtrar o buscar distintos conjuntos de seguimientos.And, like other telemetry, you can add property values to help you filter or search for different sets of traces. Por ejemplo:For example:

C#C#

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

JavaJava

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.In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Seguimientos en AnalyticsTraces in Analytics

En Analytics de Application Insights, las llamadas a TrackTrace aparecen en la tabla traces.In Application Insights Analytics, calls to TrackTrace show up in the traces table.

Si el muestreo está en uso, en la propiedad itemCount se muestra un valor mayor que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackTrace(), el proceso de muestreo solo transmite una.For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. Para obtener un recuento correcto de llamadas de seguimiento, debería codificar por tanto como traces | summarize sum(itemCount).To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependencyTrackDependency

Utilice la llamada de 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.Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. Los resultados se muestran en los gráficos de dependencia del portal.The results appear in the dependency charts in the portal. Es necesario agregar el fragmento de código siguiente siempre que se realice una llamada de dependencia.The code snippet below needs to be added wherever a dependency call is made.

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

JavaJava

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);
    RemoteDependencyTelemetry.setTimeStamp(startTime);
    RemoteDependencyTelemetry.trackDependency(dependencyTelemetry);
}

Node.jsNode.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 dependencia que detecta y realiza automáticamente el seguimiento de ciertas llamadas de dependencia; por ejemplo, a bases de datos y API de REST.Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. Debe instalar un agente en el servidor para que el módulo funcione.You have to install an agent on your server to make the module work.

En Java, es posible realizar el seguimiento de ciertas llamadas de dependencia automáticamente mediante el agente de Java.In Java, certain dependency calls can be automatically tracked using Java Agent.

Utilizará esta llamada si desea hacer un seguimiento de las llamadas no captadas por el seguimiento automatizado, o bien si no desea instalar el agente.You use this call if you want to track calls that the automated tracking doesn't catch, or if you don't want to install the agent.

Para desactivar el módulo de seguimiento de dependencias estándar en C#, edite ApplicationInsights.config y elimine la referencia a DependencyCollector.DependencyTrackingTelemetryModule.To turn off the standard dependency-tracking module in C#, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule. En Java, no instale al agente de Java si no quiere recopilar dependencias estándar automáticamente.In Java, please do not install java agent if you do not want to collect standard dependencies automatically.

Dependencias en AnalyticsDependencies in Analytics

En Analytics de Application Insights, las llamadas de trackDependency aparecen en la tabla dependencies.In Application Insights Analytics, trackDependency calls show up in the dependencies table.

Si el muestreo está en uso, en la propiedad itemCount se muestra un valor mayor que 1.If sampling is in operation, the itemCount property shows a value greater than 1. Por ejemplo, itemCount==10 significa que de cada 10 llamadas a trackDependency(), el proceso de muestreo solo transmite una.For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. Para obtener un recuento correcto de dependencias segmentadas por componente de destino, use código como el siguiente:To get a correct count of dependencies segmented by target component, use code such as:

dependencies
| summarize sum(itemCount) by target

Para asociar las dependencias a sus respectivas solicitudes, use una combinación:To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id

Datos de vaciadoFlushing data

Normalmente, el SDK envía datos a intervalos fijos (normalmente 30 segundos) o cuando el búfer está lleno (normalmente 500 elementos).Normally, the SDK sends data at fixed intervals (typically 30 secs) or whenever buffer is full (typically 500 items). Sin embargo, en algunos casos puede que desee vaciar el búfer: por ejemplo, si usa el SDK en una aplicación que se apaga.However, in some cases, you might want to flush the buffer--for example, if you are using the SDK in an application that shuts down.

C#C#

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

JavaJava

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

Node.jsNode.js

telemetry.flush();

La función es asincrónica para el canal de telemetría del servidor.The function is asynchronous for the server telemetry channel.

Lo ideal es que se utilice el método flush() en la actividad de cierre de la aplicación.Ideally, flush() method should be used in the shutdown activity of the Application.

Usuarios autenticadosAuthenticated users

En una aplicación web, los usuarios se identifican por cookies (de manera predeterminada).In a web app, users are (by default) identified by cookies. 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.A user might be counted more than once if they access your app from a different machine or browser, or if they delete 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:If users sign in to your app, you can get a more accurate count by setting the authenticated user ID in the browser code:

JavaScriptJavaScript

// 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:In an ASP.NET web MVC application, for example:

RazorRazor

@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.It isn't necessary to use the user's actual sign-in name. Solo tiene que ser un identificador único para ese usuario.It only has to be an ID that is unique to that user. No debe incluir espacios ni ninguno de los caracteres ,;=|.It must not include spaces or any of the characters ,;=|.

El identificador de usuario también se establece en una cookie de sesión y se envía al servidor.The user ID is also set in a session cookie and sent to the server. 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.If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. A continuación, puede filtrar y buscar en ella.You can then filter and search on it.

Si su aplicación agrupa a los usuarios en cuentas, también puede pasar un identificador de la cuenta (con las mismas restricciones de caracteres).If your app groups users into accounts, you can also pass an identifier for the account (with the same character restrictions).

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.In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

También puede Buscar puntos de datos de cliente con cuentas y nombres de usuario específicos.You can also Search for client data points with specific user names and accounts.

Filtrado, búsqueda y segmentación de los datos mediante el uso de propiedadesFiltering, searching, and segmenting your data by using properties

Puede asociar propiedades y medidas a los eventos (y también a las métricas, vistas de página, excepciones y otros datos de telemetría).You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

propiedades son valores de cadena que se pueden usar para filtrar los datos de telemetría en los informes de uso.Properties are string values that you can use to filter your telemetry in the usage reports. 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.For example, if your app provides several games, you can attach the name of the game to each event so that you can see which games are more popular.

Hay un límite de aproximadamente 8192 en la longitud de cadena.There's a limit of 8192 on the string length. (Si quiere enviar fragmentos grandes de datos, use el parámetro de mensaje de TrackTrace).(If you want to send large chunks of data, use the message parameter of TrackTrace.)

métricas son valores numéricos que se pueden presentar de forma gráfica.Metrics are numeric values that can be presented graphically. Por ejemplo, puede que quiera ver si hay un aumento gradual en las puntuaciones que alcanzan sus jugadores.For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. Los gráficos se pueden segmentar por las propiedades enviadas con el evento, así que puede separar o apilar los gráficos para diferentes juegos.The graphs can be segmented by the properties that are sent with the event, so that you can get separate or stacked graphs for different games.

Para que valores de métricas se muestren correctamente, deben ser mayores o iguales que 0.For metric values to be correctly displayed, they should be greater than or equal to 0.

Hay algunos límites en el número de propiedades, valores de propiedad y métricas que puede usar.There are some limits on the number of properties, property values, and metrics that you can use.

JavaScriptJavaScript

appInsights.trackEvent
    ("WinGame",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

appInsights.trackPageView
    ("page name", "http://fabrikam.com/pageurl.html",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

C#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.jsNode.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 BasicVisual 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)

JavaJava

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

Tenga cuidado de no registrar información de identificación personal en las propiedades.Take care not to log personally identifiable information in properties.

Método alternativo para establecer propiedades y métricasAlternative way to set properties and metrics

Si le resulta más cómodo, puede recopilar los parámetros de un evento en un objeto independiente:If it's more convenient, you can collect the parameters of an event in a separate object:

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 de elemento de telemetría (event en este ejemplo) para llamar a Track*() varias veces.Don't reuse the same telemetry item instance (event in this example) to call Track*() multiple times. Esto puede hacer que se envíe la telemetría con una configuración incorrecta.This may cause telemetry to be sent with incorrect configuration.

Mediciones y propiedades personalizadas en AnalyticsCustom measurements and properties in Analytics

En Analytics, las métricas y propiedades personalizadas aparecen en los atributos customMeasurements y customDimensions de cada registro de telemetría.In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

Por ejemplo, si agregó 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":For example, if you have added a property named "game" to your request telemetry, this query counts the occurrences of different values of "game", and show the average of the custom metric "score":

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

Tenga en lo siguiente:Notice that:

  • Al extraer un valor de los elementos de JSON customDimensions o customMeasurements, es de tipo dinámico, por lo que debe convertirlo a tostring o todouble.When you extract a value from the customDimensions or customMeasurements JSON, it has dynamic type, and so you must cast it tostring or todouble.
  • Para tener en cuenta la posibilidad de muestreo, debería usar sum(itemCount), no count().To take account of the possibility of sampling, you should use sum(itemCount), not count().

Eventos de temporizaciónTiming events

Seguro que en ocasiones le gustaría representar el tiempo que se tarda en realizar alguna acción.Sometimes you want to chart how long it takes to perform an action. Por ejemplo, puede que quiera saber cuánto tiempo tardan los usuarios en considerar las opciones de un juego.For example, you might want to know how long users take to consider choices in a game. Puede usar el parámetro de medida para ello.You can use the measurement parameter for this.

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

JavaJava

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 personalizadaDefault properties for custom telemetry

Si quiere establecer valores de propiedad predeterminados para algunos de los eventos personalizados que escriba, puede hacerlo en una instancia de TelemetryClient.If you want to set default property values for some of the custom events that you write, you can set them in a TelemetryClient instance. Se adjuntarán a cada elemento de telemetría enviado desde ese cliente.They are attached to every telemetry item that's sent from that client.

C#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 BasicVisual 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")

JavaJava

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.jsNode.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.Individual telemetry calls can override the default values in their property dictionaries.

Para los clientes web de JavaScript, use los inicializadores de telemetría de JavaScript.For JavaScript web clients, use JavaScript telemetry initializers.

Para agregar propiedades a toda la telemetría, incluidos los datos de los módulos de recopilación estándar, implemente ITelemetryInitializer.To add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

Muestreo, filtrado y procesamiento de telemetríaSampling, filtering, and processing telemetry

Puede escribir código para procesar la telemetría antes de que se envíe desde el SDK.You can write code to process your telemetry before it's sent from the SDK. El procesamiento incluye los datos enviados desde los módulos de telemetría estándar, como la recopilación de solicitudes HTTP y de dependencias.The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

Agregue propiedades a la telemetría mediante la implementación de ITelemetryInitializer.Add properties to telemetry by implementing ITelemetryInitializer. Por ejemplo, puede agregar números de versión o valores calculados a partir de otras propiedades.For example, you can add version numbers or values that are calculated from other properties.

El filtrado puede modificar o descartar la telemetría antes de que se envíe desde el SDK, mediante la implementación de ITelemetryProcessor.Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcessor. Puede controlar qué se envía y qué se descarta, pero debe tener en cuenta el efecto en las métricas.You control what is sent or discarded, but you have to account for the effect on your metrics. Según la forma en que se descarten los elementos, podría perder la capacidad de navegar entre elementos relacionados.Depending on how you discard items, you might lose the ability to navigate between related items.

El muestreo es una solución empaquetada para reducir el volumen de datos enviado desde la aplicación al portal.Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. Lo hace sin que las métricas mostradas resulten afectadas.It does so without affecting the displayed metrics. Y sin repercutir tampoco sobre capacidad para diagnosticar problemas navegando entre elementos relacionados, como excepciones, solicitudes y vistas de página.And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

Más información.Learn more.

Deshabilitación de la telemetríaDisabling telemetry

Para iniciar y detener dinámicamente la recopilación y la transmisión de telemetría:To dynamically stop and start the collection and transmission of telemetry:

C#C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

JavaJava

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 ApplicationInsights.config. Puede hacer esto, por ejemplo, si quiere enviar sus propios datos de TrackRequest.To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--delete or comment out the relevant lines in ApplicationInsights.config. You can do this, for example, if you want to send your own TrackRequest data.

Node.jsNode.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 el tiempo de inicialización, encadene métodos de configuración a su código de inicialización de SDK:To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--at initialization time, chain configuration methods to your SDK initialization code:

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)To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

Modo de programadorDeveloper mode

Durante la depuración, resulta útil enviar los datos de telemetría por la canalización para así poder ver los resultados inmediatamente.During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. También puede recibir mensajes adicionales que le ayuden a realizar el seguimiento de los posibles problemas con la telemetría.You also get additional messages that help you trace any problems with the telemetry. Desactívelo en producción, ya que puede ralentizar la aplicación.Switch it off in production, because it may slow down your app.

C#C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual BasicVisual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.jsNode.js

Para Node.js, puede habilitar el modo de desarrollador habilitando el registro interno a través de setInternalLogging y estableciendo maxBatchSize en 0, lo que hace que la telemetría se envíe tan pronto como se recopile.For Node.js, you can enable developer mode by enabling internal logging via setInternalLogging and setting maxBatchSize to 0, which causes your telemetry to be sent as soon as it is collected.

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 seleccionadosSetting the instrumentation key for selected custom telemetry

C#C#

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

Copia de la clave de instrumentaciónDynamic instrumentation key

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.To avoid mixing up telemetry from development, test, and production environments, you can create separate Application Insights resources and change their keys, depending on the environment.

En lugar de obtener la clave de instrumentación del archivo de configuración, puede establecerla en el código.Instead of getting the instrumentation key from the configuration file, you can set it in your code. Establezca la clave en un método de inicialización, como global.aspx.cs en un servicio de ASP.NET:Set the key in an initialization method, such as global.aspx.cs in an ASP.NET service:

C#C#

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

JavaScriptJavaScript

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.In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. Por ejemplo, en una página web generada en una aplicación ASP.NET:For example, in a webpage generated in an ASP.NET app:

JavaScript en RazorJavaScript in 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);
    }

TelemetryContextTelemetryContext

TelemetryClient tiene una propiedad de Context, que contiene valores que se envían junto con todos los datos de telemetría.TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. Normalmente, se establecen mediante los módulos de telemetría estándar, pero también los puede establecer usted mismo.They are normally set by the standard telemetry modules, but you can also set them yourself. Por ejemplo:For example:

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

Si establece cualquiera de estos valores manualmente, considere la posibilidad de quitar la línea pertinente de ApplicationInsights.config, de modo que no se confundan sus valores con los valores estándar.If you set any of these values yourself, consider removing the relevant line from ApplicationInsights.config, so that your values and the standard values don't get confused.

  • Component: la aplicación y su versión.Component: The app and its version.
  • Device: datos sobre el dispositivo donde se ejecuta la aplicación.Device: Data about the device where the app is running. (En aplicaciones web, se trata del servidor o el dispositivo de cliente desde el que se envía la telemetría).(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey: el recurso de Application Insights en Azure donde aparece la telemetría.InstrumentationKey: The Application Insights resource in Azure where the telemetry appears. Normalmente, se selecciona de ApplicationInsights.config.It's usually picked up from ApplicationInsights.config.
  • Ubicación: la ubicación geográfica del dispositivo.Location: The geographic location of the device.
  • Operation: en las aplicaciones web, es la solicitud HTTP actual.Operation: In web apps, the current HTTP request. En otros tipos de aplicaciones, puede establecer este valor para agrupar los eventos juntos.In other app types, you can set this to group events together.
    • Identificador: valor generado que correlaciona distintos eventos, de modo que cuando usted inspeccione cualquier evento en Búsqueda de diagnóstico, puede encontrar elementos relacionados.ID: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • Name: un identificador, generalmente la dirección URL de la solicitud HTTP.Name: An identifier, usually the URL of the HTTP request.
    • 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.SyntheticSource: If not null or empty, a string that indicates that the source of the request has been identified as a robot or web test. De forma predeterminada, se excluye de cálculos en el Explorador de métricas.By default, it is excluded from calculations in Metrics Explorer.
  • Propiedades: propiedades que se envían con todos los datos de telemetría.Properties: Properties that are sent with all telemetry data. Se pueden invalidar en llamadas de seguimiento* individuales.It can be overridden in individual Track* calls.
  • Sesión: sesión del usuario.Session: The user's session. El identificador se establece en un valor generado, que cambia cuando el usuario lleva un tiempo sin estar activo.The ID is set to a generated value, which is changed when the user has not been active for a while.
  • Usuario: información del usuario.User: User information.

límitesLimits

Hay algunos límites en el número de métricas y eventos por aplicación; es decir, por clave de instrumentación.There are some limits on the number of metrics and events per application, that is, per instrumentation key. Los límites dependen del plan de precios que elija.Limits depend on the pricing plan that you choose.

ResourceResource Límite predeterminadoDefault limit Nota:Note
Total de datos por díaTotal data per day 100 GB100 GB Se pueden reducir los datos si se establece un límite.You can reduce data by setting a cap. Si necesita más datos, puede aumentar el límite en el portal, hasta 1000 GB.If you need more data, you can increase the limit in the portal, up to 1,000 GB. Para capacidades mayores de 1000 GB, envíe un correo electrónico a AIDataCap@microsoft.com.For capacities greater than 1,000 GB, send email to AIDataCap@microsoft.com.
LimitacionesThrottling 32 000 eventos por segundo32,000 events/second El límite se mide por minuto.The limit is measured over a minute.
Retención de datosData retention Entre 30 y 730 días30 - 730 days Este recurso es para Search, Analytics y el Explorador de métricas.This resource is for Search, Analytics, and Metrics Explorer.
Retención de resultados detallados para la prueba de disponibilidad de varios pasosAvailability multi-step test detailed results retention 90 días90 days Este recurso proporciona resultados detallados de cada paso.This resource provides detailed results of each step.
Tamaño máximo de elementos de telemetríaMaximum telemetry item size 64 KB64 kB
Número máximo de elementos de telemetría por loteMaximum telemetry items per batch 64 K64 K
Longitud de nombres de propiedades y métricasProperty and metric name length 150150 Consulte esquemas de tipos.See type schemas.
Longitud de cadena del valor de propiedadProperty value string length 81928,192 Consulte esquemas de tipos.See type schemas.
Longitud del mensaje de seguimiento y excepciónTrace and exception message length 32 76832,768 Consulte esquemas de tipos.See type schemas.
Número de pruebas de disponibilidad por aplicaciónAvailability tests count per app 100100
Retención de datos del generador de perfilesProfiler data retention 5 días5 days
Datos enviados por día del generador de perfilesProfiler data sent per day 10 GB10 GB

Para más información, consulte Administración de precios y cuotas para Application Insights.For more information, see About pricing and quotas in Application Insights.

Para evitar llegar al límite de velocidad de datos, utilice el muestreo.To avoid hitting the data rate limit, use sampling.

Para determinar cuánto tiempo se conservan los datos, consulte el artículo sobre retención de datos y privacidad.To determine how long data is kept, see Data retention and privacy.

Documentos de referenciaReference docs

Código del SDKSDK code

PreguntasQuestions

  • ¿Qué excepciones pueden iniciar las llamadas de seguimiento_()?What exceptions might Track_() calls throw?

    Ninguno.None. No es necesario agruparlas en cláusulas try-catch.You don't need to wrap them in try-catch clauses. 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.If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • ¿Hay una API de REST para obtener datos desde el portal?Is there a REST API to get data from the portal?

    Sí, la API de acceso a datos.Yes, the data access API. Otras maneras de extraer datos son exportar desde Analytics a Power BI y la exportación continua.Other ways to extract data include export from Analytics to Power BI and continuous export.

Pasos siguientesNext steps