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, logs 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

As tabelas a seguir mostram quais recursos são compatíveis com os dois serviços. Use essas informações para identificar lacunas que você precisará resolver durante a migração:

Configurar o rastreamento

Para criar rastreamentos OpenTelemetry, você precisa de um rastreador. Para obter um rastreador, inicialize o Trace Provider na sua aplicação. Isso é semelhante à maneira como você usa o gravador do X-Ray para configurar o X-Ray e criar segmentos e subsegmentos em um rastreamento de X-Ray.

Noções básicas sobre a estrutura dos dados de rastreamento

Após entender os conceitos básicos e os mapeamentos de recursos, você pode saber mais 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 extensão 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.

Trabalhar com atributos de extensão

O SDK do X-Ray 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. Para converter atributos específicos em anotações, adicione as chaves deles à lista de atributos aws.xray.annotations.

Detectar recursos no 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

Gerenciar 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

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

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

OpenTelemetry suporta 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 o X-Ray.

Usar 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 do X-Ray predefinidas com o mínimo de alterações no código da aplicação. Essas instrumentações oferecem suporte a bibliotecas específicas, como AWS SDK e clientes HTTP, bem como estruturas da 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.

Exportar rastreamentos

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

Exportação de rastreamento do X-Ray

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 rastreamento

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

Processamento de rastreamentos do X-Ray

O daemon do X-Ray gerencia o processamento de rastreamentos:

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 os conceitos do X-Ray, consulte Conceitos do X-Ray no Guia do desenvolvedor do X-Ray

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 as etapas de migração do daemon do X-Ray.

Recomendações de aplicações novas e existentes

Paro aplicações novas e existentes, é recomendável usar as seguintes soluções para permitir o rastreamento nas suas aplicações:

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.

Alterações na instrumentação de 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.

Alterações na instrumentação do ambiente do Lambda

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

Criar dados de rastreamento manualmente

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

Para converter um atributo em uma anotação, adicione a chave à lista de atributos aws.xray.annotations. Para obter mais informações, consulte Enable The Customized X-Ray Annotations.

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 daemon do X-Ray

Instalar o daemon

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

Configurar o daemon do

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

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

Execução do daemon

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

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

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

Configurar 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

Instalar o coletor

Baixe e instale o OpenTelemetry coletor para seu sistema operacional. Para obter instruções, consulte Install the Collector.

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

Iniciar o coletor

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

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

Migrar no 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

Migrar no Elastic Beanstalk

Sua integração existente do daemon do X-Ray foi ativada usando o console do Elastic Beanstalk ou configurando o daemon do X-Ray no código-fonte da aplicação 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 de ambiente com arquivos de configuração.