为服务客户端配置 OTelProvider 为所有服务客户端配置 OTelProvider 配置自定义遥测提供程序跨度属性

在适用于 Ruby 的 Amazon SDK 中配置可观测性功能

可观测性是指可以根据系统发出的数据推断出其当前状态的程度。发出的数据通常称为遥测。适用于 Ruby 的 Amazon SDK 可以将跟踪记录作为遥测信号提供。您可以连接 TelemetryProvider 以收集遥测数据并将其发送到可观测性后端。该 SDK 目前支持 OpenTelemetry（OTel）作为遥测提供程序，OpenTelemetry 有多种方法可以导出您的遥测数据，包括使用 Amazon X-Ray 或 Amazon CloudWatch。有关适用于 Ruby 的 OpenTelemetry 导出器的更多信息，请参阅 OpenTelemetry 网站上的导出器。

默认情况下，SDK 不会记录或发出任何遥测数据。本主题介绍了如何配置和发出遥测输出。

遥测既可以针对特定服务进行配置，也可以进行全局配置。适用于 Ruby 的 SDK 配备了 OpenTelemetry 提供程序。您也可以定义自己所选的自定义遥测提供程序。

为服务客户端配置 `OTelProvider`

适用于 Ruby 的 SDK 提供了一个名为 OTelProvider 的 OpenTelemetry 提供程序。以下示例使用 OpenTelemetry 为 Amazon Simple Storage Service 服务客户端配置遥测导出。在这个简单的示例中，OpenTelemetry 中的 OTEL_TRACES_EXPORTER 环境变量用于在运行代码时将跟踪导出到控制台输出。要了解有关 OTEL_TRACES_EXPORTER 的更多信息，请参阅 OpenTelemetry 文档中的 Exporter Selection。


require 'aws-sdk-s3'
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'

ENV['OTEL_TRACES_EXPORTER'] ||= 'console'

OpenTelemetry::SDK.configure

otel_provider = Aws::Telemetry::OTelProvider.new
client = Aws::S3::Client.new(telemetry_provider: otel_provider)
client.list_buckets

前面的代码示例显示了为服务客户端配置跟踪输出的步骤：

需要 OpenTelemetry 依赖项。
1. opentelemetry-sdk 用于使用 Aws::Telemetry::OTelProvider。
2. opentelemetry-exporter-otlp 用于导出遥测数据。
使用默认配置调用 OpenTelemetry::SDK.configure 来设置 OpenTelemetry SDK。
使用适用于 Ruby 的 SDK 的 OpenTelemetry 提供程序，创建 OTelProvider 的实例作为配置选项传递给要跟踪的服务客户端。
```
otel_provider = Aws::Telemetry::OTelProvider.new
client = Aws::S3::Client.new(telemetry_provider: otel_provider)
```

使用这些步骤，在该服务客户端上调用的任何方法都将发出跟踪数据。

通过调用 Amazon S3 的 list_buckets 方法生成的跟踪输出示例如下所示：


#<struct OpenTelemetry::SDK::Trace::SpanData
 name="Handler.NetHttp",
 kind=:internal,
 status=#<OpenTelemetry::Trace::Status:0x000000011da17bd8 @code=1, @description="">,
 parent_span_id="\xBFb\xC9\xFD\xA6F!\xE1",
 total_recorded_attributes=7,
 total_recorded_events=0,
 total_recorded_links=0,
 start_timestamp=1736190567061767000,
 end_timestamp=1736190567317160000,
 attributes=
  {"http.method"=>"GET",
   "net.protocol.name"=>"http",
   "net.protocol.version"=>"1.1",
   "net.peer.name"=>"s3.amazonaws.com",
   "net.peer.port"=>"443",
   "http.status_code"=>"200",
   "aws.request_id"=>"22HSH7NQTYMB5NHQ"},
 links=nil,
 events=nil,
 resource=
  #<OpenTelemetry::SDK::Resources::Resource:0x000000011e0bf990
   @attributes=
    {"service.name"=>"unknown_service",
     "process.pid"=>37013,
     "process.command"=>"example.rb",
     "process.runtime.name"=>"ruby",
     "process.runtime.version"=>"3.3.0",
     "process.runtime.description"=>"ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]",
     "telemetry.sdk.name"=>"opentelemetry",
     "telemetry.sdk.language"=>"ruby",
     "telemetry.sdk.version"=>"1.6.0"}>,
 instrumentation_scope=#<struct OpenTelemetry::SDK::InstrumentationScope name="aws.s3.client", version="">,
 span_id="\xEF%\x9C\xB5\x8C\x04\xDB\x7F",
 trace_id=" \xE7\xF1\xF8\x9D\e\x16/\xAC\xE6\x1A\xAC%j\x81\xD8",
 trace_flags=#<OpenTelemetry::Trace::TraceFlags:0x000000011d994328 @flags=1>,
 tracestate=#<OpenTelemetry::Trace::Tracestate:0x000000011d990638 @hash={}>>
