View a markdown version of this page

Habilitación de la correlación entre seguimientos y registros - Amazon CloudWatch
Ejemplos de configuración de la correlación del registro de seguimientos

Habilitación de la correlación entre seguimientos y registros

Puede habilitar la correlación entre seguimientos y registros en Application Signals. Esto introduce automáticamente los ID de seguimiento y los ID de intervalo en los registros de aplicación pertinentes. A continuación, al abrir una página de detalles del seguimiento en la consola de Application Signals, las entradas de registro pertinentes (si las hay) que se correlacionan con el seguimiento actual aparecen automáticamente en la parte inferior de la página.

Por ejemplo, supongamos que observa un pico en un gráfico de latencia. Puede elegir el punto del gráfico para cargar la información de diagnóstico correspondiente a ese punto en el tiempo. A continuación, selecciona el seguimiento correspondiente para obtener más información. Al ver la información del seguimiento, puede desplazarse hacia abajo para ver los registros asociados a él. Estos registros pueden revelar patrones o códigos de error asociados a los problemas que provocan el pico de latencia.

Instrumentación de la aplicación antes de configurar la correlación de los registros de seguimientos

La aplicación ya debe estar instrumentada para Application Signals antes de configurar la correlación del registro de seguimientos. La instrumentación de Application Signals es la que rellena los valores trace_id, span_id y trace_flags de MDC en tiempo de ejecución. Sin instrumentación, estos valores permanecen vacíos (por ejemplo, trace_id=) y la correlación no funciona.

Para lograr la correlación del registro de trazas, Application Signals se basa en lo siguiente:

La comunidad de OpenTelemetry proporciona todas estas instrumentaciones. Application Signals los utiliza para inyectar contextos de seguimientos, como el ID de seguimiento y el ID de intervalo, en los registros de la aplicación. Para habilitar esto, debe cambiar manualmente la configuración de registro para habilitar la autoinstrumentación.

Según la arquitectura en la que se ejecute la aplicación, es posible que también deba configurar una variable de entorno para habilitar la correlación de registros de seguimiento, además de seguir los pasos de esta sección.

  • En Amazon EKS, no es necesaria ninguna variable de entorno adicional. Debe configurar igualmente la salida de registro como se describe en los siguientes ejemplos, y el registrador debe escribir en stdout para que Información de contenedores pueda recopilar los registros.

  • En Amazon ECS, no es necesaria ninguna variable de entorno adicional. Debe configurar igualmente la salida de registro como se describe en los siguientes ejemplos, y el registrador debe escribir en stdout para que Información de contenedores pueda recopilar los registros.

  • En Amazon EC2, consulte el paso 4 del procedimiento en Paso 3: instrumentar la aplicación e iníciela.

Información de contenedores de OpenTelemetry no habilita automáticamente la correlación de los registros de seguimiento

Al habilitar la ruta de recopilación de registros de Información de contenedores basada en OpenTelemetry (por ejemplo, mediante el complemento de EKS de Observabilidad de CloudWatch), los registros de los contenedores se recopilan y envían a Registros de CloudWatch, pero no se instrumenta la aplicación para Application Signals ni se inyecta el contexto de los seguimiento en esos registros. Para correlacionar los seguimientos con los registros, debe habilitar por separado la instrumentación de Application Signals y configurar el patrón de registro tal y como se describe en esta página.

Después de habilitar la correlación de registros de rastreo, al abrir una página de detalles de un seguimiento, cualquier entrada de registro que contenga el mismo ID de seguimiento aparecerá automáticamente en la parte inferior de la página. Con la correlación de registros de seguimiento, puede pasar rápidamente de un seguimiento a los registros de aplicaciones pertinentes sin necesidad de hacer búsquedas manuales.

Ejemplos de configuración de la correlación del registro de seguimientos

Esta sección contiene ejemplos de cómo configurar la correlación del registro de seguimientos en varios entornos.

