Correlación de Telemetría en Application InsightsTelemetry correlation in Application Insights

En el mundo de los microservicios, todas las operaciones lógicas requieren que el trabajo se realice en diversos componentes del servicio.In the world of microservices, every logical operation requires work to be done in various components of the service. Puede supervisar cada uno de estos componentes por separado mediante Application Insights.You can monitor each of these components separately by using Application Insights. Application Insights admite la correlación de telemetría distribuida, que se usa para detectar el componente que es responsable de los errores o de una degradación del rendimiento.Application Insights supports distributed telemetry correlation, which you use to detect which component is responsible for failures or performance degradation.

Este artículo explica el modelo de datos utilizado por Application Insights para poner en correlación la telemetría enviada por varios componentes.This article explains the data model used by Application Insights to correlate telemetry sent by multiple components. También se explican los protocolos y las técnicas de propagación contextual,It covers context-propagation techniques and protocols. así como la implementación de tácticas de correlación en distintos lenguajes y plataformas.It also covers the implementation of correlation tactics on different languages and platforms.

Modelo de datos de correlación de telemetríaData model for telemetry correlation

Application Insights define el modelo de datos para la correlación de telemetría distribuida.Application Insights defines a data model for distributed telemetry correlation. Para asociar la telemetría con una operación lógica, todos los elementos de telemetría tienen el campo de contexto denominado operation_Id.To associate telemetry with a logical operation, every telemetry item has a context field called operation_Id. Todos los elementos de telemetría comparten este identificador en el seguimiento distribuido.This identifier is shared by every telemetry item in the distributed trace. De este modo, aun si pierde telemetría desde una sola capa, se pueden seguir asociando los datos telemétricos notificados por otros componentes.So even if you lose telemetry from a single layer, you can still associate telemetry reported by other components.

Habitualmente, una operación lógica distribuida consta de un conjunto de operaciones más pequeñas, que son solicitudes que se procesan en uno de los componentes.A distributed logical operation typically consists of a set of smaller operations that are requests processed by one of the components. Estas operaciones se definen mediante telemetría de solicitudes.These operations are defined by request telemetry. Cada elemento de telemetría de solicitudes cuenta con su propio id, que lo identifica de manera global e inequívoca.Every request telemetry item has its own id that identifies it uniquely and globally. Además, todos los elementos de telemetría (como los seguimientos y las excepciones) que están asociados a la solicitud deben establecer operation_parentId en el valor de la solicitud id.And all telemetry items (such as traces and exceptions) that are associated with the request should set the operation_parentId to the value of the request id.

La telemetría de dependencias representa a todas las operaciones salientes, como una llamada HTTP a otro componente.Every outgoing operation, such as an HTTP call to another component, is represented by dependency telemetry. La telemetría de dependencia también define su propio id, que es globalmente único.Dependency telemetry also defines its own id that's globally unique. La telemetría de solicitudes, que se inicia mediante esta llamada de dependencia, utiliza este id como su operation_parentId.Request telemetry, initiated by this dependency call, uses this id as its operation_parentId.

Puede crear una vista de la operación lógica distribuida usando operation_Id, operation_parentId y request.id con dependency.id.You can build a view of the distributed logical operation by using operation_Id, operation_parentId, and request.id with dependency.id. Estos campos también definen el orden de causalidad de las llamadas de telemetría.These fields also define the causality order of telemetry calls.

En el entorno de los microservicios, los seguimientos de componentes pueden ir a distintos elementos de almacenamiento.In a microservices environment, traces from components can go to different storage items. Cada componente puede tener su propia clave de instrumentación en Application Insights.Every component can have its own instrumentation key in Application Insights. Para obtener la telemetría de la operación lógica, Application Insights consulta los datos de cada elemento de almacenamiento.To get telemetry for the logical operation, Application Insights queries data from every storage item. Si el número de elementos de almacenamiento es grande, necesitará una pista para saber dónde debe mirar a continuación.When the number of storage items is large, you'll need a hint about where to look next. El modelo de datos de Application Insights define dos campos, request.source y dependency.target, para solucionar este problema.The Application Insights data model defines two fields to solve this problem: request.source and dependency.target. El primer campo identifica el componente que inició la solicitud de dependencia.The first field identifies the component that initiated the dependency request. El segundo campo identifica qué componente devolvió la respuesta de la llamada de dependencia.The second field identifies which component returned the response of the dependency call.

