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á. # Migrar para Ruby OpenTelemetry Para migrar seus aplicativos Ruby do X-Ray SDK para a OpenTelemetry instrumentação, use os seguintes exemplos de código e orientações para instrumentação manual. **Topics** + [Instrumente manualmente suas soluções com o SDK](#manual-instrumentation-ruby) + [Rastrear solicitações recebidas (instrumentação Rails)](#tracing-incoming-requests-ruby) + [AWS Instrumentação do SDK](#aws-sdk-instrumentation-ruby) + [Instrumentar chamadas HTTP de saída](#http-instrumentation-ruby) + [Suporte de instrumentação para outras bibliotecas](#xray-migration-libraries-ruby) + [Criar dados de rastreamento manualmente](#manual-trace-creation-ruby) + [Instrumentação manual Lambda](#lambda-instrumentation-ruby) ## Instrumente manualmente suas soluções com o SDK ------ #### [ Tracing setup with X-Ray SDK ] O SDK do X-Ray para Ruby exigia que você configurasse seu código com plug-ins de serviço. ``` require 'aws-xray-sdk' XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk]) ``` ------ #### [ Tracing setup with OpenTelemetry SDK ] **nota** No momento, a amostragem remota X-Ray não está disponível para ser configurada para OpenTelemetry Ruby. Para um aplicativo Ruby on Rails, coloque seu código de configuração em um inicializador Rails. Para obter mais informações, consulte [Conceitos básicos do ](https://opentelemetry.io/docs/languages/ruby/getting-started/#initialization). Para todos os programas Ruby instrumentados manualmente, você deve usar o `OpenTelemetry::SDK.configure` método para configurar o SDK do OpenTelemetry Ruby. Primeiro, instale os seguintes pacotes: ``` bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray ``` Em seguida, configure o OpenTelemetry SDK por meio do código de configuração que é executado quando o programa é inicializado. É recomendável configurar os seguintes componentes: + `OTLP Exporter`— Necessário para exportar traços para o CloudWatch agente e coletor OpenTelemetry + `An AWS X-Ray Propagator`— Necessário para propagar o contexto de rastreamento para AWS serviços integrados ao X-Ray ``` require 'opentelemetry-sdk' require 'opentelemetry-exporter-otlp' # Import the gem containing the AWS X-Ray for OTel Ruby ID Generator and propagator require 'opentelemetry-propagator-xray' OpenTelemetry::SDK.configure do |c| c.service_name = 'my-service-name' c.add_span_processor( # Use the BatchSpanProcessor to send traces in groups instead of one at a time OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new( # Use the default OLTP Exporter to send traces to the ADOT Collector OpenTelemetry::Exporter::OTLP::Exporter.new( # The OpenTelemetry Collector is running as a sidecar and listening on port 4318 endpoint:"http://127.0.0.1:4318/v1/traces" ) ) ) # The X-Ray Propagator injects the X-Ray Tracing Header into downstream calls c.propagators = [OpenTelemetry::Propagator::XRay::TextMapPropagator.new] end ``` OpenTelemetry SDKs também têm o conceito de instrumentações de biblioteca. Habilitá-los criará automaticamente extensões para bibliotecas como o AWS SDK. OpenTelemetry fornece a opção de ativar todas as instrumentações da biblioteca ou especificar quais instrumentações da biblioteca devem ser ativadas. Para habilitar todas as instrumentações, primeiro instale o pacote `opentelemetry-instrumentation-all`: ``` bundle add opentelemetry-instrumentation-all ``` Em seguida, atualize a configuração para habilitar todas as instrumentações de biblioteca, conforme mostrado abaixo: ``` require 'opentelemetry/instrumentation/all' ... OpenTelemetry::SDK.configure do |c| ... c.use_all() # Enable all instrumentations end ``` OpenTelemetry SDKs também têm o conceito de instrumentações de biblioteca. Habilitá-los criará automaticamente extensões para bibliotecas como o AWS SDK. OpenTelemetry fornece a opção de ativar todas as instrumentações da biblioteca ou especificar quais instrumentações da biblioteca devem ser ativadas. Para habilitar todas as instrumentações, primeiro instale o pacote `opentelemetry-instrumentation-all`: ``` bundle add opentelemetry-instrumentation-all ``` Em seguida, atualize a configuração para habilitar todas as instrumentações de biblioteca, conforme mostrado abaixo: ``` require 'opentelemetry/instrumentation/all' ... OpenTelemetry::SDK.configure do |c| ... c.use_all() # Enable all instrumentations end ``` ------ ## Rastrear solicitações recebidas (instrumentação Rails) ------ #### [ With X-Ray SDK ] Com o SDK do X-Ray, o rastreamento do X-Ray é configurado para a estrutura do Rails na inicialização. **Exemplo** — config/initializers/aws \_xray.rb ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ------ #### [ With OpenTelemetry SDK ] Primeiro, instale os seguintes pacotes: ``` bundle add opentelemetry-instrumentation-rack opentelemetry-instrumentation-rails opentelemetry-instrumentation-action_pack opentelemetry-instrumentation-active_record opentelemetry-instrumentation-action_view ``` Em seguida, atualize a configuração para habilitar a instrumentação para sua aplicação Rails, conforme mostrado abaixo: ``` # During SDK configuration OpenTelemetry::SDK.configure do |c| ... c.use 'OpenTelemetry::Instrumentation::Rails' c.use 'OpenTelemetry::Instrumentation::Rack' c.use 'OpenTelemetry::Instrumentation::ActionPack' c.use 'OpenTelemetry::Instrumentation::ActiveSupport' c.use 'OpenTelemetry::Instrumentation::ActionView' ... end ``` ------ ## AWS Instrumentação do SDK ------ #### [ With X-Ray SDK ] Para instrumentar as AWS solicitações de saída do AWS SDK, os clientes do AWS SDK são corrigidos com X-Ray, como no exemplo a seguir: ``` require 'aws-xray-sdk' require 'aws-sdk-s3' # Patch AWS SDK clients XRay.recorder.configure(plugins: [:aws_sdk]) # Use the instrumented client s3 = Aws::S3::Client.new s3.list_buckets ``` ------ #### [ With OpenTelemetry SDK ] AWS O SDK for Ruby V3 fornece suporte para gravação e emissão de traços. OpenTelemetry Para obter informações sobre como configurar um cliente de serviço, consulte [Configuração de recursos de observabilidade no AWS SDK OpenTelemetry for Ruby](sdk-for-ruby/v3/developer-guide/observability.html). ------ ## Instrumentar chamadas HTTP de saída Ao fazer chamadas HTTP para serviços externos, talvez seja necessário instrumentar manualmente as chamadas se a instrumentação automática não estiver disponível ou não informar detalhes suficientes. ------ #### [ With X-Ray SDK ] Para instrumentar chamadas downstream, o SDK do X-Ray para Ruby foi usado para aplicar patches à biblioteca `net/http` usada pela aplicação: ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http] } XRay.recorder.configure(config) ``` ------ #### [ With OpenTelemetry SDK ] Para habilitar o uso da `net/http` instrumentação OpenTelemetry, primeiro instale o `opentelemetry-instrumentation-net_http` pacote: ``` bundle add opentelemetry-instrumentation-net_http ``` Em seguida, atualize a configuração para habilitar a instrumentação de `net/http`, conforme mostrado abaixo: ``` OpenTelemetry::SDK.configure do |c| ... c.use 'OpenTelemetry::Instrumentation::Net::HTTP' ... end ``` ------ ## Suporte de instrumentação para outras bibliotecas Você pode encontrar a lista completa de instrumentações de biblioteca suportadas para OpenTelemetry Ruby em. [opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation) Como alternativa, você pode pesquisar no OpenTelemetry Registro para descobrir se OpenTelemetry suporta instrumentação. Para obter mais informações, consulte [Registry](https://opentelemetry.io/ecosystem/registry/). ## Criar dados de rastreamento manualmente ------ #### [ With X-Ray SDK ] Ao usar o X-Ray, o pacote `aws-xray-sdk` necessário para criar manualmente segmentos e seus subsegmentos filho para rastrear sua aplicação. Você também pode ter adicionado anotações e metadados do X-Ray aos seus segmentos ou subsegmentos: ``` require 'aws-xray-sdk' ... # Start a segment segment = XRay.recorder.begin_segment('my-service') # Add annotations (indexed key-value pairs) segment.annotations[:user_id] = 'user-123' segment.annotations[:payment_status] = 'completed' # Add metadata (non-indexed data) segment.metadata[:order] = { id: 'order-456', items: [ { product_id: 'prod-1', quantity: 2 }, { product_id: 'prod-2', quantity: 1 } ], total: 67.99 } # Add metadata to a specific namespace segment.metadata(namespace: 'payment') do |metadata| metadata[:transaction_id] = 'tx-789' metadata[:payment_method] = 'credit_card' end # Create a subsegment with annotations and metadata segment.subsegment('payment-processing') do |subsegment1| subsegment1.annotations[:payment_id] = 'pay-123' subsegment1.metadata[:details] = { amount: 67.99, currency: 'USD' } # Create a nested subsegment subsegment1.subsegment('operation-2') do |subsegment2| # Do more work... end end # Close the segment segment.close ``` ------ #### [ With OpenTelemetry SDK ] Você pode usar extensões personalizadas para monitorar o desempenho de atividades internas que não são capturadas pelas bibliotecas de instrumentação. Somente extensões do tipo Servidor são convertidas em segmentos do X-Ray. Todas as outras extensões são convertidas em subsegmentos do X-Ray. Por padrão, as extensões são `INTERNAL`. Primeiro, crie um Rastreador para gerar extensões, que podem ser obtidas por meio do método `OpenTelemetry.tracer_provider.tracer('')`. Isso fornecerá uma instância do Tracer registrada globalmente na OpenTelemetry configuração do seu aplicativo. É comum ter um único rastreador para um aplicativo inteiro. Crie um OpenTelemetry rastreador e use-o para criar extensões: ``` require 'opentelemetry-sdk' ... # Get a tracer tracer = OpenTelemetry.tracer_provider.tracer('my-application') # Create a server span (equivalent to X-Ray segment) tracer.in_span('my-application', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span| # Do work... # Create nested spans of default kind INTERNAL will become an X-Ray subsegment tracer.in_span('operation-1') do |child_span1| # Set attributes (equivalent to X-Ray annotations and metadata) child_span1.set_attribute('key', 'value') # Do more work... tracer.in_span('operation-2') do |child_span2| # Do more work... end end end ``` **Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry ** Use o método `set_attribute` para adicionar atributos a cada extensão. Por padrão, todos esses atributos de extensão serão convertidos em metadados nos dados brutos do X-Ray. Para garantir que um atributo seja convertido em uma anotação, e não em metadados, adicione a chave desses atributos à lista do atributo `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). ``` # SERVER span will become an X-Ray segment tracer.in_span('my-server-operation', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span| # Your server logic here span.set_attribute('attribute.key', 'attribute.value') span.set_attribute("metadataKey", "metadataValue") span.set_attribute("annotationKey1", "annotationValue") # Create X-Ray annotations span.set_attribute("aws.xray.annotations", ["annotationKey1"]) end ``` ------ ## Instrumentação manual Lambda ------ #### [ With X-Ray SDK ] Depois que o *Rastreamento ativo* for habilitado no Lambda, não haverá necessidade de configurações adicionais para usar o SDK do X-Ray. O Lambda criará um segmento representando a invocação do manipulador do Lambda, e você poderá criar subsegmentos ou bibliotecas de instrumentos usando o SDK do X-Ray sem nenhuma configuração adicional. ------ #### [ With OpenTelemetry SDK ] Considere o seguinte exemplo de código de função do Lambda (sem instrumentação): ``` require 'json' def lambda_handler(event:, context:) # TODO implement { statusCode: 200, body: JSON.generate('Hello from Lambda!') } end ``` Para instrumentar manualmente seu Lambda, é necessário: 1. Adicionar os seguintes gems para seu Lambda ``` gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-propagator-xray' gem 'aws-distro-opentelemetry-exporter-xray-udp' gem 'opentelemetry-instrumentation-aws_lambda' gem 'opentelemetry-propagator-xray', '~> 0.24.0' # Requires version v0.24.0 or higher ``` 1. Inicialize o OpenTelemetry SDK fora do seu Lambda Handler. Recomenda-se que o OpenTelemetry SDK seja configurado com: 1. Um processador de extensões simples com um exportador de extensões do UDP do X-Ray para enviar rastreamentos ao endpoint UDP X-Ray do Lambda 1. Um propagador do X-Ray Lambda 1. Configuração de `service_name` a ser definida para o nome da função do Lambda 1. Na sua classe de manipulador Lambda, adicione as seguintes linhas para instrumentar seu manipulador Lambda: ``` class Handler extend OpenTelemetry::Instrumentation::AwsLambda::Wrap ... instrument_handler :process end ``` O código a seguir demonstra a função do Lambda após as alterações necessárias. Você pode criar extensões personalizadas adicionais para complementar as extensões fornecidas automaticamente. ``` require 'json' require 'opentelemetry-sdk' require 'aws/distro/opentelemetry/exporter/xray/udp' require 'opentelemetry/propagator/xray' require 'opentelemetry/instrumentation/aws_lambda' # Initialize OpenTelemetry SDK outside handler OpenTelemetry::SDK.configure do |c| # Configure the AWS Distro for OpenTelemetry X-Ray Lambda exporter c.add_span_processor( OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new( AWS::Distro::OpenTelemetry::Exporter::XRay::UDP::AWSXRayUDPSpanExporter.new ) ) # Configure X-Ray Lambda propagator c.propagators = [OpenTelemetry::Propagator::XRay.lambda_text_map_propagator] # Set minimal resource information c.resource = OpenTelemetry::SDK::Resources::Resource.create({ OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => ENV['AWS_LAMBDA_FUNCTION_NAME'] }) c.use 'OpenTelemetry::Instrumentation::AwsLambda' end module LambdaFunctions class Handler extend OpenTelemetry::Instrumentation::AwsLambda::Wrap def self.process(event:, context:) "Hello!" end instrument_handler :process end end ``` ------ Veja a seguir um exemplo de mapa de rastreamento de uma função do Lambda instrumentada escrita no Ruby. ![Mapa de rastreamento no CloudWatch console para Ruby.](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/deprecation_ruby.png) Você também pode usar camadas Lambda OpenTelemetry para configurar seu Lambda. Para obter mais informações, consulte Instrumentação [OpenTelemetry AWS-Lambda](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_lambda#usage).