Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Migrasi ke Ruby OpenTelemetry Untuk memigrasikan aplikasi Ruby Anda dari X-Ray SDK ke OpenTelemetry instrumentasi, gunakan contoh kode berikut dan panduan untuk instrumentasi manual. **Topics** + [Instrumentasikan solusi Anda secara manual dengan SDK](#manual-instrumentation-ruby) + [Menelusuri permintaan masuk (instrumentasi Rails)](#tracing-incoming-requests-ruby) + [AWS Instrumentasi SDK](#aws-sdk-instrumentation-ruby) + [Instrumentasi panggilan HTTP keluar](#http-instrumentation-ruby) + [Dukungan instrumentasi untuk perpustakaan lain](#xray-migration-libraries-ruby) + [Membuat data jejak secara manual](#manual-trace-creation-ruby) + [Instrumentasi manual Lambda](#lambda-instrumentation-ruby) ## Instrumentasikan solusi Anda secara manual dengan SDK ------ #### [ Tracing setup with X-Ray SDK ] X-Ray SDK for Ruby mengharuskan Anda untuk mengonfigurasi kode Anda dengan plug-in layanan. ``` require 'aws-xray-sdk' XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk]) ``` ------ #### [ Tracing setup with OpenTelemetry SDK ] **catatan** X-Ray Remote Sampling saat ini tidak tersedia untuk dikonfigurasi untuk OpenTelemetry Ruby. Untuk aplikasi Ruby on Rails, tempatkan kode konfigurasi Anda di penginisialisasi Rails. Untuk informasi selengkapnya, lihat [Memulai](https://opentelemetry.io/docs/languages/ruby/getting-started/#initialization). Untuk semua program Ruby yang diinstrumentasi secara manual, Anda harus menggunakan `OpenTelemetry::SDK.configure` metode ini untuk mengkonfigurasi OpenTelemetry Ruby SDK. Pertama, instal paket-paket berikut: ``` bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray ``` Selanjutnya, konfigurasikan OpenTelemetry SDK melalui kode konfigurasi yang berjalan saat program Anda diinisialisasi. Disarankan agar Anda mengkonfigurasi komponen-komponen berikut: + `OTLP Exporter`- Diperlukan untuk mengekspor jejak ke CloudWatch agen dan kolektor OpenTelemetry + `An AWS X-Ray Propagator`— Diperlukan untuk menyebarkan konteks jejak ke AWS layanan yang terintegrasi dengan X-Ray ``` require 'opentelemetry-sdk' require 'opentelemetry-exporter-otlp' # Import the gem containing the AWS X-Ray for OTel Ruby ID Generator and propagator require 'opentelemetry-propagator-xray' OpenTelemetry::SDK.configure do |c| c.service_name = 'my-service-name' c.add_span_processor( # Use the BatchSpanProcessor to send traces in groups instead of one at a time OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new( # Use the default OLTP Exporter to send traces to the ADOT Collector OpenTelemetry::Exporter::OTLP::Exporter.new( # The OpenTelemetry Collector is running as a sidecar and listening on port 4318 endpoint:"http://127.0.0.1:4318/v1/traces" ) ) ) # The X-Ray Propagator injects the X-Ray Tracing Header into downstream calls c.propagators = [OpenTelemetry::Propagator::XRay::TextMapPropagator.new] end ``` OpenTelemetry SDKs juga memiliki konsep instrumentasi perpustakaan. Mengaktifkan ini akan secara otomatis membuat rentang untuk pustaka seperti SDK. AWS OpenTelemetry menyediakan opsi untuk mengaktifkan semua instrumentasi perpustakaan atau menentukan instrumentasi perpustakaan mana yang akan diaktifkan. Untuk mengaktifkan semua instrumentasi, instal paket terlebih dahulu: `opentelemetry-instrumentation-all` ``` bundle add opentelemetry-instrumentation-all ``` Selanjutnya, perbarui konfigurasi untuk mengaktifkan semua instrumentasi pustaka seperti yang ditunjukkan di bawah ini: ``` require 'opentelemetry/instrumentation/all' ... OpenTelemetry::SDK.configure do |c| ... c.use_all() # Enable all instrumentations end ``` OpenTelemetry SDKs juga memiliki konsep instrumentasi perpustakaan. Mengaktifkan ini akan secara otomatis membuat rentang untuk pustaka seperti SDK. AWS OpenTelemetry menyediakan opsi untuk mengaktifkan semua instrumentasi perpustakaan atau menentukan instrumentasi perpustakaan mana yang akan diaktifkan. Untuk mengaktifkan semua instrumentasi, instal paket terlebih dahulu: `opentelemetry-instrumentation-all` ``` bundle add opentelemetry-instrumentation-all ``` Selanjutnya, perbarui konfigurasi untuk mengaktifkan semua instrumentasi pustaka seperti yang ditunjukkan di bawah ini: ``` require 'opentelemetry/instrumentation/all' ... OpenTelemetry::SDK.configure do |c| ... c.use_all() # Enable all instrumentations end ``` ------ ## Menelusuri permintaan masuk (instrumentasi Rails) ------ #### [ With X-Ray SDK ] Dengan X-Ray SDK, penelusuran X-Ray dikonfigurasi untuk kerangka Rails setelah inisialisasi. **Contoh** - config/initializers/aws \_xray.rb ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ------ #### [ With OpenTelemetry SDK ] Pertama, instal paket-paket berikut: ``` bundle add opentelemetry-instrumentation-rack opentelemetry-instrumentation-rails opentelemetry-instrumentation-action_pack opentelemetry-instrumentation-active_record opentelemetry-instrumentation-action_view ``` Selanjutnya, perbarui konfigurasi untuk mengaktifkan instrumentasi untuk aplikasi Rails Anda seperti yang ditunjukkan di bawah ini: ``` # During SDK configuration OpenTelemetry::SDK.configure do |c| ... c.use 'OpenTelemetry::Instrumentation::Rails' c.use 'OpenTelemetry::Instrumentation::Rack' c.use 'OpenTelemetry::Instrumentation::ActionPack' c.use 'OpenTelemetry::Instrumentation::ActiveSupport' c.use 'OpenTelemetry::Instrumentation::ActionView' ... end ``` ------ ## AWS Instrumentasi SDK ------ #### [ With X-Ray SDK ] Untuk menginstrumentasikan AWS permintaan keluar dari AWS SDK, klien AWS SDK ditambal dengan X-Ray seperti contoh berikut: ``` require 'aws-xray-sdk' require 'aws-sdk-s3' # Patch AWS SDK clients XRay.recorder.configure(plugins: [:aws_sdk]) # Use the instrumented client s3 = Aws::S3::Client.new s3.list_buckets ``` ------ #### [ With OpenTelemetry SDK ] AWS SDK for Ruby V3 menyediakan dukungan untuk merekam dan memancarkan jejak. OpenTelemetry Untuk informasi tentang cara mengonfigurasi klien layanan, lihat [Mengonfigurasi fitur observabilitas di AWS SDK OpenTelemetry for Ruby](sdk-for-ruby/v3/developer-guide/observability.html). ------ ## Instrumentasi panggilan HTTP keluar Saat melakukan panggilan HTTP ke layanan eksternal, Anda mungkin perlu mengarahkan panggilan secara manual jika instrumentasi otomatis tidak tersedia atau tidak memberikan detail yang cukup. ------ #### [ With X-Ray SDK ] Untuk instrumen panggilan hilir, X-Ray SDK for Ruby digunakan untuk menambal `net/http` library yang digunakan aplikasi Anda: ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http] } XRay.recorder.configure(config) ``` ------ #### [ With OpenTelemetry SDK ] Untuk mengaktifkan `net/http` instrumentasi menggunakan OpenTelemetry, pertama instal `opentelemetry-instrumentation-net_http` paket: ``` bundle add opentelemetry-instrumentation-net_http ``` Selanjutnya, perbarui konfigurasi untuk mengaktifkan `net/http` instrumentasi seperti yang ditunjukkan di bawah ini: ``` OpenTelemetry::SDK.configure do |c| ... c.use 'OpenTelemetry::Instrumentation::Net::HTTP' ... end ``` ------ ## Dukungan instrumentasi untuk perpustakaan lain Anda dapat menemukan daftar lengkap instrumentasi Library yang didukung untuk OpenTelemetry Ruby di bawah. [opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation) Atau, Anda dapat mencari OpenTelemetry Registry untuk mengetahui apakah OpenTelemetry mendukung instrumentasi. Untuk informasi selengkapnya, lihat [Registry](https://opentelemetry.io/ecosystem/registry/). ## Membuat data jejak secara manual ------ #### [ With X-Ray SDK ] Menggunakan X-Ray, `aws-xray-sdk` paket mengharuskan Anda untuk membuat segmen dan sub-segmen anak mereka secara manual untuk melacak aplikasi Anda. Anda mungkin juga telah menambahkan anotasi X-Ray dan metadata ke segmen atau sub-segmen Anda: ``` require 'aws-xray-sdk' ... # Start a segment segment = XRay.recorder.begin_segment('my-service') # Add annotations (indexed key-value pairs) segment.annotations[:user_id] = 'user-123' segment.annotations[:payment_status] = 'completed' # Add metadata (non-indexed data) segment.metadata[:order] = { id: 'order-456', items: [ { product_id: 'prod-1', quantity: 2 }, { product_id: 'prod-2', quantity: 1 } ], total: 67.99 } # Add metadata to a specific namespace segment.metadata(namespace: 'payment') do |metadata| metadata[:transaction_id] = 'tx-789' metadata[:payment_method] = 'credit_card' end # Create a subsegment with annotations and metadata segment.subsegment('payment-processing') do |subsegment1| subsegment1.annotations[:payment_id] = 'pay-123' subsegment1.metadata[:details] = { amount: 67.99, currency: 'USD' } # Create a nested subsegment subsegment1.subsegment('operation-2') do |subsegment2| # Do more work... end end # Close the segment segment.close ``` ------ #### [ With OpenTelemetry SDK ] Anda dapat menggunakan rentang kustom untuk memantau kinerja aktivitas internal yang tidak ditangkap oleh pustaka instrumentasi. Perhatikan bahwa hanya rentang server jenis yang diubah menjadi segmen X-Ray, semua rentang lainnya diubah menjadi sub-segmen X-Ray. Secara default, bentang adalah`INTERNAL`. Pertama, buat Tracer untuk menghasilkan bentang, yang dapat Anda peroleh melalui metode ini`OpenTelemetry.tracer_provider.tracer('')`. Ini akan memberikan instance Tracer yang terdaftar secara global dalam OpenTelemetry konfigurasi aplikasi Anda. Adalah umum untuk memiliki satu Tracer untuk seluruh aplikasi. Buat OpenTelemetry pelacak dan gunakan untuk membuat bentang: ``` require 'opentelemetry-sdk' ... # Get a tracer tracer = OpenTelemetry.tracer_provider.tracer('my-application') # Create a server span (equivalent to X-Ray segment) tracer.in_span('my-application', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span| # Do work... # Create nested spans of default kind INTERNAL will become an X-Ray subsegment tracer.in_span('operation-1') do |child_span1| # Set attributes (equivalent to X-Ray annotations and metadata) child_span1.set_attribute('key', 'value') # Do more work... tracer.in_span('operation-2') do |child_span2| # Do more work... end end end ``` **Menambahkan anotasi dan metadata ke jejak dengan SDK OpenTelemetry ** Gunakan `set_attribute` metode untuk menambahkan atribut ke setiap rentang. Perhatikan bahwa secara default, semua atribut rentang ini akan diubah menjadi metadata dalam data mentah X-Ray. Untuk memastikan bahwa atribut diubah menjadi anotasi dan bukan metadata, Anda dapat menambahkan kunci atribut tersebut ke daftar atribut. `aws.xray.annotations` Untuk informasi selengkapnya, lihat [Mengaktifkan Anotasi X-Ray yang Disesuaikan](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations). ``` # SERVER span will become an X-Ray segment tracer.in_span('my-server-operation', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span| # Your server logic here span.set_attribute('attribute.key', 'attribute.value') span.set_attribute("metadataKey", "metadataValue") span.set_attribute("annotationKey1", "annotationValue") # Create X-Ray annotations span.set_attribute("aws.xray.annotations", ["annotationKey1"]) end ``` ------ ## Instrumentasi manual Lambda ------ #### [ With X-Ray SDK ] Setelah *Active Tracing* diaktifkan di Lambda, tidak ada konfigurasi tambahan yang diperlukan untuk menggunakan X-Ray SDK. Lambda akan membuat segmen yang mewakili pemanggilan penangan Lambda, dan Anda dapat membuat sub-segmen atau pustaka instrumen menggunakan X-Ray SDK tanpa konfigurasi tambahan. ------ #### [ With OpenTelemetry SDK ] Pertimbangkan contoh kode fungsi Lambda berikut (tanpa instrumentasi): ``` require 'json' def lambda_handler(event:, context:) # TODO implement { statusCode: 200, body: JSON.generate('Hello from Lambda!') } end ``` Untuk instrumen Lambda Anda secara manual, Anda harus: 1. Tambahkan permata berikut untuk Lambda Anda ``` gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-propagator-xray' gem 'aws-distro-opentelemetry-exporter-xray-udp' gem 'opentelemetry-instrumentation-aws_lambda' gem 'opentelemetry-propagator-xray', '~> 0.24.0' # Requires version v0.24.0 or higher ``` 1. Inisialisasi OpenTelemetry SDK di luar Lambda Handler Anda. OpenTelemetry SDK direkomendasikan untuk dikonfigurasi dengan: 1. Prosesor span sederhana dengan eksportir rentang UDP X-Ray untuk mengirim Jejak ke titik akhir X-Ray UDP Lambda 1. Penyebar X-Ray Lambda 1. `service_name`konfigurasi yang akan disetel ke nama fungsi Lambda 1. Di kelas handler Lambda Anda, tambahkan baris berikut untuk instrumen Lambda Handler Anda: ``` class Handler extend OpenTelemetry::Instrumentation::AwsLambda::Wrap ... instrument_handler :process end ``` Kode berikut menunjukkan fungsi Lambda setelah perubahan yang diperlukan. Anda dapat membuat rentang kustom tambahan untuk melengkapi rentang yang disediakan secara otomatis. ``` require 'json' require 'opentelemetry-sdk' require 'aws/distro/opentelemetry/exporter/xray/udp' require 'opentelemetry/propagator/xray' require 'opentelemetry/instrumentation/aws_lambda' # Initialize OpenTelemetry SDK outside handler OpenTelemetry::SDK.configure do |c| # Configure the AWS Distro for OpenTelemetry X-Ray Lambda exporter c.add_span_processor( OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new( AWS::Distro::OpenTelemetry::Exporter::XRay::UDP::AWSXRayUDPSpanExporter.new ) ) # Configure X-Ray Lambda propagator c.propagators = [OpenTelemetry::Propagator::XRay.lambda_text_map_propagator] # Set minimal resource information c.resource = OpenTelemetry::SDK::Resources::Resource.create({ OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => ENV['AWS_LAMBDA_FUNCTION_NAME'] }) c.use 'OpenTelemetry::Instrumentation::AwsLambda' end module LambdaFunctions class Handler extend OpenTelemetry::Instrumentation::AwsLambda::Wrap def self.process(event:, context:) "Hello!" end instrument_handler :process end end ``` ------ Berikut ini adalah contoh peta jejak fungsi Lambda berinstrumen yang ditulis dalam Ruby. ![Lacak peta di CloudWatch konsol untuk Ruby.](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/deprecation_ruby.png) Anda juga dapat menggunakan lapisan Lambda untuk mengkonfigurasi OpenTelemetry Lambda Anda. Untuk informasi selengkapnya, lihat Instrumentasi [OpenTelemetry AWS-Lambda](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_lambda#usage).