EjemploExample

Veamos un ejemplo.Let's look at an example. Una aplicación llamada Stock Prices muestra el precio de mercado actual de una acción mediante una API externa denominada Stock.An application called Stock Prices shows the current market price of a stock by using an external API called Stock. La aplicación Stock Prices tiene una página llamada Stock page que el explorador web del cliente abre mediante GET /Home/Stock.The Stock Prices application has a page called Stock page that the client web browser opens by using GET /Home/Stock. La aplicación consulta la API Stick mediante el uso de una llamada HTTP GET /api/stock/value.The application queries the Stock API by using the HTTP call GET /api/stock/value.

Puede analizar la telemetría resultante ejecutando una consulta:You can analyze the resulting telemetry by running a query:

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

En los resultados, observe que todos los elementos de telemetría comparten la raíz operation_Id.In the results, note that all telemetry items share the root operation_Id. Cuando se realiza una llamada Ajax desde la página, se asigna un nuevo identificador único (qJSXU) a la telemetría de dependencia y el identificador de pageView se usa como operation_ParentId.When an Ajax call is made from the page, a new unique ID (qJSXU) is assigned to the dependency telemetry, and the ID of the pageView is used as operation_ParentId. La solicitud al servidor utiliza después el identificador de Ajax como operation_ParentId.The server request then uses the Ajax ID as operation_ParentId.

itemTypeitemType namename idID operation_ParentIdoperation_ParentId operation_Idoperation_Id
pageViewpageView Stock pageStock page STYzSTYz STYzSTYz
dependencydependency GET /Home/StockGET /Home/Stock qJSXUqJSXU STYzSTYz STYzSTYz
requestrequest GET Home/StockGET Home/Stock KqKwlrSt9PA=KqKwlrSt9PA= qJSXUqJSXU STYzSTYz
dependencydependency GET /api/stock/valueGET /api/stock/value bBrf2L7mm2g=bBrf2L7mm2g= KqKwlrSt9PA=KqKwlrSt9PA= STYzSTYz

Cuando se realiza la llamada GET /api/stock/value a un servicio externo, necesita conocer la identidad de ese servidor para poder establecer el campo dependency.target correctamente.When the call GET /api/stock/value is made to an external service, you need to know the identity of that server so you can set the dependency.target field appropriately. Si el servicio externo no admite la supervisión, target se establece en el nombre de host del servicio (por ejemplo, stock-prices-api.com).When the external service doesn't support monitoring, target is set to the host name of the service (for example, stock-prices-api.com). Pero si ese servicio se identifica devolviendo un encabezado HTTP predefinido, target contiene la identidad de servicio que permite a Application Insights crear un seguimiento distribuido consultando la telemetría de ese servicio.But if the service identifies itself by returning a predefined HTTP header, target contains the service identity that allows Application Insights to build a distributed trace by querying telemetry from that service.

Encabezados de correlación mediante W3C Trace-ContextCorrelation headers using W3C TraceContext

Application Insights está realizando la transición a W3C Trace-Context, que define:Application Insights is transitioning to W3C Trace-Context, which defines:

  • traceparent: lleva el identificador único global de la operación y un identificador único de la llamada.traceparent: Carries the globally unique operation ID and unique identifier of the call.
  • tracestate: lleva el contexto de seguimiento específico del sistema.tracestate: Carries system-specific tracing context.

