Mengkonfigurasi fitur observabilitas di AWS SDK for Ruby - AWS SDK for Ruby
Mengkonfigurasi OTelProvider untuk klien layananMengkonfigurasi OTelProvider untuk semua klien layananMengkonfigurasi penyedia telemetri khususAtribut Span

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mengkonfigurasi fitur observabilitas di AWS SDK for Ruby

Observabilitas adalah sejauh mana keadaan sistem saat ini dapat disimpulkan dari data yang dipancarkannya. Data yang dipancarkan biasanya disebut sebagai telemetri. AWS SDK for Ruby dapat memberikan jejak sebagai sinyal telemetri. Anda dapat memasang file TelemetryProvider untuk mengumpulkan dan mengirim data telemetri ke backend observabilitas. SDK saat ini mendukung OpenTelemetry (OTel) sebagai penyedia telemetri dan OpenTelemetry memiliki banyak cara untuk mengekspor data telemetri Anda, termasuk menggunakan atau Amazon. AWS X-Ray CloudWatch Untuk informasi lebih lanjut tentang OpenTelemetry eksportir Ruby, lihat Eksportir di situs web. OpenTelemetry

Secara default, SDK tidak akan merekam atau memancarkan data telemetri apa pun. Topik ini menjelaskan cara mengkonfigurasi dan memancarkan keluaran telemetri.

Telemetri dapat dikonfigurasi baik untuk layanan tertentu atau secara global. SDK for Ruby OpenTelemetry memasok penyedia. Anda juga dapat menentukan penyedia telemetri khusus pilihan Anda.

Mengkonfigurasi OTelProvider untuk klien layanan

SDK for Ruby OpenTelemetry menyediakan penyedia yang disebut. OTelProvider Contoh berikut mengonfigurasi ekspor telemetri menggunakan OpenTelemetry untuk klien layanan Amazon Simple Storage Service. Untuk contoh sederhana ini, variabel OTEL_TRACES_EXPORTER lingkungan dari OpenTelemetry digunakan untuk mengekspor jejak ke output konsol saat Anda menjalankan kode. Untuk mempelajari selengkapnyaOTEL_TRACES_EXPORTER, lihat Pemilihan Eksportir di OpenTelemetry dokumentasi. 

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

Contoh kode sebelumnya menunjukkan langkah-langkah untuk mengonfigurasi keluaran jejak untuk klien layanan:

  1. Membutuhkan OpenTelemetry dependensi.

    1. opentelemetry-sdkuntuk menggunakanAws::Telemetry::OTelProvider.

    2. opentelemetry-exporter-otlpuntuk mengekspor data telemetri.

  2. Panggilan OpenTelemetry::SDK.configure untuk mengatur OpenTelemetry SDK dengan default konfigurasi mereka.

  3. Menggunakan SDK untuk OpenTelemetry penyedia Ruby, buat instance OTelProvider untuk diteruskan sebagai opsi konfigurasi ke klien layanan yang ingin Anda lacak.

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

Dengan menggunakan langkah-langkah ini, metode apa pun yang dipanggil pada klien layanan itu akan memancarkan data jejak.

Contoh keluaran jejak yang dihasilkan dari panggilan ke list_buckets metode Amazon S3 adalah sebagai berikut:

#<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={}>>

Output jejak sebelumnya memiliki dua rentang data. Setiap entri jejak menyediakan metadata tambahan tentang peristiwa dalam satu atau beberapa atribut.

Mengkonfigurasi OTelProvider untuk semua klien layanan

Alih-alih mengaktifkan telemetri untuk klien layanan tertentu seperti yang dijelaskan bagian sebelumnya, Anda memiliki opsi untuk mengaktifkan telemetri secara global.

Untuk memancarkan data telemetri untuk semua klien AWS layanan, Anda dapat mengatur penyedia telemetri Aws.config sebelum membuat klien layanan.

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

Dengan konfigurasi ini, setiap klien layanan yang dibuat setelahnya akan secara otomatis memancarkan telemetri. Untuk mempelajari lebih lanjut tentang Aws.config cara menggunakan pengaturan global, lihatAws.config.

Mengkonfigurasi penyedia telemetri khusus

Jika Anda tidak ingin digunakan OpenTelemetry sebagai penyedia telemetri, AWS SDK for Ruby mendukung Anda menerapkan penyedia kustom. Mungkin berguna untuk menggunakan OTelProviderimplementasi yang tersedia di repositori AWS SDK GitHub for Ruby sebagai contoh. Untuk konteks tambahan, lihat catatan Module: Aws::Telemetrydi Referensi AWS SDK untuk Ruby API.

Atribut Span

Jejak adalah output dari telemetri. Jejak terdiri dari satu atau lebih bentang. Rentang memiliki atribut yang menyertakan metadata tambahan yang secara otomatis disertakan bila sesuai untuk pemanggilan metode. Berikut ini adalah daftar atribut yang didukung oleh SDK for Ruby, di mana:

  • Nama Atribut - nama yang digunakan untuk memberi label data yang muncul di jejak.

  • Jenis - tipe data dari nilai.

  • Deskripsi - deskripsi tentang apa yang diwakili oleh nilai.

Nama Atribut Jenis Deskripsi
error Boolean Benar jika unit kerja tidak berhasil. Kalau tidak, salah.
exception.message String Pesan pengecualian atau kesalahan.
exception.stacktrace String Stacktrace seperti yang disediakan oleh runtime bahasa jika tersedia.
exception.type String Jenis (nama yang sepenuhnya memenuhi syarat) dari pengecualian atau kesalahan.
rpc.system String Pengidentifikasi sistem jarak jauh diatur ke 'aws-api'.
rpc.method String Nama operasi yang dipanggil.
rpc.service String Nama layanan jarak jauh.
aws.request_id String ID AWS permintaan dikembalikan dalam header respons, per upaya HTTP. ID permintaan terbaru digunakan jika memungkinkan.
code.function String Metode atau nama fungsi.
code.namespace String Namespace di dalamnya code.function didefinisikan.
http.status_code Panjang Kode status respons HTTP.
http.request_content_length Panjang Ukuran badan payload permintaan dalam byte.
http.response_content_length Panjang Ukuran badan payload respons dalam byte.
http.method String Metode permintaan HTTP.
net.protocol.name String Nama protokol lapisan aplikasi.
net.protocol.version String Versi protokol lapisan aplikasi (misalnya 1.0, 1.1, 2.0).
net.peer.name String Nama host jarak jauh logis.
net.peer.port String Nomor port jarak jauh logis.
Tip

OpenTelemetry-Ruby memiliki implementasi tambahan yang terintegrasi dengan SDK untuk dukungan Telemetri Ruby yang ada. Untuk informasi selengkapnya, lihat OpenTelemetry AWS-SDK Instrumentation di repositori. open-telemetry GitHub