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 trazas.

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. Comprender estos mapeos le ayuda a traducir su instrumentación de rayos X existente a: OpenTelemetry

Comparación de características

En la siguiente tabla se muestran las funciones compatibles con ambos servicios. Utilice esta información para identificar las brechas que necesite abordar durante la migración:

Configuración y configuración del rastreo

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

Comprender la estructura de los datos de rastreo

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

OpenTelemetry utiliza intervalos en lugar de segmentos y subsegmentos para estructurar los datos de rastreo. Cada tramo 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.

Trabajando con atributos de intervalo

El SDK de X-Ray ofrece dos formas de añadir 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, añada sus claves a la lista de aws.xray.annotations atributos.

Detectar recursos en su 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 .

Administrar las estrategias de muestreo

El muestreo de trazas 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 rayos X, consulte Reglas de muestreo en la consola de X-Ray

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

Administrar el contexto de rastreo

X-Ray SDKs gestiona el contexto del segmento para gestionar correctamente las relaciones padre-hijo entre los segmentos y los 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 principal.

Propagar el contexto de rastreo

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 rastreo generados por diferentes servicios y mantener las decisiones de muestreo.

El SDK de X-Ray propaga automáticamente el contexto de rastreo mediante el encabezado de rastreo de X-Ray. Cuando un servicio llama a otro, el encabezado de rastreo contiene el contexto necesario para mantener las relaciones padre-hijo entre los rastreos.

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 rastreo a los puntos finales de API Gateway y otros servicios compatibles con X-Ray.

Uso de la instrumentación de la 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 añadir instrumentaciones de rayos X 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 trazas

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

Exportación de trazas de rayos X

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 trazas

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

Procesamiento de trazas de rayos X

El Demonio X-Ray gestiona el procesamiento de trazas:

OpenTelemetry procesamiento de trazas

El OpenTelemetry recopilador gestiona el procesamiento de trazas:

Procesamiento de intervalos (concepto OpenTelemetry específico)

OpenTelemetry utiliza 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 Collector OpenTelemetry

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

Información general sobre la migración

En esta sección se proporciona una descripción general 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.

Cambios en la configuración de rastreo

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

Cambios en la instrumentación de la biblioteca

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 Lambda

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

Creación manual de datos de rastreo

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

Para convertir un atributo en una anotación, añada su clave a la lista de aws.xray.annotations atributos. Para obtener más información, consulte Habilitar anotaciones de rayos X 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 de 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

Eliminando el daemon

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

Configuración del CloudWatch agente

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 colector

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 su 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]

Iniciar el recopilador

Ejecute el recopilador con su 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 existente de X-Ray Daemon se activó mediante la consola de Elastic Beanstalk o configurando X-Ray Daemon en el código fuente 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.