La versión más reciente del SDK de Application Insights es compatible con el protocolo de Trace-Context, pero es posible que tenga que usarlo.The latest version of the Application Insights SDK supports the Trace-Context protocol, but you might need to opt in to it. (Se mantendrá la compatibilidad con el antiguo protocolo de correlación compatible con el SDK de Application Insights).(Backward compatibility with the previous correlation protocol supported by the Application Insights SDK will be maintained.)

El protocolo HTTP de correlación , también denominado Request-Id, está entrando en desuso.The correlation HTTP protocol, also called Request-Id, is being deprecated. Este protocolo define dos encabezados:This protocol defines two headers:

  • Request-Id: lleva el identificador único global de la llamada.Request-Id: Carries the globally unique ID of the call.
  • Correlation-Context: lleva la colección de pares nombre-valor de las propiedades del seguimiento distribuido.Correlation-Context: Carries the name-value pairs collection of the distributed trace properties.

Application Insights también define la extensión del protocolo HTTP de correlación.Application Insights also defines the extension for the correlation HTTP protocol. Usa pares nombre-valor Request-Context para propagar la colección de propiedades utilizadas por el autor o el destinatario de la llamada.It uses Request-Context name-value pairs to propagate the collection of properties used by the immediate caller or callee. El SDK de Application Insights usa este encabezado para establecer los campos dependency.target y request.source.The Application Insights SDK uses this header to set the dependency.target and request.source fields.

W3C Trace-Context y los modelos de datos de Application Insights se asignan de la siguiente manera:The W3C Trace-Context and Application Insights data models map in the following way:

Application InsightsApplication Insights W3C TraceContextW3C TraceContext
Id de Request y DependencyId of Request and Dependency parent-idparent-id
Operation_Id trace-idtrace-id
Operation_ParentId parent-id del intervalo primario de este intervalo.parent-id of this span's parent span. Si se trata de un intervalo raíz, este campo debe estar vacío.If this is a root span, then this field must be empty.

Para más información, consulte Modelo de datos de telemetría de Application Insights.For more information, see Application Insights telemetry data model.

Habilitación de la compatibilidad con el seguimiento distribuido de W3C para aplicaciones .NETEnable W3C distributed tracing support for .NET apps

El seguimiento distribuido basado en W3C Trace-Context está habilitado de forma predeterminada en todos los SDK de .NET Framework/.NET Core recientes, junto con la compatibilidad con versiones anteriores con el protocolo heredado de Request-Id.W3C TraceContext based distributed tracing is enabled by default in all recent .NET Framework/.NET Core SDKs, along with backward compatibility with legacy Request-Id protocol.

Habilitar la compatibilidad con el seguimiento distribuido de W3C para aplicaciones de JavaEnable W3C distributed tracing support for Java apps

Agente de Java 3.0Java 3.0 agent

El agente de Java 3.0 es compatible con W3C listo para usar y no se necesita ninguna configuración adicional.Java 3.0 agent supports W3C out of the box and no additional configuration is needed.

SDK de JavaJava SDK

  • Configuración de entradaIncoming configuration

    • En el caso de las aplicaciones de Java EE, agregue lo siguiente a la etiqueta <TelemetryModules> en el archivo ApplicationInsights.xml:For Java EE apps, add the following to the <TelemetryModules> tag in ApplicationInsights.xml:

      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule>
         <Param name = "W3CEnabled" value ="true"/>
         <Param name ="enableW3CBackCompat" value = "true" />
      </Add>
      
    • En el caso de las aplicaciones de Spring Boot, agregue estas propiedades:For Spring Boot apps, add these properties:

      • azure.application-insights.web.enable-W3C=true
      • azure.application-insights.web.enable-W3C-backcompat-mode=true
  • Configuración de salidaOutgoing configuration

    Agregue lo siguiente al archivo AI-Agent.xml:Add the following to AI-Agent.xml:

    <Instrumentation>
      <BuiltIn enabled="true">
        <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
      </BuiltIn>
    </Instrumentation>
    

    Nota

    El modo de compatibilidad con versiones anteriores está habilitado de forma predeterminada, por lo que el enableW3CBackCompat parámetro es opcional.Backward compatibility mode is enabled by default, and the enableW3CBackCompat parameter is optional. Solo debe utilizarlo cuando desee desactivar la compatibilidad con versiones anteriores.Use it only when you want to turn backward compatibility off.

    Lo ideal sería desactivar la compatibilidad cuando todos los servicios se hayan actualizado a la versión más reciente de los SDK compatibles con el protocolo W3C.Ideally, you would turn this off when all your services have been updated to newer versions of SDKs that support the W3C protocol. Se recomienda encarecidamente que cambie a estos SDK más recientes lo antes posible.We highly recommend that you move to these newer SDKs as soon as possible.

