使用 SDK 手动分析您的解决方案跟踪传入的请求（Rails 工具）Amazon 软件开发工具包工具检测传出 HTTP 调用对其他库的仪器支持手动创建跟踪数据 Lambda 手动检测

迁移到 OpenTelemetry Ruby

要将 Ruby 应用程序从 X-Ray SDK 迁移到 OpenTelemetry 检测中，请使用以下代码示例和手动检测指南。

Sections

使用 SDK 手动分析您的解决方案
跟踪传入的请求（Rails 工具）
Amazon 软件开发工具包工具
检测传出 HTTP 调用
对其他库的仪器支持
手动创建跟踪数据
Lambda 手动检测

使用 SDK 手动分析您的解决方案

Tracing setup with X-Ray SDK

适用于 Ruby 的 X-Ruby SDK 要求您使用服务插件配置代码。


require 'aws-xray-sdk'

XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk])

Tracing setup with OpenTelemetry SDK

注意

目前无法为 OpenTelemetry Ruby 配置 X-Ray 远程采样。

对于 Ruby on Rails 应用程序，请将配置代码放在 Rails 初始化器中。有关更多信息，请参阅入门。对于所有手动检测的 Ruby 程序，必须使用该OpenTelemetry::SDK.configure方法来配置 OpenTelemetry Ruby SDK。

首先，安装以下软件包：


bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray

接下来，通过程序初始化时运行的配置代码配置 OpenTelemetry SDK。建议您配置以下组件：

OTLP Exporter— 将轨迹导出到 CloudWatch 代理和 OpenTelemetry 采集器时需要
An Amazon X-Ray Propagator— 需要将跟踪上下文传播到与 X-Ray 集成的 Amazon 服务


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 也有图书馆仪器的概念。启用这些功能将自动为 Amazon SDK 等库创建跨度。 OpenTelemetry 提供了启用所有库乐器或指定要启用哪些库乐器的选项。

要启用所有工具，请先安装软件包：opentelemetry-instrumentation-all


bundle add opentelemetry-instrumentation-all

接下来，更新配置以启用所有库工具，如下所示：


require 'opentelemetry/instrumentation/all'
...

OpenTelemetry::SDK.configure do |c|
   ...

  c.use_all() # Enable all instrumentations
end

要启用所有工具，请先安装软件包：opentelemetry-instrumentation-all


bundle add opentelemetry-instrumentation-all

接下来，更新配置以启用所有库工具，如下所示：


require 'opentelemetry/instrumentation/all'
...

OpenTelemetry::SDK.configure do |c|
   ...

  c.use_all() # Enable all instrumentations
end

跟踪传入的请求（Rails 工具）

Amazon 软件开发工具包工具

检测传出 HTTP 调用

在对外部服务进行 HTTP 调用时，如果自动检测不可用或无法提供足够的细节，则可能需要手动检测调用。

对其他库的仪器支持

你可以在下面找到 OpenTelemetry Ruby 支持的库工具的完整列表。opentelemetry-ruby-contrib

或者，您可以搜索 OpenTelemetry 注册表以了解是否 OpenTelemetry 支持检测。有关更多信息，请参阅注册表。

手动创建跟踪数据

With X-Ray SDK

使用 X-Ray，该aws-xray-sdk软件包要求您手动创建区段及其子子分段来跟踪您的应用程序。您可能还为区段或子分段添加了 X-Ray 注释和元数据：


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

您可以使用自定义跨度来监控未被仪器库捕获的内部活动的性能。请注意，只有服务器类型的跨度才会转换为 X-Ray 分段，所有其他跨度都会转换为 X-Ray 子分段。默认情况下，跨度为。INTERNAL

首先，创建一个 Tracer 以生成跨度，你可以通过该OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>')方法获得跨度。这将提供一个在您的应用程序 OpenTelemetry 配置中全局注册的 Tracer 实例。通常对整个应用程序使用一个 Tracer。创建一个 OpenTelemetry 示踪器并用它来创建跨度：


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

使用 OpenTelemetry SDK 向跟踪添加注释和元数据

使用set_attribute方法向每个跨度添加属性。请注意，默认情况下，所有这些跨度属性都将转换为 X-Ray 原始数据中的元数据。为确保将属性转换为注释而不是元数据，可以将该属性键添加到aws.xray.annotations属性列表中。有关更多信息，请参见启用自定义 X-Ray 注释。


# 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

Lambda 手动检测

With X-Ray SDK

在 Lambda 上启用主动跟踪后，无需进行其他配置即可使用 X-Ray SDK。Lambda 将创建一个表示 Lambda 处理程序调用的区段，您无需任何额外配置即可使用 X-Ray SDK 创建子分段或仪器库。

With OpenTelemetry SDK

考虑以下 Lambda 函数代码示例（不带插入）：


require 'json'
def lambda_handler(event:, context:)
    # TODO implement
    { statusCode: 200, body: JSON.generate('Hello from Lambda!') }
end

要手动检测您的 Lambda，您需要：

为你的 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

在 Lambda 处理程序之外初始化 OpenTelemetry 开发工具包。建议将 S OpenTelemetry DK 配置为：
1. 一个带有 X-Ray UDP 跨度导出器的简单跨度处理器，用于向 Lambda 的 UDP X-Ray 端点发送跟踪
2. X-Ray Lambda 传播器
3. service_name要设置为 Lambda 函数名称的配置

在您的 Lambda 处理程序类中，添加以下几行来检测您的 Lambda 处理程序：


  class Handler
        extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
        ...

        instrument_handler :process
    end

以下代码演示了进行必要更改后的 Lambda 函数。您可以创建其他自定义跨度来补充自动提供的跨度。


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

以下是用 Ruby 编写的带检测的 Lambda 函数的示例。

您也可以使用 Lambda 层为您的 Lambda OpenTelemetry 进行配置。有关更多信息，请参阅 OpenTelemetry AWS-Lambda 工具。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

迁移到 OpenTelemetry Python

使用创建 X-Ray 资源 CloudFormation