As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Migração da instrumentação X-Ray para a instrumentação OpenTelemetry **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). 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. **Topics** + [Compreensão OpenTelemetry](#migration-to-opentelemetry) + [Entendendo OpenTelemetry os conceitos de migração](#opentelemetry-concepts) + [Visão geral da migração](#migration-overview) + [Migração do X-Ray Daemon para AWS CloudWatch agente ou coletor OpenTelemetry](#xray-Daemon-migration) + [Migrando para Java OpenTelemetry](xray-migration-opentelemetry.md) + [Migre para Go OpenTelemetry](manual-instrumentation-go.md) + [Migrar para Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md) + [Migrar para o.NET OpenTelemetry](introduction-dotnet.md) + [Migrar para Python OpenTelemetry](migrate-xray-to-opentelemetry-python.md) + [Migrar para Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md) ## 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: + Suporte aprimorado para estrutura e instrumentação de biblioteca + Suporte para linguagens de programação adicionais + Recursos de instrumentação automática + Opções flexíveis de configuração de amostragem + Coleta unificada de métricas, logs e rastreamentos 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: + AWS Distro para OpenTelemetry Exporte OpenTelemetry traços como segmentos para o X-Ray. Para obter mais informações, consulte [AWS Distro for OpenTelemetry](https://aws-otel.github.io/). + CloudWatch Sinais de aplicação Exporte OpenTelemetry traços e métricas personalizados para monitorar a integridade do aplicativo. Para obter mais informações, consulte [Trabalhar com o Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). + CloudWatch OTel Ponto final Exporte OpenTelemetry traços para o X-Ray usando o OTel endpoint HTTP com OpenTelemetry instrumentação nativa. Para obter mais informações, consulte [Usando OTel endpoints](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html). #### 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html). ## 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 | Conceito do X-Ray | OpenTelemetry conceito | | --- | --- | | Gravador do X-Ray | Tracer Provider e rastreadores | | Plug-ins de serviço | Detector de recursos | | Segmento | Extensão (servidor) | | Subsegmento | Extensão (sem servidor) | | Regras de amostragem do X-Ray | OpenTelemetry Amostragem (personalizável) | | Emissor do X-Ray | Exportador de extensão (personalizável) | | Anotações/metadados | Atributos | | Instrumentação da biblioteca | Instrumentação da biblioteca | | Contexto de rastreamento do X-Ray | Contexto da extensão | | Propagação do contexto de rastreamento do X-Ray | Propagação do contexto de rastreamento do W3C | | Amostragem de rastreamento do X-Ray Trace | OpenTelemetry Amostragem de traços | | N/D | Processamento da extensão | | N/D | Baggage | | Daemon do X-Ray | OpenTelemetry Colecionador | **nota** Para obter mais informações sobre OpenTelemetry conceitos, consulte a [OpenTelemetry documentação](https://opentelemetry.io/docs). ### 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 precisarão ser resolvidas resolver durante a migração: | Recurso | Instrumentação do X-Ray | OpenTelemetry instrumentação | | --- | --- | --- | | Instrumentação da biblioteca | Compatível | Compatível | | Amostragem do X-Ray | Compatível | Compatível com OTel java/.net/GO Compatível com ADOT Java/. NET/Python/Node.js | | Propagação do contexto de rastreamento do X-Ray | Compatível | Compatível | | Detecção de recursos | Compatível | Compatível | | Anotações de segmento | Compatível | Compatível | | Metadados de segmento | Compatível | Compatível | | Instrumentação automática de código zero | Compatível com Java | Compatível com OTel Java/. NET/Python/Node.js Compatível com ADOT Java/. NET/Python/Node.js | | Criação manual de rastreamento | Compatível | Compatível | ### 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. **nota** O OpenTelemetry *Tracer Provider* oferece mais opções de configuração do que o X-Ray Recorder. #### Noções básicas sobre a estrutura dos dados de rastreamento Após entender os conceitos básicos e os mapeamentos de recursos, você poderá aprender 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: + Nome + ID exclusivo + Carimbos de data/hora de início e término + Tipo de extensão + Contexto da extensão + Atributos (metadados de valores-chave) + Eventos (logs de data e hora) + Links para outras extensões + Informações de status + Referências de extensão principal 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: Anotações Pares de valores-chave que são indexados para filtragem e pesquisa Metadados Pares de valores-chave que contêm dados complexos que não são indexados para pesquisa 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`. + Para obter mais informações sobre OpenTelemetry conceitos, consulte [OpenTelemetry Traces](https://opentelemetry.io/docs/concepts/signals/traces/) + Para obter detalhes sobre como os OpenTelemetry dados são mapeados para dados do X-Ray, consulte [OpenTelemetry Tradução do modelo de dados do X-Ray](https://aws-otel.github.io/docs/getting-started/X-Ray#otel-to-X-Ray-data-model-translation-behavior-of-aws-X-Ray-exporter) ### 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 instância do Amazon EC2, e os atributos de recursos que podem ser registrados com base nessas entidades podem incluir o ARN do cluster do Amazon ECS ou o ID da instância do Amazon EC2. + Para obter informações sobre os tipos de recursos compatíveis, consulte Convenções [semânticas de OpenTelemetry recursos](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/) + Para saber mais sobre os plug-ins de serviço do X-Ray, consulte [Configurar o SDK do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html). ### 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. **nota** A amostragem de menos de 100% dos rastreamentos reduz os custos de observabilidade, mantendo insights significativos sobre o desempenho da aplicação. 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: + Amostragem baseada no pai: respeita a decisão de amostragem da extensão pai antes de aplicar outras estratégias de amostragem + Amostragem baseada na taxa de identificação do rastreamento: faz uma amostragem aleatória de uma porcentagem especificada de extensões + Amostragem da cauda — Aplica regras de amostragem para completar traços no coletor OpenTelemetry + Amostradores personalizados: implemente sua própria lógica de amostragem usando a interface de amostragem Para obter informações sobre as regras de amostragem do X-Ray, consulte [Regras de amostragem no console do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) Para obter informações sobre amostragem de OpenTelemetry cauda, consulte Processador de amostragem de [cauda](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) ### 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 oferece suporte a vários formatos de cabeçalho de rastreamento para propagação de contexto, incluindo: + Contexto de rastreamento do W3C (padrão) + Cabeçalho de rastreamento do X-Ray + Outros formatos personalizados **nota** Você pode configurar OpenTelemetry para usar um ou mais formatos de cabeçalho. Por exemplo, use o X-Ray Propagator para enviar contexto de rastreamento para AWS serviços que oferecem suporte ao rastreamento de X-Ray. Configure e use o X-Ray Propagator para permitir o rastreamento entre AWS serviços. Essa ação possibilita propagar o contexto de rastreamento para endpoints do API Gateway e outros serviços compatíveis com o X-Ray. + Para saber mais sobre cabeçalhos de rastreamento do X-Ray, consulte [Cabeçalho de rastreamento](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) no Guia do desenvolvedor do X-Ray + Para obter informações sobre propagação de OpenTelemetry contexto, consulte [Contexto e propagação de contexto](https://opentelemetry.io/docs/concepts/context-propagation/) na documentação OpenTelemetry ### 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. Essa ação possibilita adicionar 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 o AWS SDK e os clientes 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.](https://opentelemetry.io/ecosystem/registry/) ### 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: + Envia segmentos e subsegmentos para o daemon do X-Ray + Usa UDP para E/S sem bloqueio + É configurado por padrão no SDK #### OpenTelemetry exportação de rastreamento OpenTelemetry usa *exportadores de Span configuráveis para enviar dados* de rastreamento: + Usa os protocolos *http/protobuf* ou *grpc* + Exporta extensões para endpoints monitorados pelo OpenTelemetry coletor ou agente CloudWatch + Permite configurações personalizadas do exportador ### 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: + Ouve o tráfego UDP do X-Ray SDKs + Agrupa segmentos e subsegmentos + Carrega lotes para o serviço do X-Ray #### OpenTelemetry processamento de traços O OpenTelemetry Collector manipula o processamento de traços: + Recebe rastreamentos de serviços instrumentados + Processa e, opcionalmente, modifica os dados de rastreamento + Envia rastreamentos processados para vários backends, incluindo o X-Ray **nota** O AWS CloudWatch agente também pode receber e enviar OpenTelemetry traços para o X-Ray. Para obter mais informações, consulte [Coletar métricas e rastreamentos com OpenTelemetry](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html). ### Processamento de extensão (conceito OpenTelemetry específico) OpenTelemetry usa processadores de extensão para modificar extensões à medida que elas são criadas: + Permite ler e modificar extensões na criação ou na conclusão + Habilita a lógica personalizada para o gerenciamento de extensões ### Bagagem (conceito específico) OpenTelemetry OpenTelemetryO recurso de bagagem do permite a propagação de dados de valores-chave: + Permite a transmissão de dados arbitrários com o contexto de rastreamento + É útil para propagar informações específicas da aplicação para todos os limites do serviço [Para obter informações sobre o OpenTelemetry Collector, consulte OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) Para saber mais sobre os conceitos do X-Ray, consulte [Conceitos do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html) 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. **Importante** Para migrar totalmente da instrumentação X-Ray para a OpenTelemetry instrumentação, você precisa: Substitua o uso do X-Ray SDK por uma solução OpenTelemetry Substitua o X-Ray Daemon pelo CloudWatch agente ou OpenTelemetry coletor (com o X-Ray Exporter) + [Migrando para Java OpenTelemetry](xray-migration-opentelemetry.md) + [Migre para Go OpenTelemetry](manual-instrumentation-go.md) + [Migrar para Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md) + [Migrar para o.NET OpenTelemetry](introduction-dotnet.md) + [Migrar para Python OpenTelemetry](migrate-xray-to-opentelemetry-python.md) + [Migrar para Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md) ### Recomendações de aplicações novas e existentes Quanto a aplicações novas e existentes, é recomendável usar as seguintes soluções para permitir o rastreamento nas suas aplicações: Instrumentação + OpenTelemetry SDKs + AWS Distro para instrumentação OpenTelemetry Coleta de dados + OpenTelemetry Colecionador + CloudWatch Agente 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-api.html). ### Alterações na configuração de rastreamento Você precisa substituir a configuração do X-Ray por uma OpenTelemetry configuração. **Comparação entre X-Ray e OpenTelemetry configuração** | Recurso | SDK do X-Ray | OpenTelemetry | | --- | --- | --- | | Configurações padrão | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/xray-sdk-migration.html) | | Configurações manuais | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/xray-sdk-migration.html) | ### 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. **nota** As alterações no código variam conforme o idioma e a biblioteca. Consulte os guias de migração específicos do idioma para obter instruções detalhadas. ### 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: 1. Usar uma camada do Lambda de instrumentação automática: + (Recomendado) [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html) Layer para OpenTelemetry **nota** Para usar somente o rastreamento, defina a variável de ambiente `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` do Lambda. + [AWS camada Lambda gerenciada para ADOT](https://aws-otel.github.io/docs/getting-started/lambda) 1. Configurado manualmente OpenTelemetry para sua função Lambda: + Configure um processador de extensão simples com um exportador de extensão UDP do X-Ray + Configure um propagador do X-Ray para Lambda ### Criar dados de rastreamento manualmente Substitua segmentos e subsegmentos do X-Ray por OpenTelemetry Spans: + Use um OpenTelemetry rastreador para criar vãos + Adicione atributos às extensões (equivalentes aos metadados e anotações do X-Ray) **Importante** Quando enviado para o X-Ray: As extensões do servidor são convertidas em segmentos do X-Ray Outras extensões são convertidas em subsegmentos do X-Ray Os atributos são convertidos em metadados por padrão 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](https://aws-otel.github.io/docs/getting-started/x-ray#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. **nota** A versão 1.300025.0 e posterior do CloudWatch agente pode coletar rastreamentos. OpenTelemetry Usar o CloudWatch agente em vez do X-Ray Daemon reduz o número de agentes que você precisa gerenciar. Para obter mais informações, consulte [Coleta de métricas, registros e rastreamentos com o CloudWatch agente](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html). **Topics** + [Migrar no Amazon EC2 ou em servidores on-premises](#ec2-onprem-migration) + [Migrar no Amazon ECS](#ecs-migration) + [Migrar no Elastic Beanstalk](#beanstalk-migration) ### Migrar no Amazon EC2 ou em servidores on-premises **Importante** Pare o processo do X-Ray Daemon antes de usar o CloudWatch agente ou OpenTelemetry coletor para evitar conflitos de portas. #### 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: Instalação manual Baixar e executar o arquivo executável do bucket do Amazon S3 do daemon do X-Ray. Instalação automática Usar este script para instalar o daemon ao iniciar uma instância: ``` #!/bin/bash curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \ -o /home/ec2-user/xray.rpm yum install -y /home/ec2-user/xray.rpm ``` ##### Configurar o daemon do Seu uso atual do daemon do X-Ray foi configurado usando: + Argumentos da linha de comando + Arquivo de configuração (`xray-daemon.yaml`) **Example Usar um arquivo de configuração** ``` ./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 do X-Ray da sua instância do Amazon EC2: 1. Interrompa o serviço do daemon: ``` systemctl stop xray ``` 1. Exclua o arquivo de configuração: ``` rm ~/path/to/xray-daemon.yaml ``` 1. Se configurado, remova o arquivo de log: **nota** A localização do arquivo de log depende da sua configuração: Configuração da linha de comando: `/var/log/xray-daemon.log` Arquivo de configuração: verifique a configuração de `LogPath` #### Configurando o CloudWatch agente ##### Instalar o agente Para obter instruções de instalação, consulte [Instalação do CloudWatch agente em um servidor local](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_user-first). ##### Configurar o agente 1. Crie um arquivo de configuração para habilitar a coleta de rastreamentos. Para obter mais informações, consulte [Criação do arquivo de configuração do CloudWatch agente](AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html). 1. Configurar permissões do IAM: + Anexe um perfil do IAM ou especifique as credenciais do agente. Para obter mais informações, consulte [Configurar perfis do IAM](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_permissions-first). + Verifique se o perfil ou as credenciais incluem a permissão `xray:PutTraceSegments`. ##### Como iniciar o agente do Para obter instruções sobre como iniciar o agente, consulte [Iniciando o CloudWatch agente usando a linha de comando](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#start-CloudWatch-Agent-EC2-commands-fleet). #### 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](https://opentelemetry.io/docs/collector/installation/). ##### Configurar o coletor Configure os seguintes componentes em seu coletor: + Extensão awsproxy Necessário para amostragem do X-Ray + OTel receptores Coleta rastreamentos da sua aplicação + Exportador xray Envia rastreamentos para o X-Ray **Example Configuração do coletor de amostras — .yaml otel-collector-config** ``` 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] ``` **Importante** Configure AWS as credenciais com a `xray:PutTraceSegments` permissão. Para obter mais informações, consulte [Especificar credenciais](sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials). ##### Iniciar o coletor Execute o coletor com seu arquivo de configuração: ``` otelcol --config=otel-collector-config.yaml ``` ### Migrar no Amazon ECS **Importante** Seu perfil de tarefas deve ter a permissão `xray:PutTraceSegments` para qualquer coletor que você usar. Pare qualquer contêiner X-Ray Daemon existente antes de executar o contêiner do CloudWatch agente ou OpenTelemetry coletor no mesmo host para evitar conflitos de portas. #### Usando o CloudWatch agente 1. Obtenha a imagem do Docker na [Galeria Pública do Amazon ECR](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent). 1. Crie um arquivo de configuração chamado`cw-agent-otel.json`: ``` { "traces": { "traces_collected": { "xray": { "tcp_proxy": { "bind_address": "0.0.0.0:2000" } }, "otlp": { "grpc_endpoint": "0.0.0.0:4317", "http_endpoint": "0.0.0.0:4318" } } } } ``` 1. Armazene a configuração no Systems Manager Parameter Store: 1. Abra as [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 1. Selecione **Criar Parâmetro**. 1. Insira os seguintes valores: + Nome: `/ecs/cwagent/otel-config` + Nível: Padrão + Tipo: string + Tipo de dados: Texto + Valor: [Cole a configuração cw-agent-otel de.json aqui] 1. Crie uma definição de tarefa usando o modo de rede de ponte: Na definição da tarefa, a configuração vai depender do modo de rede que você usa. A rede bridge é o padrão e pode ser usado na sua VPC padrão. Em uma rede bridge, defina a variável de `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` ambiente para informar ao OpenTelemetry SDK qual é o endpoint e a porta do CloudWatch agente. Você também deve criar um link do contêiner do aplicativo para o contêiner do Collector para que os rastreamentos sejam enviados do OpenTelemetry SDK do seu aplicativo para o contêiner do Collector. **Example CloudWatch definição de tarefa do agente** ``` { "containerDefinitions": [ { "name": "cwagent", "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "portMappings": [ { "containerPort": 4318, "hostPort": 4318, "protocol": "tcp" }, { "containerPort": 4317, "hostPort": 4317, "protocol": "tcp" }, { "containerPort": 2000, "hostPort": 2000, "protocol": "tcp" } ], "secrets": [ { "name": "CW_CONFIG_CONTENT", "valueFrom": "/ecs/cwagent/otel-config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["cwagent"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://cwagent:4318/v1/traces" } ] } ] } ``` Para obter mais informações, consulte [Implantação do CloudWatch agente para coletar métricas em nível de instância do Amazon EC2 no Amazon ECS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html). #### Usando o OpenTelemetry coletor 1. Obtenha a imagem do Docker `otel/opentelemetry-collector-contrib` do [Docker Hub](https://hub.docker.com/r/otel/opentelemetry-collector-contrib). 1. Crie um arquivo de configuração chamado `otel-collector-config.yaml` usando o mesmo conteúdo mostrado na seção de **configuração do coletor do Amazon EC2**, mas atualize os endpoints para usar `0.0.0.0` em vez de `127.0.0.1`. 1. Para usar essa configuração no Amazon ECS, você pode armazenar a configuração no Systems Manager Parameter Store. Primeiro, acesse o console do Systems Manager Parameter Store e selecione **Criar novo parâmetro**. Crie um parâmetro com as seguintes informações: + Nome:/ecs/otel/config(esse nome será referenciado na Definição de Tarefa do Coletor) + Nível: Padrão + Tipo: string + Tipo de dados: Texto + Valor: [Cole a configuração otel-collector-config de.yaml aqui] 1. Crie uma definição de tarefa para implantar o OpenTelemetry coletor usando o modo de rede bridge como exemplo. Na definição da tarefa, a configuração vai depender do modo de rede que você usa. A rede bridge é o padrão e pode ser usado na sua VPC padrão. Em uma rede bridge, defina a variável de `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` ambiente para informar ao OpenTelemetry SDK qual é o endpoint e a porta do OpenTelemetry Collector. Você também deve criar um link do contêiner do aplicativo para o contêiner do Collector para que os rastreamentos sejam enviados do OpenTelemetry SDK do seu aplicativo para o contêiner do Collector. **Example OpenTelemetry definição de tarefa de coletor** ``` { "containerDefinitions": [ { "name": "otel-collector", "image": "otel/opentelemetry-collector-contrib", "portMappings": [ { "containerPort": 2000, "hostPort": 2000 }, { "containerPort": 4317, "hostPort": 4317 }, { "containerPort": 4318, "hostPort": 4318 } ], "command": [ "--config", "env:SSM_CONFIG" ], "secrets": [ { "name": "SSM_CONFIG", "valueFrom": "/ecs/otel/config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["otel-collector"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://otel-collector:4318/v1/traces" } ] } ] } ``` ### Migrar no Elastic Beanstalk **Importante** Pare o processo do X-Ray Daemon antes de usar o CloudWatch agente para evitar conflitos de portas. A 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: 1. Crie um diretório chamado `.ebextensions` na raiz do projeto 1. Crie um arquivo denominado `cloudwatch.config` no diretório `.ebextensions` com o conteúdo a seguir: ``` files: "/opt/aws/amazon-cloudwatch-agent/etc/config.json": mode: "0644" owner: root group: root content: | { "traces": { "traces_collected": { "otlp": { "grpc_endpoint": "12.0.0.1:4317", "http_endpoint": "12.0.0.1:4318" } } } } container_commands: start_agent: command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s ``` 1. Inclua o diretório `.ebextensions` no pacote de fontes da aplicação ao implantar 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](elasticbeanstalk/latest/dg/ebextensions.html).