Importante

Asegúrese de que las configuraciones de entrada y salida sean exactamente iguales.Make sure the incoming and outgoing configurations are exactly the same.

Habilitar la compatibilidad con el seguimiento distribuido de W3C para aplicaciones webEnable W3C distributed tracing support for Web apps

Esta característica está en Microsoft.ApplicationInsights.JavaScript.This feature is in Microsoft.ApplicationInsights.JavaScript. De forma predeterminada, está deshabilitada.It's disabled by default. Para habilitarla, use la configuración distributedTracingMode. AI_AND_W3C se proporciona para la compatibilidad con versiones anteriores de cualquier servicio heredado instrumentado por Application Insights.To enable it, use distributedTracingMode config. AI_AND_W3C is provided for backward compatibility with any legacy services instrumented by Application Insights.

Agregue la siguiente configuración:Add the following configuration:

  distributedTracingMode: DistributedTracingModes.W3C

Agregue la siguiente configuración:Add the following configuration:

    distributedTracingMode: 2 // DistributedTracingModes.W3C

Importante

Para ver todas las configuraciones necesarias para habilitar la correlación, consulte la documentación Correlación de JavaScript.To see all configurations required to enable correlation, see the JavaScript correlation documentation.

Correlación de los datos de telemetría en OpenCensus PythonTelemetry correlation in OpenCensus Python

OpenCensus Python admite W3C Trace-Context sin requerir ninguna configuración adicional.OpenCensus Python supports W3C Trace-Context without requiring additional configuration.

Como referencia, el modelo de datos de OpenCensus se puede encontrar aquí.As a reference, the OpenCensus data model can be found here.

Correlación de las solicitudes entrantesIncoming request correlation

OpenCensus Python correlaciona los encabezados de Trace-Context de W3C de las solicitudes entrantes a los intervalos que se generan a partir de las solicitudes.OpenCensus Python correlates W3C Trace-Context headers from incoming requests to the spans that are generated from the requests themselves. OpenCensus lo hará automáticamente con integraciones para marcos de aplicaciones web populares: Flask, Django y Pyramid.OpenCensus will do this automatically with integrations for these popular web application frameworks: Flask, Django, and Pyramid. Solo tiene que rellenar los encabezados de Trace-Context de W3C con el formato correcto y enviarlos con la solicitud.You just need to populate the W3C Trace-Context headers with the correct format and send them with the request. Esta es una aplicación de Flask de ejemplo que muestra esto:Here's a sample Flask application that demonstrates this:

from flask import Flask
from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.ext.flask.flask_middleware import FlaskMiddleware
from opencensus.trace.samplers import ProbabilitySampler

app = Flask(__name__)
middleware = FlaskMiddleware(
    app,
    exporter=AzureExporter(),
    sampler=ProbabilitySampler(rate=1.0),
)

@app.route('/')
def hello():
    return 'Hello World!'

if __name__ == '__main__':
    app.run(host='localhost', port=8080, threaded=True)

Este código ejecuta una aplicación de Flask de ejemplo en la máquina local, escuchando el puerto 8080.This code runs a sample Flask application on your local machine, listening to port 8080. Para correlacionar el contexto de seguimiento, se envía una solicitud al punto de conexión.To correlate trace context, you send a request to the endpoint. En este ejemplo, se puede usar un comando curl:In this example, you can use a curl command:

