本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在適用於 Ruby 的 AWS SDK 中設定可觀測性功能
<a name="observability"></a>

 可觀測性是從系統發出的資料推斷系統目前狀態的程度。發出的資料通常稱為遙測。適用於 Ruby 的 AWS SDK 可以提供追蹤作為遙測訊號。您可以連接 `TelemetryProvider`以收集遙測資料並將其傳送至可觀測性後端。開發套件目前支援 OpenTelemetry (OTel) 做為遙測供應商，而 OpenTelemetry 有許多匯出遙測資料的方式，包括使用 [AWS X-Ray](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools)或 [Amazon CloudWatch](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov)。如需適用於 Ruby 的 OpenTelemetry 匯出工具的詳細資訊，請參閱 OpenTelemetry 網站上的[匯出工具](https://opentelemetry.io/docs/languages/ruby/exporters)。

 根據預設，軟體開發套件不會記錄或發出任何遙測資料。本主題說明如何設定和發出遙測輸出。

 您可以針對特定服務或全域設定遙測。適用於 Ruby 的 SDK 提供 OpenTelemetry 供應商。您也可以定義您選擇的自訂遙測供應商。

## `OTelProvider` 為服務用戶端設定
<a name="config-otel"></a>

適用於 Ruby 的 SDK 提供稱為 的 OpenTelemetry 供應商[https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry/OTelProvider.html](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry/OTelProvider.html)。下列範例使用 Amazon Simple Storage Service 服務用戶端的 OpenTelemetry 設定遙測匯出。在此簡單範例中，執行程式碼時，來自 OpenTelemetry `OTEL_TRACES_EXPORTER`的環境變數會用來將追蹤匯出至主控台輸出。若要進一步了解 `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.  使用適用於 Ruby 的 OpenTelemetry 供應商的 SDK，建立 執行個體`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>

您可以選擇全域開啟遙測，而不是開啟前一節所述的特定服務用戶端的遙測。

若要**為所有** AWS 服務用戶端發出遙測資料，您可以在建立服務用戶端`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 做為遙測提供者，適用於 Ruby 的 AWS SDK 會支援您實作自訂提供者。例如，使用適用於 Ruby GitHub 的 AWS SDK 儲存庫中提供的[`OTelProvider`實作](https://github.com/aws/aws-sdk-ruby/blob/version-3/gems/aws-sdk-core/lib/aws-sdk-core/telemetry/otel.rb)可能會有所幫助。如需其他內容，請參閱 *適用於 Ruby 的 AWS SDK API 參考*[https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry.html](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry.html)中的 備註。

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

追蹤是遙測的輸出。追蹤包含一或多個跨度。範圍具有包含其他中繼資料的屬性，這些中繼資料會在適合方法呼叫時自動包含。以下是適用於 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 AWS 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 整合。如需詳細資訊，請參閱 `open-telemetry` GitHub 儲存庫中的 [OpenTelemetry AWS-SDK Instrumentation](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_sdk)。