Migración de la instrumentación de rayos X a la instrumentación OpenTelemetry

X-Ray está pasando a ser OpenTelemetry (OTel) su principal estándar de instrumentación para el rastreo y la observabilidad de las aplicaciones. Este cambio estratégico se alinea AWS con las mejores prácticas de la industria y ofrece a los clientes una solución más completa, flexible y preparada para el futuro para sus necesidades de observabilidad. OpenTelemetrySu amplia adopción en la industria permite rastrear las solicitudes en diversos sistemas, incluidos aquellos externos AWS que pueden no integrarse directamente con X-Ray.

En este capítulo se ofrecen recomendaciones para una transición fluida y se hace hincapié en la importancia de migrar a soluciones OpenTelemetry basadas en sistemas para garantizar el soporte y el acceso continuos a las funciones más recientes en materia de observabilidad e instrumentación de aplicaciones.

Se recomienda adoptarla OpenTelemetry como solución de observabilidad para instrumentar su aplicación.

Comprensión OpenTelemetry

OpenTelemetry es un marco de observabilidad estándar del sector que proporciona protocolos y herramientas estandarizados para recopilar datos de telemetría. Ofrece un enfoque unificado para instrumentar, generar, recopilar y exportar datos de telemetría como métricas, registros y rastros.

Al migrar de X-Ray SDKs a OpenTelemetry, obtiene los siguientes beneficios:

El OpenTelemetry recopilador ofrece más opciones para los formatos de recopilación de datos y los destinos de exportación que el daemon X-Ray.

OpenTelemetry soporte en AWS

AWS proporciona múltiples soluciones para trabajar con OpenTelemetry:

Utilización con OpenTelemetry AWS CloudWatch

AWS CloudWatch admite los OpenTelemetry rastreos a través de la instrumentación de aplicaciones del lado del cliente y de AWS CloudWatch servicios nativos, como Application Signals, Trace, Map, Metrics y Logs. Para obtener más información, consulte OpenTelemetry.

Comprensión OpenTelemetry de los conceptos de migración

La siguiente tabla mapea los conceptos de X-Ray con sus OpenTelemetry equivalentes. La comprensión de estos mapeos le ayuda a traducir su instrumentación de rayos X existente a: OpenTelemetry

Comparación de características

En la tabla siguiente se muestran las características admitidas en ambos servicios. Utilice esta información para identificar las brechas que necesite abordar durante la migración:

Instalación y configuración del rastro

Para crear trazas OpenTelemetry, necesitas un rastreador. Para obtener un rastreador, debe inicializar un proveedor de rastreadores en la aplicación. Esto es similar a la forma en que se utiliza la grabadora de X-Ray para configurar X-Ray y crear segmentos y subsegmentos en un rastro de X-Ray.

Descripción de la estructura de datos de rastros

Tras comprender los conceptos básicos y las asignaciones de características, podrá obtener información sobre los detalles específicos de la implementación, como la estructura de los datos de rastros y el muestreo.

OpenTelemetry utiliza tramos en lugar de segmentos y subsegmentos para estructurar los datos de rastreo. Cada intervalo incluye los siguientes componentes:

Al migrar a OpenTelemetry, los tramos se convierten automáticamente en segmentos o subsegmentos de X-Ray. Esto garantiza que su experiencia de CloudWatch consola actual permanezca inalterada.

Uso de atributos de intervalo

El X-Ray SDK ofrece dos formas de agregar datos a segmentos y subsegmentos:

De forma predeterminada, los OpenTelemetry atributos de espacio se convierten en metadatos en los datos sin procesar de X-Ray. Para convertir atributos específicos en anotaciones, agregue sus claves a la lista de atributos aws.xray.annotations.

Detección de recursos en el entorno

OpenTelemetry usa Resource Detectors para recopilar metadatos sobre los recursos que generan datos de telemetría. Estos metadatos se almacenan como atributos de recurso. Por ejemplo, una entidad que produce telemetría podría ser un clúster de Amazon ECS o una EC2 instancia de Amazon, y los atributos de recursos que se pueden registrar desde estas entidades pueden incluir el ARN del clúster de Amazon ECS o el ID de instancia de Amazon EC2 .

Administración de las estrategias de muestreo

El muestreo de rastros le ayuda a administrar los costos al recopilar datos de un subconjunto representativo de solicitudes en lugar de todas las solicitudes. OpenTelemetry Tanto X-Ray como X-Ray admiten el muestreo, pero lo implementan de manera diferente.