curl --header "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" localhost:8080

Al examinar el formato de encabezado de Trace-Context, se deriva la información siguiente:By looking at the Trace-Context header format, you can derive the following information:

version: 00version: 00

trace-id: 4bf92f3577b34da6a3ce929d0e0e4736trace-id: 4bf92f3577b34da6a3ce929d0e0e4736

parent-id/span-id: 00f067aa0ba902b7parent-id/span-id: 00f067aa0ba902b7

trace-flags: 01trace-flags: 01

Si se echa un vistazo a la entrada de solicitud que se envió a Azure Monitor, se pueden ver los campos rellenados con la información de encabezado de seguimiento.If you look at the request entry that was sent to Azure Monitor, you can see fields populated with the trace header information. Puede encontrar estos datos en Registros (Analytics) en el recurso Application Insights de Azure Monitor.You can find this data under Logs (Analytics) in the Azure Monitor Application Insights resource.

Solicitud de telemetría en Registros (Analytics)

El campo id está en el formato <trace-id>.<span-id>, donde el trace-id se toma del encabezado de seguimiento que se pasó en la solicitud y el span-id es una matriz de 8 bytes generada para este intervalo.The id field is in the format <trace-id>.<span-id>, where the trace-id is taken from the trace header that was passed in the request and the span-id is a generated 8-byte array for this span.

El campo operation_ParentId tiene el formato <trace-id>.<parent-id>, donde tanto trace-id como parent-id se toman del encabezado de seguimiento que se pasó en la solicitud.The operation_ParentId field is in the format <trace-id>.<parent-id>, where both the trace-id and the parent-id are taken from the trace header that was passed in the request.

Correlación de registrosLog correlation

Python de OpenCensus permite correlacionar registros al agregar un identificador de seguimiento, un identificador de intervalo y una marca de muestreo para escribir registros.OpenCensus Python enables you to correlate logs by adding a trace ID, a span ID, and a sampling flag to log records. Estos atributos se agregan al instalar la integración de registro de OpenCensus.You add these attributes by installing OpenCensus logging integration. Los atributos siguientes se agregarán a los objetos LogRecord de Python: traceId, spanId y traceSampled.The following attributes will be added to Python LogRecord objects: traceId, spanId, and traceSampled. Tenga en cuenta que esto solo se aplica a los registradores que se crean después de la integración.Note that this takes effect only for loggers that are created after the integration.

Esta es una aplicación de ejemplo que muestra esto:Here's a sample application that demonstrates this:

import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(['logging'])
logging.basicConfig(format='%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s')
tracer = Tracer(sampler=AlwaysOnSampler())

logger = logging.getLogger(__name__)
logger.warning('Before the span')
with tracer.span(name='hello'):
    logger.warning('In the span')
logger.warning('After the span')

Cuando se ejecuta este código, se imprime lo siguiente en la consola:When this code runs, the following prints in the console:

2019-10-17 11:25:59,382 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=0000000000000000 Before the span
2019-10-17 11:25:59,384 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=70da28f5a4831014 In the span
2019-10-17 11:25:59,385 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=0000000000000000 After the span

Observe que hay un spanId presente para el mensaje de registro que se encuentra dentro del intervalo.Notice that there's a spanId present for the log message that's within the span. Es el mismo spanId que pertenece al intervalo denominado hello.This is the same spanId that belongs to the span named hello.

Puede exportar los datos de registro mediante AzureLogHandler.You can export the log data by using AzureLogHandler. Para obtener más información, consulte este artículo.For more information, see this article.

Correlación de telemetría en .NETTelemetry correlation in .NET

El runtime de .NET admite la distribución con la ayuda de Activity y DiagnosticSource..NET runtime supports distributed with the help of Activity and DiagnosticSource

