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á. # AWS 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 é uma biblioteca para aplicações web do Ruby que fornece classes e métodos para gerar e enviar dados de rastreamento ao daemon do X-Ray. Os dados de rastreamento incluem informações sobre solicitações HTTP recebidas pelo aplicativo e chamadas que o aplicativo faz para serviços downstream usando o AWS SDK, clientes HTTP ou um cliente de registro ativo. Você também pode criar segmentos manualmente e adicionar informações de depuração em anotações e metadados. Você pode baixar do SDK, adicionando-o ao seu gemfile e executando `bundle install`. **Example Gemfile** ``` gem 'aws-sdk' ``` Se você usa o Rails, primeiro [adicione o middleware do X-Ray SDK](xray-sdk-ruby-middleware.md) para rastrear solicitações de entrada. Um filtro de solicitação cria um [segmento](xray-concepts.md#xray-concepts-segments). Embora o segmento esteja aberto, você pode usar os métodos do cliente do SDK para adicionar informações ao segmento e criar subsegmentos para rastrear as chamadas subsequentes. O SDK também registra automaticamente exceções que seu aplicativo lança enquanto o segmento está aberto. Para aplicativos que não sejam Rails, você pode [criar segmentos manualmente](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual). Em seguida, use o X-Ray SDK para instrumentar seus AWS SDK para Ruby clientes HTTP e SQL [configurando o gravador para corrigir as](xray-sdk-ruby-patching.md) bibliotecas associadas. Sempre que você faz uma chamada para um downstream AWS service (Serviço da AWS) ou recurso com um cliente instrumentado, o SDK registra as informações sobre a chamada em um subsegmento. Serviços da AWS e os recursos que você acessa nos serviços aparecem como nós downstream no mapa de rastreamento para ajudá-lo a identificar erros e problemas de limitação em conexões individuais. Assim que você começar a usar o SDK, personalize seu comportamento [configurando o gravador](xray-sdk-ruby-configuration.md). Você pode adicionar plug-ins para registrar dados sobre os recursos de computação que executam seu aplicativo, personalizar o comportamento de amostragem definindo as regras de amostragem e fornecer um registrador para ver mais ou menos informações do SDK nos logs do seu aplicativo. Registre informações adicionais sobre as solicitações e o trabalho que o a aplicação faz em [anotações e metadados](xray-sdk-ruby-segment.md). Anotações são simples pares de chave-valor que são indexados para serem usados com [expressões de filtro](xray-console-filters.md) para que você possa pesquisar rastreamentos que contêm dados específicos. As entradas de metadados são menos restritivas e podem registrar matrizes e objetos inteiros: tudo o que pode ser serializado em JSON. **Anotações e metadados** Anotações e metadados são textos arbitrários que você adiciona aos segmentos com o X-Ray SDK. As anotações são indexadas para serem usadas com expressões de filtro. Os metadados não são indexados, mas podem ser visualizados no segmento bruto com o console ou a API do X-Ray. Qualquer pessoa à qual você conceder acesso de leitura ao X-Ray poderá visualizar esses dados. Quando há uma grande quantidade de clientes instrumentados no código, um único segmento de solicitação pode conter um grande número de subsegmentos, um para cada chamada feita com um cliente instrumentado. Você pode organizar e agrupar subsegmentos integrando chamadas de clientes em [subsegmentos personalizados](xray-sdk-ruby-subsegments.md). Você pode criar um subsegmento personalizado para uma função inteira ou qualquer seção de código e registrar metadados e anotações no subsegmento em vez de gravar tudo no segmento principal. Para documentação de referência para as classes e métodos do SDK, consulte a [Referência de API do AWS X-Ray X-Ray SDK para Ruby](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference). ## Requisitos O X-Ray SDK requer o Ruby 2.3 ou posterior e é compatível com as seguintes bibliotecas: + AWS SDK para Ruby versão 3.0 ou posterior + Rails versão 5.1 ou posterior # 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. # Rastrear solicitações de entrada com o middleware do 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 Você pode usar o X-Ray SDK para rastrear solicitações HTTP recebidas que seu aplicativo atende em uma instância do EC2 no Amazon EC2 ou no Amazon ECS. AWS Elastic Beanstalk Se você usa o Rails, use o middleware do Rails para instrumentar as solicitações HTTP de entrada. Quando você adiciona o middleware ao aplicativo e configura o nome do segmento, o X-Ray SDK para Ruby cria um segmento para cada solicitação amostrada. Todos os segmentos criados por instrumentação adicional tornam-se subsegmentos do segmento em nível da solicitação que fornecem informações sobre solicitação e resposta HTTP. Essas informações incluem tempo, método e disposição da solicitação. Cada segmento tem um nome que identifica a aplicação no mapa de serviços. O segmento pode ser nomeado estaticamente ou você pode configurar o SDK para nomeá-lo dinamicamente com base no cabeçalho do host na solicitação de entrada. A nomeação dinâmica permite agrupar rastreamentos com base no nome de domínio na solicitação e aplicar um nome padrão se o nome não corresponder ao padrão esperado (por exemplo, se o cabeçalho do host for falsificado). **Solicitações encaminhadas** Se um balanceador de carga ou outro intermediário encaminhar uma solicitação para o aplicativo, o X-Ray obterá o IP do cliente do cabeçalho `X-Forwarded-For` na solicitação em vez do IP de origem no pacote IP. O IP do cliente registrado para uma solicitação encaminhada pode ser falsificado; portanto, não é digno de confiança. Quando uma solicitação é encaminhada, o SDK define um campo adicional no segmento para indicar isso. Se o segmento tiver o campo `x_forwarded_for` definido como `true`, isso significa que o IP do cliente foi obtido no cabeçalho `X-Forwarded-For` na solicitação HTTP. O middleware cria um segmento para cada solicitação de entrada com um bloco `http` contendo as seguintes informações: + **Método HTTP**: GET, POST, PUT, DELETE etc. + **Endereço do cliente**: o endereço IP do cliente que enviou a solicitação. + **Código de resposta**: o código de resposta HTTP da solicitação concluída. + **Horário**: a hora de início (quando a solicitação foi recebida) e a hora de término (quando a resposta foi enviada). + **Agente do usuário**: o `user-agent` da solicitação. + **Tamanho do conteúdo**: o `content-length` da resposta. ## Como usar o middleware do Rails Para usar o middleware, atualize o gemfile para incluir o [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html) necessário. **Example Gemfile: rails** ``` gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie'] ``` Para usar o middleware, você também deve [configurar o gravador](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails) com um nome que representa a aplicação no mapa de rastreamento. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app' } ``` ## Instrumentação de código manual Se você não usa o Rails, crie os segmentos manualmente. Você pode criar um segmento para cada solicitação recebida ou criar segmentos em torno de clientes HTTP ou AWS SDK corrigidos para fornecer contexto para que o gravador adicione subsegmentos. ``` # Start a segment segment = XRay.recorder.begin_segment 'my_service' # Start a subsegment subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote' # Add metadata or annotation here if necessary my_annotations = { k1: 'v1', k2: 1024 } segment.annotations.update my_annotations # Add metadata to default namespace subsegment.metadata[:k1] = 'v1' # Set user for the segment (subsegment is not supported) segment.user = 'my_name' # End segment/subsegment XRay.recorder.end_subsegment XRay.recorder.end_segment ``` ## Configurar uma estratégia de nomeação de segmentos AWS X-Ray usa um *nome de serviço* para identificar seu aplicativo e diferenciá-lo dos outros aplicativos, bancos de dados APIs, AWS recursos externos e que seu aplicativo usa. Quando o X-Ray SDK gera segmentos para solicitações recebidas, ele registra o nome do serviço do aplicativo no [campo de nome](xray-api-segmentdocuments.md#api-segmentdocuments-fields) do segmento. O X-Ray SDK pode nomear segmentos com o nome do host no cabeçalho da solicitação HTTP. No entanto, esse cabeçalho pode ser falsificado, o que pode resultar em nós inesperados no mapa de serviço. Para evitar que o SDK nomeie segmentos incorretamente devido a solicitações com cabeçalhos de host falsificados, você deve especificar um nome padrão para as solicitações recebidas. Se o aplicativo atende a solicitações para vários domínios, você pode configurar o SDK para usar uma estratégia de nomeação dinâmica para refletir isso nos nomes dos segmentos. Uma estratégia de nomeação dinâmica permite que o SDK use o nome do host para solicitações que correspondam a um padrão esperado e aplique o nome padrão às solicitações que não correspondem. Por exemplo, você pode ter uma único aplicativo para atender a solicitações para três subdomínios: `www.example.com`, `api.example.com` e `static.example.com`. Você pode usar uma estratégia de nomeação dinâmica com o padrão `*.example.com` a fim de identificar segmentos para cada subdomínio com um nome diferente, o que resulta em três nós de serviço no mapa de serviços. Se a aplicação receber solicitações com um nome de host que não corresponda ao padrão, você verá um quarto nó no mapa de serviços com um nome alternativo especificado por você. Para usar o mesmo nome para todos os segmentos de solicitação, especifique o nome da aplicação ao configurar o gravador, conforme mostrado nas [seções anteriores](#xray-sdk-ruby-middleware-rails). Uma estratégia de nomeação dinâmica define um padrão com o qual os nomes de host devem corresponder e um nome padrão a ser usado se o nome do host na solicitação HTTP não corresponder ao padrão. Para nomear segmentos dinamicamente, especifique um padrão de nomeação no hash do config. **Example main.rb: nomeação dinâmica** ``` config = { naming_pattern: '*mydomain*', name: 'my app', } XRay.recorder.configure(config) ``` Você pode usar '\$1' no padrão para fazer a correspondência com qualquer string ou '?' para um caractere único. **nota** Você pode sobrepor o nome do serviço padrão que definiu no código com a [variável de ambiente](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars) `AWS_XRAY_TRACING_NAME`. # Aplicar patches a bibliotecas para instrumentar chamadas downstream **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 Para instrumentar chamadas subsequentes, use o X-Ray SDK para Ruby para aplicar patches às bibliotecas usadas pela aplicação. O X-Ray SDK para Ruby pode corrigir as bibliotecas a seguir. **Bibliotecas com suporte** + `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)`: instrumentar clientes HTTP. + `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)`— AWS SDK para Ruby Clientes de instrumentos. Quando você usa uma biblioteca com patches aplicados, o X-Ray SDK para Ruby cria um subsegmento para a chamada e registra as informações da solicitação e da resposta. O segmento deve estar disponível para que o SDK crie o subsegmento do middleware do SDK ou de uma chamada para `XRay.recorder.begin_segment`. Quanto às bibliotecas de patches, é necessário especificá-las no objeto de configuração que você passa ao gravador do X-Ray. **Example main.rb: bibliotecas de patches** ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http aws_sdk] } XRay.recorder.configure(config) ``` # Rastreando chamadas AWS do SDK com o X-Ray SDK for 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 [Quando seu aplicativo faz chamadas Serviços da AWS para armazenar dados, gravar em uma fila ou enviar notificações, o X-Ray SDK for Ruby rastreia as chamadas downstream em subsegmentos.](xray-sdk-ruby-subsegments.md) Os recursos rastreados Serviços da AWS e que você acessa nesses serviços (por exemplo, um bucket do Amazon S3 ou uma fila do Amazon SQS) aparecem como nós downstream no mapa de rastreamento no console X-Ray. O X-Ray SDK for Ruby AWS instrumenta automaticamente todos os clientes SDK [quando você](xray-sdk-ruby-patching.md) corrige a biblioteca. `aws-sdk` Você não pode instrumentar clientes individuais. Para todos os serviços, o nome da API chamada no console do X-Ray pode ser visto. Para um subconjunto de serviços, o X-Ray SDK adiciona informações ao segmento para fornecer maior detalhamento no mapa de serviços. Por exemplo, quando você faz uma chamada com um cliente instrumentado do DynamoDB, o SDK adiciona o nome da tabela ao segmento para chamadas direcionadas a uma tabela. No console, cada tabela aparece como um nó separado no mapa de serviços, com um nó genérico do DynamoDB para chamadas não direcionadas a uma tabela. **Example Subsegmento para uma chamada ao DynamoDB para salvar um item** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` Ao acessar recursos nomeados, as chamadas para os serviços os seguir criam nós adicionais no mapa de serviço. As chamadas que não apontam para recursos específicos criam um nó genérico para o serviço. + **Amazon DynamoDB**: nome da tabela + **Amazon Simple Storage Service**: nome de chave e bucket + **Amazon Simple Queue Service**: nome da fila # Gerar subsegmentos personalizados com o X-Ray SDK **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 Os subsegmentos estendem o [segmento](xray-concepts.md#xray-concepts-segments) de um rastreamento com detalhes sobre o trabalho realizado para atender a uma solicitação. Sempre que você faz uma chamada com um cliente instrumentado, o X-Ray SDK registra as informações geradas em um subsegmento. Você pode criar subsegmentos adicionais para agrupar outros subsegmentos, medir o desempenho de uma seção do código ou registrar anotações e metadados. Para gerenciar subsegmentos, use os métodos `begin_subsegment` e `end_subsegment`. ``` subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote' my_annotations = { id: 12345 } subsegment.annotations.update my_annotations XRay.recorder.end_subsegment ``` Para criar um subsegmento para uma função, encapsule-o em uma chamada para `XRay.recorder.capture`. ``` XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' resp end ``` Quando você cria um subsegmento dentro de um segmento ou outro subsegmento, o X-Ray SDK gera um ID para ele e registra a hora de início e de término. **Example Subsegmento com metadados** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` # Adicionar anotações e metadados aos segmentos com 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 Você pode registrar informações adicionais sobre solicitações, o ambiente ou o aplicativo com anotações e metadados. Também é possível adicionar anotações e metadados aos segmentos que o X-Ray SDK cria ou aos subsegmentos personalizados que você cria. **Anotações** são pares de chave-valor com valores boolianos, de string ou número. As anotações são indexadas para serem usadas com [expressões de filtro](xray-console-filters.md). Use anotações para registrar dados que você deseja usar para agrupar rastreamentos no console ou ao chamar a API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). **Metadados** são pares chave-valor que podem ter valores de qualquer tipo, incluindo objetos e listas, mas não são indexados para uso com expressões de filtro. Use metadados para registrar dados adicionais que você deseja armazenar no rastreamento e não precisa usar com a pesquisa. Além de anotações e metadados, você também pode [registrar strings de ID de usuário](#xray-sdk-ruby-segment-userid) em segmentos. IDs Os usuários são registrados em um campo separado nos segmentos e são indexados para uso com a pesquisa. **Topics** + [Registrar anotações com o X-Ray SDK para Ruby](#xray-sdk-ruby-segment-annotations) + [Registrar metadados com o X-Ray SDK para Ruby](#xray-sdk-ruby-segment-metadata) + [Gravando usuário IDs com o X-Ray SDK for Ruby](#xray-sdk-ruby-segment-userid) ## Registrar anotações com o X-Ray SDK para Ruby Use anotações para registrar informações em segmentos ou subsegmentos que você deseja indexar para pesquisa. **Requisitos de anotação** + **Chaves**: a chave para uma anotação do X-Ray pode ter até 500 caracteres alfanuméricos. Você não pode usar espaços ou símbolos que não sejam um ponto (.) + **Valores**: o valor de uma anotação do X-Ray pode ter até 1.000 caracteres Unicode. + O número de **anotações**: você pode usar até cinquenta anotações por rastreamento. **Como registrar anotações** 1. Obtenha uma referência para o segmento ou subsegmento atual no `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` ou ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Chame `update` com um valor de hash. ``` my_annotations = { id: 12345 } document.annotations.update my_annotations ``` Veja a seguir um exemplo que mostra como chamar `update` com uma chave de anotação que contém um ponto. ``` my_annotations = { testkey.test: 12345 } document.annotations.update my_annotations ``` O SDK registra anotações como pares de chave-valor em um objeto `annotations` no documento de segmentos. Chamar `add_annotations` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento. Para encontrar rastreamentos que têm anotações com valores específicos, use a palavra-chave `annotation[key]` em uma [expressão de filtro](xray-console-filters.md). ## Registrar metadados com o X-Ray SDK para Ruby Use metadados para registrar informações em segmentos ou subsegmentos dos quais você não precisa indexados para pesquisa. Valores de metadados podem ser strings, números, boolianos ou qualquer objeto que possa ser serializado em uma matriz ou objeto JSON. **Como registrar metadados** 1. Obtenha uma referência para o segmento ou subsegmento atual no `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` ou ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Chame `metadata` com uma chave de string, um booliano, um número, uma string ou valor de objeto e um namespace de string. ``` my_metadata = { my_namespace: { key: 'value' } } subsegment.metadata my_metadata ``` Chamar `metadata` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento. ## Gravando usuário IDs com o X-Ray SDK for Ruby Registre o usuário IDs nos segmentos da solicitação para identificar o usuário que enviou a solicitação. **Para gravar usuário IDs** 1. Obtenha uma referência para o segmento atual em `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. Defina o campo do usuário no segmento com o ID da string do usuário que enviou a solicitação. ``` segment.user = 'U12345' ``` Você pode configurar o usuário em seus controladores para registrar o ID de usuário assim que o aplicativo começar a processar uma solicitação. Para encontrar rastreamentos para um ID de usuário, use a `user` palavra-chave em uma [expressão de filtragem](xray-console-filters.md).