Spring Boot para Java

Supongamos que tiene una aplicación Spring Boot en una carpeta llamada custom-app. La configuración de la aplicación suele ser un archivo YAML con el nombre custom-app/src/main/resources/application.yml y que podría tener este aspecto: 

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...

Para habilitar la correlación del registro de seguimientos, agregue la siguiente configuración de registro.

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...    

logging:
  pattern:
    level: trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p
Configuración de XML y Spring Boot como alternativas

El enfoque de application.yml (logging.pattern.level) Spring Boot y los enfoques de configuración Logback/Log4j2/Log4j de XML que se muestran en las siguientes secciones son alternativas. Use uno u otro, no ambos. Si establece el patrón en application.yml, la configuración de Logback predeterminada de Spring Boot lo recopila automáticamente sin que sea necesario ningún logback.xml independiente.

EKS y ECS: escritura de registros en stdout

Información de contenedores recopila los registros de stdout o stderr del contenedor, no de los archivos escritos dentro del contenedor. Configure el registrador para que escriba en la consola (stdout). Si un FileAppender escribe en un archivo como app.log, se producen líneas correctamente etiquetadas con el seguimiento, pero no se recopilan ni aparecen correlacionadas en la página de detalles del seguimiento. Si debe registrar en un archivo, también tendrá que enviar ese archivo (por ejemplo, un recopilador asociado que lea un volumen compartido), lo que queda fuera del ámbito de esta página.

Logback para Java

En la configuración de registro (como logback.xml), inserte el contexto de seguimiento trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p en pattern del codificador. Por ejemplo, la siguiente configuración antepone el contexto de seguimiento al mensaje de registro.

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder> 
    <pattern>trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n</pattern> 
  </encoder>
</appender>

Para obtener más información sobre los codificadores de Logback, consulte Encoders en la documentación de Logback.

Log4j2 para Java

En la configuración de registro (por ejemplo, log4j2.xml), inserte el contexto de seguimiento trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p en PatternLayout. Por ejemplo, la siguiente configuración antepone el contexto de seguimiento al mensaje de registro.

<Appenders>
  <Console name="CONSOLE" target="SYSTEM_OUT">
    <PatternLayout pattern="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>
  </Console>
</Appenders>

Para obtener más información sobre los diseños de patrones en Log4j2, consulte Pattern Layout en la documentación de Log4j2.

Log4j para Java

En la configuración de registro (como log4j.xml), inserte el contexto de seguimiento trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p en PatternLayout. Por ejemplo, la siguiente configuración antepone el contexto de seguimiento al mensaje de registro.

<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p - %m%n"/>
  </layout>
</appender>

Para obtener más información sobre los diseños de patrones en Log4j, consulte Class Pattern Layout en la documentación de Log4j.

Python

Establezca la variable de entorno de OTEL_PYTHON_LOG_CORRELATION en true mientras se ejecuta la aplicación. Para obtener más información, consulte Enable trace context injection en la documentación de OpenTelemetry de Python.

Node.js

Para obtener más información sobre cómo habilitar la inyección de contexto de rastreo en Node.js para las bibliotecas de registro que la admiten, consulte la documentación de uso de NPM de las instrumentaciones automáticas de Pino, Winston o Bunyan para Node.js.

Verificar la configuración

Después de volver a implementar la aplicación, confirme que una línea de registro muestre ahora un valor trace_id rellenado (por ejemplo, mediante la ejecución de kubectl logs pod-name). A continuación, abra una página de detalles del seguimiento en la consola de Application Signals y confirme que las entradas de registro correlacionadas aparezcan en la parte inferior de la página.

En Amazon EKS, los registros se escriben en el grupo de registros de la aplicación de Información de contenedores (/aws/containerinsights/cluster-name/application, o /aws/otel/containerinsights/cluster-name/application cuando la ruta de registro de Información de contenedores de OpenTelemetry está habilitada).