#<struct OpenTelemetry::SDK::Trace::SpanData
 name="S3.ListBuckets",
 kind=:client,
 status=#<OpenTelemetry::Trace::Status:0x000000011da17bd8 @code=1, @description="">,
 parent_span_id="\x00\x00\x00\x00\x00\x00\x00\x00",
 total_recorded_attributes=5,
 total_recorded_events=0,
 total_recorded_links=0,
 start_timestamp=1736190567054410000,
 end_timestamp=1736190567327916000,
 attributes={"rpc.system"=>"aws-api", "rpc.service"=>"S3", "rpc.method"=>"ListBuckets", "code.function"=>"list_buckets", "code.namespace"=>"Aws::Plugins::Telemetry"},
 links=nil,
 events=nil,
 resource=
  #<OpenTelemetry::SDK::Resources::Resource:0x000000011e0bf990
   @attributes=
    {"service.name"=>"unknown_service",
     "process.pid"=>37013,
     "process.command"=>"example.rb",
     "process.runtime.name"=>"ruby",
     "process.runtime.version"=>"3.3.0",
     "process.runtime.description"=>"ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]",
     "telemetry.sdk.name"=>"opentelemetry",
     "telemetry.sdk.language"=>"ruby",
     "telemetry.sdk.version"=>"1.6.0"}>,
 instrumentation_scope=#<struct OpenTelemetry::SDK::InstrumentationScope name="aws.s3.client", version="">,
 span_id="\xBFb\xC9\xFD\xA6F!\xE1",
 trace_id=" \xE7\xF1\xF8\x9D\e\x16/\xAC\xE6\x1A\xAC%j\x81\xD8",
 trace_flags=#<OpenTelemetry::Trace::TraceFlags:0x000000011d994328 @flags=1>,
 tracestate=#<OpenTelemetry::Trace::Tracestate:0x000000011d990638 @hash={}>>

之前的跟踪输出有两个数据跨度。每个跟踪条目都通过一个或多个属性提供有关事件的其他元数据。

为所有服务客户端配置 `OTelProvider`

您可以选择全局开启遥测功能，而不是像上一节所解释的那样为特定的服务客户端开启遥测功能。

要为所有 Amazon 服务客户端发出遥测数据，可以在创建服务客户端之前，在 Aws.config 中设置遥测提供程序。


otel_provider = Aws::Telemetry::OTelProvider.new 
Aws.config[:telemetry_provider] = otel_provider

使用此配置，之后创建的任何服务客户端都将自动发出遥测信号。要了解有关使用 Aws.config 设置全局设置的更多信息，请参阅Aws.config。

配置自定义遥测提供程序

如果您不想使用 OpenTelemetry 作为遥测提供程序，适用于 Ruby 的 Amazon SDK 支持您实现自定义提供程序。以适用于 Ruby 的 Amazon SDK GitHub 存储库中提供的 OTelProvider 实现作为示例可能会有所帮助。有关其他背景信息，请参阅《适用于 Ruby 的 Amazon SDK API 参考》中的 Module: Aws::Telemetry 的注释。

跨度属性

跟踪是遥测的输出。跟踪由一个或多个跨度组成。跨度包含属性，这些属性会附带额外的元数据；当该元数据适用于方法调用时，会自动纳入其中。以下是适用于 Ruby 的 SDK 所支持的属性列表，其中：

属性名称：用于标记跟踪中显示的数据的名称。
类型：值的数据类型。
描述：值所代表的内容的描述。

Attribute Name	Type	Description
`error`	Boolean	True if the unit of work was unsuccessful. Otherwise, false.
`exception.message`	String	The exception or error message.
`exception.stacktrace`	String	A stacktrace as provided by the language runtime if available.
`exception.type`	String	The type (fully qualified name) of the exception or error.
`rpc.system`	String	The remote system identifier set to '`aws-api`'.
`rpc.method`	String	The name of the operation being invoked.
`rpc.service`	String	The name of the remote service.
`aws.request_id`	String	The Amazon request ID returned in the response headers, per HTTP attempt. The latest request ID is used when possible.
`code.function`	String	The method or function name.
`code.namespace`	String	The namespace within which `code.function` is defined.
`http.status_code`	Long	The HTTP response status code.
`http.request_content_length`	Long	The size of the request payload body in bytes.
`http.response_content_length`	Long	The size of the response payload body in bytes.
`http.method`	String	The HTTP request method.
`net.protocol.name`	String	The name of the application layer protocol.
`net.protocol.version`	String	The version of the application layer protocol (e.g. 1.0, 1.1, 2.0).
`net.peer.name`	String	The logical remote hostname.
`net.peer.port`	String	The logical remote port number.

提示

OpenTelemetry-Ruby 提供了额外的实现，这些实现与适用于 Ruby 的 SDK 的现的遥测支持相集成。有关更多信息，请参阅 GitHub open-telemetry 存储库中的 OpenTelemetry Amazon-SDK Instrumentation。

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

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

重试

HTTP