Migração da instrumentação X-Ray para a instrumentação OpenTelemetry

O X-Ray está migrando para OpenTelemetry (OTel) como seu principal padrão de instrumentação para rastreamento e observabilidade de aplicativos. Essa mudança estratégica se alinha AWS às melhores práticas do setor e oferece aos clientes uma solução mais abrangente, flexível e pronta para o futuro para suas necessidades de observabilidade. OpenTelemetryA ampla adoção da X-Ray no setor permite o rastreamento de solicitações em diversos sistemas, incluindo aqueles externos AWS que podem não se integrar diretamente ao X-Ray.

Este capítulo fornece recomendações para uma transição suave e enfatiza a importância de migrar para soluções OpenTelemetry baseadas para garantir suporte e acesso contínuos aos recursos mais recentes em instrumentação e observabilidade de aplicativos.

É recomendável adotar OpenTelemetry como solução de observabilidade para instrumentar seu aplicativo.

Compreensão OpenTelemetry

OpenTelemetry é uma estrutura de observabilidade padrão do setor que fornece protocolos e ferramentas padronizados para coletar dados de telemetria. Ele oferece uma abordagem unificada para instrumentar, gerar, coletar e exportar dados de telemetria, como métricas, registros e rastreamentos.

Ao migrar do X-Ray SDKs para OpenTelemetry, você obtém os seguintes benefícios:

O OpenTelemetry coletor fornece mais opções para formatos de coleta de dados e destinos de exportação do que o daemon X-Ray.

OpenTelemetry suporte em AWS

AWS fornece várias soluções para trabalhar com OpenTelemetry:

Usando OpenTelemetry com AWS CloudWatch

AWS CloudWatch oferece suporte a OpenTelemetry rastreamentos por meio de instrumentação de aplicativos do lado do cliente e AWS CloudWatch serviços nativos, como Application Signals, Trace, Map, Metrics e Logs. Para obter mais informações, consulte OpenTelemetry.

Entendendo OpenTelemetry os conceitos de migração

A tabela a seguir mapeia os conceitos de X-Ray para seus OpenTelemetry equivalentes. A compreensão desses mapeamentos ajuda você a traduzir sua instrumentação de X-Ray existente para: OpenTelemetry

Comparando recursos

A tabela a seguir mostra quais recursos são compatíveis com os dois serviços. Use essas informações para identificar quaisquer lacunas que você precise resolver durante a migração:

Configurando e configurando o rastreamento

Para criar rastreamentos OpenTelemetry, você precisa de um rastreador. Você obtém um rastreador inicializando um Tracer Provider em seu aplicativo. Isso é semelhante à forma como você usa o X-Ray Recorder para configurar o X-Ray e criar segmentos e subsegmentos em um traçado de X-Ray.

Entendendo a estrutura de dados de rastreamento

Depois de entender os conceitos básicos e os mapeamentos de recursos, você pode aprender sobre detalhes específicos de implementação, como estrutura de dados de rastreamento e amostragem.

OpenTelemetry usa extensões em vez de segmentos e subsegmentos para estruturar dados de rastreamento. Cada intervalo inclui os seguintes componentes:

Quando você migra para OpenTelemetry, suas extensões são automaticamente convertidas em segmentos ou subsegmentos de X-Ray. Isso garante que sua experiência de CloudWatch console existente permaneça inalterada.

Trabalhando com atributos de extensão

O X-Ray SDK fornece duas maneiras de adicionar dados a segmentos e subsegmentos:

Por padrão, os atributos OpenTelemetry span são convertidos em metadados nos dados brutos do X-Ray. Em vez disso, para converter atributos específicos em anotações, adicione suas chaves à lista de aws.xray.annotations atributos.

Detectando recursos em seu ambiente

OpenTelemetry usa Detectores de recursos para coletar metadados sobre os recursos que geram dados de telemetria. Esses metadados são armazenados como atributos de recursos. Por exemplo, uma entidade que produz telemetria pode ser um cluster do Amazon ECS ou uma EC2 instância da Amazon, e os atributos de recursos que podem ser registrados a partir dessas entidades podem incluir o ARN do cluster do Amazon ECS ou o ID da instância da Amazon. EC2