OpenTelemetry proporciona varias estrategias de muestreo integradas y le permite crear estrategias personalizadas. También puede configurar un muestreador remoto de rayos X en algunos lenguajes del SDK para utilizar las reglas de muestreo de rayos X. OpenTelemetry

Las estrategias de muestreo adicionales OpenTelemetry son las siguientes:

Para obtener información sobre las reglas de muestreo de X-Ray, consulte Reglas de muestreo en la consola de X-Ray

Para obtener información sobre el muestreo de OpenTelemetry la cola, consulte el procesador de muestreo de la cola

Administración del contexto de rastros

X-Ray SDKs gestiona el contexto del segmento para gestionar correctamente las relaciones padre-hijo entre los segmentos y subsegmentos de una traza. OpenTelemetry utiliza un mecanismo similar para garantizar que los tramos tengan el intervalo principal correcto. Almacena y propaga los datos de rastreo en todo el contexto de una solicitud. Por ejemplo, cuando la aplicación procese una solicitud y cree un intervalo de servidor que represente esa solicitud, OpenTelemetry almacenará el intervalo de servidores en el OpenTelemetry contexto para que, cuando se cree un intervalo secundario, ese intervalo secundario pueda hacer referencia al intervalo del contexto como su principal.

Propagación del contexto de rastro

Tanto X-Ray como yo OpenTelemetry utilizan encabezados HTTP para propagar el contexto de rastreo en todos los servicios. Esto le permite vincular los datos de rastros generados por diferentes servicios y mantener las decisiones de muestreo.

El X-Ray SDK propaga automáticamente el contexto de rastro mediante el encabezado de rastro de X-Ray. Cuando un servicio llama a otro, el encabezado de rastro contiene el contexto necesario para mantener las relaciones principal-secundario entre los rastros.

OpenTelemetry admite varios formatos de encabezados de rastreo para la propagación del contexto, entre los que se incluyen:

Configure y utilice el propagador de rayos X para permitir el rastreo entre AWS los servicios. Esto le permite propagar el contexto de rastros a los puntos de conexión de API Gateway y otros servicios compatibles con X-Ray.

Uso de la instrumentación de biblioteca

Tanto X-Ray como OpenTelemetry yo proporcionan instrumentación de biblioteca que requiere cambios mínimos en el código para añadir el rastreo a sus aplicaciones.

X-Ray proporciona funcionalidades de instrumentación de biblioteca. Esto le permite agregar instrumentaciones de X-Ray prediseñadas con cambios mínimos en el código de la aplicación. Estas instrumentaciones son compatibles con bibliotecas específicas, como el AWS SDK y los clientes HTTP, así como con marcos web como Spring Boot o Express.js.

OpenTelemetryLas bibliotecas de instrumentación generan extensiones detalladas para sus bibliotecas mediante enlaces a las bibliotecas o mediante la modificación automática del código, lo que requiere cambios mínimos en el código.

Para determinar si Library Instrumentations OpenTelemetry es compatible con su biblioteca, búsquela en el OpenTelemetry Registro de Registry. OpenTelemetry

Exportación de rastros

X-Ray y OpenTelemetry utilizan diferentes métodos para exportar los datos de rastreo.

Exportación de rastros de X-Ray

Los X-Ray SDKs utilizan un emisor para enviar datos de rastreo:

OpenTelemetry exportación de trazas

OpenTelemetry utiliza Span Exporters configurables para enviar datos de rastreo:

Procesamiento y reenvío de rastros

Tanto X-Ray como OpenTelemetry yo proporcionan componentes para recibir, procesar y reenviar datos de rastreo.

Procesamiento de rastros de X-Ray

El X-Ray Daemon gestiona el procesamiento de rastros:

OpenTelemetry procesamiento de trazas

El OpenTelemetry recopilador gestiona el procesamiento de trazas:

Procesamiento de intervalos (concepto OpenTelemetry específico)

OpenTelemetry utiliza los procesadores Span para modificar los intervalos a medida que se crean:

Equipaje (OpenTelemetryconcepto específico)

OpenTelemetryLa función de equipaje permite la propagación de datos clave-valor:

Para obtener información sobre el OpenTelemetry recopilador, consulte el recopilador OpenTelemetry

