本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 Amazon SDK for Ruby 中配置可观察性功能
<a name="observability"></a>

 可观测性是指可以根据系统发出的数据推断出其当前状态的程度。发出的数据通常称为遥测。 Amazon 适用于 Ruby 的 SDK 可以将轨迹作为遥测信号提供。您可以连接 `TelemetryProvider` 以收集遥测数据并将其发送到可观测性后端。[该软件开发工具包目前支持 OpenTelemetry (OTel) 作为遥测提供商，并且 OpenTelemetry 有多种导出遥测数据的方式，包括使用或 [Amazon X-Ray](https://docs.amazonaws.cn/xray/?icmpid=docs_homepage_devtools)Amazon。 CloudWatch](https://docs.amazonaws.cn/cloudwatch/?icmpid=docs_homepage_mgmtgov)有关 Ruby 导 OpenTelemetry 出器的更多信息，请参阅[ OpenTelemetry 网站](https://opentelemetry.io/docs/languages/ruby/exporters)上的导出器。

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

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

## 为服务客户端配置 `OTelProvider`
<a name="config-otel"></a>

适用于 Ruby 的 SDK 提供了一个名为的 OpenTelemetry 提供程序[https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/Telemetry/OTelProvider.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/Telemetry/OTelProvider.html)。以下示例使用 OpenTelemetry 亚马逊简单存储服务客户端配置遥测导出。在这个简单的示例中，`OTEL_TRACES_EXPORTER`环境变量 f OpenTelemetry rom 用于在运行代码时将跟踪导出到控制台输出。要了解更多信息`OTEL_TRACES_EXPORTER`，请参阅 OpenTelemetry 文档中的[导出器选择](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#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
```

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

1. 需要 OpenTelemetry 依赖关系。

   1. [https://rubygems.org/gems/opentelemetry-sdk](https://rubygems.org/gems/opentelemetry-sdk) 用于使用 `Aws::Telemetry::OTelProvider`。

   1. [https://rubygems.org/gems/opentelemetry-exporter-otlp](https://rubygems.org/gems/opentelemetry-exporter-otlp) 用于导出遥测数据。

1.  调用`OpenTelemetry::SDK.configure`以使用默认配置设置 OpenTelemetry SDK。

1.  使用 SDK for Ruby 的 OpenTelemetry 提供程序，创建`OTelProvider`要作为配置选项传递给要跟踪的服务客户端的实例。

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

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

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

### OpenTelemetry 跟踪输出示例
<a name="otel-trace-output"></a>

```
#<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`
<a name="otel-global"></a>

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

要为**所有** Amazon 服务客户端发送遥测数据，可以在创建服务客户端`Aws.config`之前将遥测提供者设置为开启。

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

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

## 配置自定义遥测提供程序
<a name="custom-telem"></a>

如果您不想 OpenTelemetry 用作遥测提供程序，那么 Amazon SDK for Ruby 确实支持您实现自定义提供程序。以 Amazon SDK for Ruby GitHub 存储库中提供的[`OTelProvider`实现](https://github.com/aws/aws-sdk-ruby/blob/version-3/gems/aws-sdk-core/lib/aws-sdk-core/telemetry/otel.rb)作为示例可能会有所帮助。有关其他背景信息，请参阅《适用于 Ruby 的 Amazon SDK API 参考》**中的 [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/Telemetry.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/Telemetry.html) 的注释。

## 跨度属性
<a name="span-attributes"></a>

跟踪是遥测的输出。跟踪由一个或多个跨度组成。跨度包含属性，这些属性会附带额外的元数据；当该元数据适用于方法调用时，会自动纳入其中。以下是适用于 Ruby 的 SDK 所支持的属性列表，其中：
+ 属性名称：用于标记跟踪中显示的数据的名称。
+ 类型：值的数据类型。
+ 描述：值所代表的内容的描述。




|  |  |  | 
| --- |--- |--- |
| 属性名称 | Type | 描述 | 
| error | 布尔值 | 如果工作单元不成功，则为 true。否则为 false。 | 
| exception.message | 字符串 | 异常或错误消息。 | 
| exception.stacktrace | 字符串 | 语言运行时提供的堆栈跟踪（如果有）。 | 
| exception.type | 字符串 | 异常或错误的类型（完全限定名称）。 | 
| rpc.system | 字符串 | 远程系统标识符设置为 “aws-api”。 | 
| rpc.method | 字符串 | 所调用操作的名称。 | 
| rpc.service | 字符串 | 远程服务的名称。 | 
| aws.request\_id | 字符串 | 每次 HTTP 尝试都会在响应标头中返回的 Amazon 请求 ID。尽可能使用最新的请求 ID。 | 
| code.function | 字符串 | 方法或函数名称。 | 
| code.namespace | 字符串 | 在其中code.function定义的命名空间。 | 
| http.status\_code | 长整型 | HTTP 响应状态码。 | 
| http.request\_content\_length | 长整型 | 请求负载正文的大小，以字节为单位。 | 
| http.response\_content\_length | 长整型 | 响应负载正文的大小，以字节为单位。 | 
| http.method | 字符串 | HTTP 请求方法。 | 
| net.protocol.name | 字符串 | 应用层协议的名称。 | 
| net.protocol.version | 字符串 | 应用层协议的版本（例如 1.0、1.1、2.0）。 | 
| net.peer.name | 字符串 | 逻辑远程主机名。 | 
| net.peer.port | 字符串 | 逻辑远程端口号。 | 

**提示**  
OpenTelemetry-Ruby 还有其他实现与 SDK 集成，适用于 Ruby 现有的遥测支持。有关更多信息，请参阅`open-telemetry` GitHub 存储库中的 [OpenTelemetry Amazon-SDK 工具](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_sdk)。