Gerenciando estratégias de amostragem

A amostragem de rastreamento ajuda você a gerenciar custos coletando dados de um subconjunto representativo de solicitações em vez de todas as solicitações. Tanto o X-Ray OpenTelemetry quanto o X-Ray oferecem suporte à amostragem, mas a implementam de forma diferente.

OpenTelemetry fornece várias estratégias de amostragem integradas e permite criar estratégias personalizadas. Você também pode configurar um X-Ray Remote Sampler em algumas linguagens do SDK para usar as regras de amostragem do X-Ray. OpenTelemetry

As estratégias de amostragem adicionais de OpenTelemetry são:

Para obter informações sobre as regras de amostragem do X-Ray, consulte Regras de amostragem no console do X-Ray

Para obter informações sobre amostragem de OpenTelemetry cauda, consulte Processador de amostragem de cauda

Gerenciando o contexto de rastreamento

O X-Ray SDKs gerencia o contexto do segmento para lidar corretamente com os relacionamentos pai-filho entre segmentos e subsegmentos em um rastreamento. OpenTelemetry usa um mecanismo semelhante para garantir que as extensões tenham a extensão principal correta. Ele armazena e propaga dados de rastreamento em todo o contexto de uma solicitação. Por exemplo, quando seu aplicativo processa uma solicitação e cria uma extensão de servidor para representar essa solicitação, OpenTelemetry armazenará a extensão do servidor no OpenTelemetry Contexto para que, quando uma extensão secundária for criada, essa extensão secundária possa referenciar a extensão no Contexto como sua principal.

Propagando o contexto de rastreamento

Tanto o X-Ray quanto OpenTelemetry o uso de cabeçalhos HTTP para propagar o contexto de rastreamento entre os serviços. Isso permite vincular dados de rastreamento gerados por diferentes serviços e manter as decisões de amostragem.

O X-Ray SDK propaga automaticamente o contexto de rastreamento usando o cabeçalho de rastreamento X-Ray. Quando um serviço chama outro, o cabeçalho do rastreamento contém o contexto necessário para manter os relacionamentos pai-filho entre os rastreamentos.

OpenTelemetry oferece suporte a vários formatos de cabeçalho de rastreamento para propagação de contexto, incluindo:

Configure e use o X-Ray Propagator para permitir o rastreamento entre AWS serviços. Isso permite que você propague o contexto de rastreamento para endpoints do API Gateway e outros serviços compatíveis com X-Ray.

Usando instrumentação de biblioteca

Tanto o X-Ray quanto o X-Ray OpenTelemetry fornecem instrumentação de biblioteca que requer alterações mínimas no código para adicionar rastreamento aos seus aplicativos.

O X-Ray fornece funcionalidades de instrumentação de biblioteca. Isso permite que você adicione instrumentações de X-Ray pré-criadas com o mínimo de alterações no código do aplicativo. Essas instrumentações oferecem suporte a bibliotecas específicas, como os clientes AWS SDK e HTTP, bem como a estruturas web como Spring Boot ou Express.js.

OpenTelemetryAs bibliotecas de instrumentação da geram extensões detalhadas para suas bibliotecas por meio de ganchos de biblioteca ou modificação automática de código, exigindo o mínimo de alterações no código.

Para determinar se o Library Instrumentations OpenTelemetry é compatível com sua biblioteca, procure-o no OpenTelemetry Registro em OpenTelemetry Registro.

Exportação de traços

X-Ray e OpenTelemetry use métodos diferentes para exportar dados de rastreamento.

Exportação de traços de raio-X

O X-Ray SDKs usa um emissor para enviar dados de rastreamento:

OpenTelemetry exportação de rastreamento

OpenTelemetry usa exportadores de Span configuráveis para enviar dados de rastreamento:

Processamento e encaminhamento de rastros

Tanto o X-Ray quanto o X-Ray OpenTelemetry fornecem componentes para receber, processar e encaminhar dados de rastreamento.

Processamento de traços de raio-X

O X-Ray Daemon lida com o processamento de traços:

OpenTelemetry processamento de traços

O OpenTelemetry Collector manipula o processamento de traços:

Processamento de extensão (conceito OpenTelemetry específico)

