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á. # Configurar o X-Ray SDK para Ruby **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). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry O X-Ray SDK para Ruby tem uma classe chamada `XRay.recorder`, que fornece o gravador global. Você pode configurar o gravador global para personalizar o middleware que cria segmentos para chamadas HTTP de entrada. **Topics** + [Plug-ins de serviço](#xray-sdk-ruby-configuration-plugins) + [Regras de amostragem](#xray-sdk-ruby-configuration-sampling) + [Registro em log](#xray-sdk-ruby-configuration-logging) + [Configuração do gravador no código](#xray-sdk-ruby-configuration-code) + [Configuração do gravador com o rails](#xray-sdk-ruby-middleware-configuration-rails) + [Variáveis de ambiente](#xray-sdk-ruby-configuration-envvars) ## Plug-ins de serviço Use `plugins` para registrar informações sobre o serviço que hospeda o aplicativo. **Plugins** + Amazon EC2: o `ec2` adiciona o ID de instância e a zona de disponibilidade. + Elastic Beanstalk: o `elastic_beanstalk` adiciona o nome do ambiente, o rótulo da versão e o ID de implantação. + Amazon ECS: o `ecs` adiciona o ID do contêiner. ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) Para usar plug-ins, você deve especificá-los no objeto de configuração que passa ao gravador. **Example main.rb: configuração do plug-in** ``` my_plugins = %I[ec2 elastic_beanstalk] config = { plugins: my_plugins, name: 'my app', } XRay.recorder.configure(config) ``` Você também pode usar [variáveis de ambiente](#xray-sdk-ruby-configuration-envvars), que têm precedência sobre valores definidos no código, para configurar o gravador. O SDK também usa as configurações do plug-in para definir o campo `origin` no segmento. Isso indica o tipo de AWS recurso que executa seu aplicativo. Quando você usa vários plug-ins, o SDK usa a seguinte ordem de resolução para determinar a origem: ElasticBeanstalk > EKS > ECS > EC2. ## Regras de amostragem O SDK usa as regras de amostragem que você define no console do X-Ray para determinar quais solicitações serão registradas. A regra padrão rastreia a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais em todos os serviços que enviam rastreamentos ao X-Ray. [Crie regras adicionais no console do X-Ray](xray-console-sampling.md) para personalizar a quantidade de dados registrados para cada uma dos aplicativos. O SDK aplica regras personalizadas na ordem em que elas estão definidas. Se uma solicitação corresponder a várias regras personalizadas, o SDK aplicará somente a primeira regra. **nota** Se o SDK não conseguir acessar o X-Ray para obter regras de amostragem, ele reverterá para uma regra local padrão da primeira solicitação a cada segundo e 5% de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar a amostragem APIs ou não conseguir se conectar ao daemon X-Ray, que atua como um proxy TCP para chamadas de API feitas pelo SDK. Você também pode configurar o SDK para carregar regras de amostragem de um documento JSON. O SDK pode usar regras locais como backup para casos em que a amostragem do X-Ray não está disponível ou usar exclusivamente regras locais. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` Este exemplo define uma regra personalizada e uma regra padrão. A regra personalizada aplica uma taxa de amostragem de 5% sem um número mínimo de solicitações para rastrear os caminhos em `/api/move/`. A regra padrão rastreia a primeira solicitação a cada segundo e 10% das solicitações adicionais. A desvantagem de definir regras localmente é que o destino fixo é aplicado por instância do gravador de forma independente, em vez de ser gerenciado pelo serviço X-Ray. À medida que você implanta mais hosts, a taxa fixa é multiplicada, dificultando o controle da quantidade de dados registrados. Para configurar regras de backup, defina um hash para o documento no objeto de configuração que você passa para o gravador. **Example main.rb: configuração da regra de backup** ``` require 'aws-xray-sdk' my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config) ``` Para armazenar as regras de amostragem de forma independente, defina o hash em um arquivo separado e exija que o arquivo o inclua em seu aplicativo. **Example config/sampling-rules.rb** ``` my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } ``` **Example main.rb: regra de amostragem de um arquivo** ``` require 'aws-xray-sdk' require 'config/sampling-rules.rb' config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config) ``` Para usar apenas regras locais, exija as regras de amostragem e configure o `LocalSampler`. **Example main.rb: amostragem de regra local** ``` require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config) ``` Você também pode configurar o gravador global para desabilitar a amostragem e instrumentar todas as solicitações de entrada. **Example main.rb: desabilitar a amostragem** ``` require 'aws-xray-sdk' config = { sampling: false, name: 'my app', } XRay.recorder.configure(config) ``` ## Registro em log Por padrão, o gravador encaminha os eventos informativos para `$stdout`. Você pode personalizar o registro em log definindo um [registrador](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) no objeto de configuração que você passa para o gravador. **Example main.rb: registrar em log** ``` require 'aws-xray-sdk' config = { logger: my_logger, name: 'my app', } XRay.recorder.configure(config) ``` Use logs de depuração para identificar problemas como subsegmentos não fechados ao [gerar subsegmentos manualmente](xray-sdk-ruby-subsegments.md). ## Configuração do gravador no código Configurações adicionais estão disponíveis no método `configure` no `XRay.recorder`. + `context_missing`: defina como `LOG_ERROR` para evitar o lançamento de exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto. + `daemon_address`: defina o host e a porta do receptor do daemon do X-Ray. + `name`: defina um nome de serviço para o SDK usar para segmentos. + `naming_pattern`: defina um nome de domínio padrão para usar a [nomeação dinâmica](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming). + `plugins`: registre informações sobre os recursos da AWS de sua aplicação com [plug-ins](#xray-sdk-ruby-configuration-plugins). + `sampling`: defina como `false` para desabilitar a amostragem. + `sampling_rules`: defina o hash que contém suas [regras de amostragem](#xray-sdk-ruby-configuration-sampling). **Example main.rb: desabilitar exceções de contexto ausente** ``` require 'aws-xray-sdk' config = { context_missing: 'LOG_ERROR' } XRay.recorder.configure(config) ``` ## Configuração do gravador com o rails Se você usa o framework do Rails, pode configurar as opções do gravador global em um arquivo Ruby em `app_root/initializers`. O X-Ray SDK aceita uma chave de configuração adicional para usar com o Rails. + `active_record`: defina como `true` para registrar os subsegmentos das transações de banco de dados de registros ativos. Defina as configurações disponíveis em um objeto de configuração denominado `Rails.application.config.xray`. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ## Variáveis de ambiente É possível usar variáveis de ambiente para configurar o X-Ray SDK para Ruby. O SDK é compatível com as seguintes variáveis: + `AWS_XRAY_TRACING_NAME`: defina um nome de serviço para o SDK usar para segmentos. Sobrepõe o nome do serviço que você definiu na [estratégia de nomeação de segmentos](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) do filtro do servlet. + `AWS_XRAY_DAEMON_ADDRESS`: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, o SDK envia dados de rastreamento para `127.0.0.1:2000`. Use essa variável se você tiver configurado o daemon para [escutar em uma porta diferente](xray-daemon-configuration.md) ou se ele estiver sendo executado em um host diferente. + `AWS_XRAY_CONTEXT_MISSING`: defina como `RUNTIME_ERROR` para lançar exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto. **Valores válidos** + `RUNTIME_ERROR`: lance uma exceção de tempo de execução. + `LOG_ERROR`: registre um erro e continue (padrão). + `IGNORE_ERROR`: ignore o erro e continue. Erros relativos a segmentos ou subsegmentos ausentes poderão ocorrer quando você tentar usar um cliente instrumentado no código de inicialização que é executado quando nenhuma solicitação estiver aberta ou em um código que gere um novo thread. As variáveis de ambiente substituem os valores definidos no código.