Para obtener información acerca de los conceptos de X-Ray, consulte Conceptos de X-Ray en la Guía para desarrolladores de X-Ray

Información general sobre la migración

En esta sección, se proporciona información general acerca de los cambios de código necesarios para la migración. La siguiente lista contiene una guía específica para cada idioma y los pasos de migración de X-Ray Daemon.

Recomendaciones para aplicaciones nuevas y existentes

Para las aplicaciones nuevas y existentes, se recomienda utilizar las siguientes soluciones para habilitar el rastreo en las aplicaciones:

Tras migrar a soluciones OpenTelemetry basadas en bases, su CloudWatch experiencia seguirá siendo la misma. Podrá seguir viendo sus trazas en el mismo formato en las páginas de trazas y mapas de trazas de la CloudWatch consola, o recuperar sus datos de rastreo a través del X-Ray APIs.

Rastreo de los cambios de configuración

Debe reemplazar la configuración de X-Ray por una OpenTelemetry configuración.

Cambios de instrumentación de bibliotecas

Actualice su código para usar OpenTelemetry Library Instrumentation en lugar de X-Ray Library Instrumentation para AWS SDK, clientes HTTP, marcos web y otras bibliotecas. Esto genera OpenTelemetry trazas en lugar de trazas de X-Ray.

Cambios en la instrumentación del entorno de Lambda

Para utilizarlas OpenTelemetry en las funciones de Lambda, elija una de estas opciones de configuración:

Creación manual de datos de rastros

Sustituya los segmentos y subsegmentos de X-Ray por OpenTelemetry Spans:

Para convertir un atributo en una anotación, agregue su clave a la lista de atributos de aws.xray.annotations. Para obtener más información, consulte Habilitar anotaciones de X-Ray personalizadas.

Migración de X-Ray Daemon a AWS CloudWatch agente o recopilador OpenTelemetry

Puede utilizar el CloudWatch agente o el OpenTelemetry recopilador para recibir las trazas de sus aplicaciones instrumentadas y enviarlas a X-Ray.

Migración en Amazon EC2 o en servidores locales

Configuración del X-Ray Daemon existente

Instalación del daemon

Su uso actual de X-Ray Daemon se instaló mediante uno de estos métodos:

Configuración del daemon de

Su uso actual de X-Ray Daemon se configuró mediante:

./xray -c ~/xray-daemon.yaml

Ejecutar el demonio

Su uso actual de X-Ray Daemon se inició con el siguiente comando:

~/xray-daemon$ ./xray -o -n us-east-1

Eliminación del daemon

Para eliminar el Demonio X-Ray de tu EC2 instancia de Amazon:

Configuración del agente CloudWatch

Instalación del agente

Para obtener instrucciones de instalación, consulte Instalación del CloudWatch agente en un servidor local.

Configuración del agente

Cómo iniciar el agente de

Para obtener instrucciones sobre cómo iniciar el agente, consulte Iniciar el CloudWatch agente mediante la línea de comandos.

Configuración del OpenTelemetry recopilador

Instalación del recopilador

Descargue e instale el OpenTelemetry recopilador para su sistema operativo. Para obtener instrucciones, consulte Instalación del recopilador.

Configuración del recopilador

Configure los siguientes componentes en el recopilador:

extensions:
  awsproxy:
    endpoint: 127.0.0.1:2000
  health_check:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch:

exporters:
  awsxray:
    region: 'us-east-1'

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [awsxray]
  extensions: [awsproxy, health_check]

Inicio del recopilador

Ejecute el recopilador con el archivo de configuración:

otelcol --config=otel-collector-config.yaml

Migración en Amazon ECS

Uso del agente CloudWatch

Para obtener más información, consulte Implementación del CloudWatch agente para recopilar métricas a EC2 nivel de instancia de Amazon en Amazon ECS.

Uso del recopilador OpenTelemetry

Migración en Elastic Beanstalk

La integración actual de X-Ray Daemon se activó al usar la consola de Elastic Beanstalk o mediante la configuración de X-Ray Daemon en el código de origen de la aplicación con un archivo de configuración.

Uso del agente CloudWatch

En la plataforma Amazon Linux 2, configure el CloudWatch agente mediante un archivo .ebextensions de configuración:

Para obtener más información sobre los archivos de configuración de Elastic Beanstalk, consulte Personalización avanzada del entorno con archivos de configuración.