OpenTelemetry usa processadores de extensão para modificar extensões à medida que elas são criadas:

Bagagem (conceito específico) OpenTelemetry

OpenTelemetryO recurso de bagagem do permite a propagação de dados de valores-chave:

Para obter informações sobre o OpenTelemetry Collector, consulte OpenTelemetry Collector

Para obter informações sobre conceitos de X-Ray, consulte Conceitos de X-Ray no X-Ray Developer Guide

Visão geral da migração

Esta seção fornece uma visão geral das alterações de código necessárias para a migração. A lista abaixo contém orientações específicas do idioma e etapas de migração do X-Ray Daemon.

Recomendações para aplicativos novos e existentes

Para aplicativos novos e existentes, é recomendável usar as seguintes soluções para permitir o rastreamento em seus aplicativos:

Depois de migrar para soluções OpenTelemetry baseadas, sua CloudWatch experiência permanecerá a mesma. Você ainda poderá visualizar seus traços no mesmo formato nas páginas Traces e Trace Map do CloudWatch console ou recuperar seus dados de rastreamento por meio do X-Ray APIs.

Alterações na configuração de rastreamento

Você precisa substituir a configuração do X-Ray por uma OpenTelemetry configuração.

Mudanças na instrumentação da biblioteca

Atualize seu código para usar o OpenTelemetry Library Instrumentation em vez do X-Ray Library Instrumentation para AWS SDK, clientes HTTP, Web Frameworks e outras bibliotecas. Isso gera OpenTelemetry Traces em vez de X-Ray Traces.

Mudanças na instrumentação do ambiente Lambda

Para usar OpenTelemetry em suas funções do Lambda, escolha uma dessas opções de configuração:

Criação manual de dados de rastreamento

Substitua segmentos e subsegmentos do X-Ray por OpenTelemetry Spans:

Para converter um atributo em uma anotação, adicione sua chave à lista de aws.xray.annotations atributos. Para obter mais informações, consulte Habilitar anotações personalizadas de X-Ray.

Migração do X-Ray Daemon para AWS CloudWatch agente ou coletor OpenTelemetry

Você pode usar o CloudWatch agente ou o OpenTelemetry coletor para receber traços de seus aplicativos instrumentados e enviá-los para o X-Ray.

Migração na Amazon EC2 ou em servidores locais

Configuração existente do X-Ray Daemon

Instalando o daemon

Seu uso atual do X-Ray Daemon foi instalado usando um destes métodos:

Configurar o daemon do

Seu uso atual do X-Ray Daemon foi configurado usando:

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

Execução do daemon

Seu uso atual do X-Ray Daemon foi iniciado com o seguinte comando:

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

Removendo o daemon

Para remover o Daemon X-Ray da sua instância da Amazon EC2 :

Configurando o CloudWatch agente

Instalar o agente

Para obter instruções de instalação, consulte Instalação do CloudWatch agente em um servidor local.

Configurando o agente

Como iniciar o agente do

Para obter instruções sobre como iniciar o agente, consulte Iniciando o CloudWatch agente usando a linha de comando.

Configurando o OpenTelemetry coletor

Instalando o coletor

Baixe e instale o OpenTelemetry coletor para seu sistema operacional. Para obter instruções, consulte Instalação do coletor.

Configurando o coletor

Configure os seguintes componentes em seu coletor:

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]

Iniciando o coletor

Execute o coletor com seu arquivo de configuração:

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

Migração para o Amazon ECS

Usando o CloudWatch agente

Para obter mais informações, consulte Implantação do CloudWatch agente para coletar EC2 métricas em nível de instância da Amazon no Amazon ECS.

Usando o OpenTelemetry coletor

Migração no Elastic Beanstalk

Sua integração existente com o X-Ray Daemon foi ativada usando o console do Elastic Beanstalk ou configurando o X-Ray Daemon no código-fonte do seu aplicativo com um arquivo de configuração.

Usando o CloudWatch agente

Na plataforma Amazon Linux 2, configure o CloudWatch agente usando um arquivo .ebextensions de configuração:

Para obter mais informações sobre os arquivos de configuração do Elastic Beanstalk, consulte Personalização avançada do ambiente com arquivos de configuração.