AWS SDK for Ruby でのオブザーバビリティ機能の設定 - AWS SDK for Ruby
サービスクライアントの OTelProvider の設定すべてのサービスクライアント用の OTelProvider の設定カスタムテレメトリプロバイダーの設定スパン属性

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS SDK for Ruby でのオブザーバビリティ機能の設定

オブザーバビリティとは、システムが出力するデータから現在の状態をどの程度推論できるかを示します。出力されるデータは、一般的にテレメトリと呼ばれます。AWS SDK for Ruby は、トレースをテレメトリ信号として提供できます。TelemetryProvider をワイヤアップしてテレメトリデータを収集し、オブザーバビリティバックエンドに送信できます。SDK は現在、テレメトリプロバイダーとして OpenTelemetry (OTel) をサポートしており、OpenTelemetry には、AWS X-Rayや Amazon CloudWatch の使用など、テレメトリデータをエクスポートする多くの方法があります。Ruby 用の OpenTelemetry エクスポーターの詳細については、OpenTelemetry ウェブサイトの「エクスポーター」を参照してください。

デフォルトでは、SDK はテレメトリデータを記録も出力もしません。このトピックでは、テレメトリ出力を設定して送信する方法について説明します。

テレメトリは、特定のサービス用に、またはグローバルに設定できます。SDK for Ruby は OpenTelemetry プロバイダーを提供します。選択したカスタムテレメトリプロバイダーを定義することもできます。

サービスクライアントの OTelProvider の設定

SDK for Ruby は、OTelProvider という OpenTelemetry プロバイダーを提供します。次の例では、Amazon Simple Storage Service サービスクライアントの OpenTelemetry を使用してテレメトリエクスポートを設定します。この簡単な例では、OpenTelemetry のOTEL_TRACES_EXPORTER 環境変数を使用して、コードの実行時にトレースをコンソール出力にエクスポートします。OTEL_TRACES_EXPORTER の詳細については、OpenTelemetry ドキュメントの「エクスポーターの選択」を参照してください。

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. Aws::Telemetry::OTelProvider を使用するための opentelemetry-sdk。

    2. テレメトリデータをエクスポートするための opentelemetry-exporter-otlp。

  2. OpenTelemetry::SDK.configure を呼び出し、設定のデフォルトを使用して OpenTelemetry SDK をセットアップします。

  3. SDK for Ruby の 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={}>>

前のトレース出力には 2 つのデータスパンがあります。各トレースエントリは、1 つ以上の属性のイベントに関する追加のメタデータを提供します。

すべてのサービスクライアント用の OTelProvider の設定

前のセクションで説明したように、特定のサービスクライアントのテレメトリを有効にする代わりに、テレメトリをグローバルに有効にすることもできます。

すべての AWS サービスクライアントのテレメトリデータを生成するには、サービスクライアントを作成する前に Aws.config にテレメトリプロバイダーを設定できます。

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

この設定では、後で作成されたサービスクライアントは自動的にテレメトリを出力します。Aws.config を使用してグローバル設定を設定する方法の詳細については、「Aws.config」を参照してください。

カスタムテレメトリプロバイダーの設定

OpenTelemetry をテレメトリプロバイダーとして使用しない場合、カスタムプロバイダーの実装は AWS SDK for Ruby によってサポートされます。AWS SDK for Ruby GitHub リポジトリで利用できるOTelProvider 実装を例として参考にすると役立つ場合があります。補足情報については、「AWS SDK for Ruby API リファレンス」の「Module: Aws::Telemetry」の注意事項を参照してください。

スパン属性

トレースはテレメトリの出力です。トレースは 1 つ以上のスパンで構成されます。スパンには、メソッド呼び出しに適切な場合に自動的に含まれる追加のメタデータを含む属性があります。以下に、SDK for Ruby でサポートされている属性のリストを示します。

  • 属性名 - トレースに表示されるデータのラベル付けに使用される名前。

  • 型 - 値のデータ型。

  • 説明 - 値が表す内容の説明。

Attribute Name Type Description
エラー 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 には、SDK for Ruby の既存のテレメトリサポートと統合された追加の実装があります。詳細については、open-telemetry GitHub リポジトリの「OpenTelemetry AWS SDK 計測」を参照してください。