El SDK de .NET de Application Insights usa DiagnosticSource y Activity para recopilar y correlacionar la telemetría.The Application Insights .NET SDK uses DiagnosticSource and Activity to collect and correlate telemetry.

Correlación de telemetría en JavaTelemetry correlation in Java

El agente de Java y el SDK de Java versión 2.0.0 o posteriores permiten la correlación automática de la telemetría.Java agent as well as Java SDK version 2.0.0 or later supports automatic correlation of telemetry. Rellena automáticamente el valor de operation_id en todos los elementos de telemetría (como seguimientos, excepciones y eventos personalizados) que se emiten en el ámbito de una solicitud.It automatically populates operation_id for all telemetry (like traces, exceptions, and custom events) issued within the scope of a request. También propaga los encabezados de correlación (descritos anteriormente) de las llamadas de un servicio de a otro mediante HTTP si el agente del SDK de Java está configurado.It also propagates the correlation headers (described earlier) for service-to-service calls via HTTP, if the Java SDK agent is configured.

Nota

El agente de Java de Application Insights recopila automáticamente las solicitudes y dependencias de JMS, Kafka, Netty/Webflux, etc.Application Insights Java agent auto-collects requests and dependencies for JMS, Kafka, Netty/Webflux, and more. En el caso del SDK de Java, la característica de correlación solamente admite las llamadas realizadas mediante Apache HttpClient.For Java SDK only calls made via Apache HttpClient are supported for the correlation feature. No se admite la propagación automática de contextos entre tecnologías de mensajería (como Kafka, RabbitMQ y Azure Service Bus) en el SDK.Automatic context propagation across messaging technologies (like Kafka, RabbitMQ, and Azure Service Bus) isn't supported in the SDK.

Nota

Para recopilar la telemetría personalizada, debe instrumentar la aplicación con el SDK de Java 2.6.To collect custom telemetry you need to instrument the application with Java 2.6 SDK.

Nombres de rolesRole names

Es posible que quiera personalizar el modo en que los nombres de los componentes aparecen en el mapa de aplicación.You might want to customize the way component names are displayed in the Application Map. Para ello, puede establecer manualmente el valor de cloud_RoleName a través de una de las acciones siguientes:To do so, you can manually set the cloud_RoleName by taking one of the following actions:

  • Para el agente de Java 3.0 de Application Insights, establezca el nombre del rol de nube de la siguiente manera:For Application Insights Java agent 3.0, set the cloud role name as follows:

    {
      "instrumentationSettings": {
        "preview": {
          "roleName": "my cloud role name"
        }
      }
    }
    

    También puede establecer el nombre de rol en la nube mediante la variable de entorno APPLICATIONINSIGHTS_ROLE_NAME.You can also set the cloud role name using the environment variable APPLICATIONINSIGHTS_ROLE_NAME.

  • Con el SDK 2.5.0 de Java de Application Insights y versiones posteriores, puede especificar el cloud_RoleName si agrega <RoleName> al archivo ApplicationInsights.xml:With Application Insights Java SDK 2.5.0 and later, you can specify the cloud_RoleName by adding <RoleName> to your ApplicationInsights.xml file:

    <?xml version="1.0" encoding="utf-8"?>
    <ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">
       <InstrumentationKey>** Your instrumentation key **</InstrumentationKey>
       <RoleName>** Your role name **</RoleName>
       ...
    </ApplicationInsights>
    
  • Si usa Spring Boot con el código de inicio de Spring Boot de Application Insights, solo debe establecer el nombre personalizado para la aplicación en el archivo application.properties:If you use Spring Boot with the Application Insights Spring Boot Starter, you just need to set your custom name for the application in the application.properties file:

    spring.application.name=<name-of-app>

    El código de inicio de Spring Boot asigna automáticamente cloudRoleName al valor que se especifica para la propiedad spring.application.name.The Spring Boot Starter automatically assigns cloudRoleName to the value you enter for the spring.application.name property.

Pasos siguientesNext steps