Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Migrasi dari instrumentasi X-Ray ke instrumentasi OpenTelemetry **catatan** Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). X-Ray beralih ke OpenTelemetry (OTel) sebagai standar instrumentasi utamanya untuk penelusuran aplikasi dan observabilitas. Pergeseran strategis ini sejalan AWS dengan praktik terbaik industri dan menawarkan pelanggan solusi yang lebih komprehensif, fleksibel, dan siap di masa depan untuk kebutuhan pengamatan mereka. OpenTelemetryAdopsi luas di industri memungkinkan penelusuran permintaan di berbagai sistem, termasuk yang di luar AWS yang mungkin tidak secara langsung terintegrasi dengan X-Ray. Bab ini memberikan rekomendasi untuk transisi yang mulus, dan menekankan pentingnya migrasi ke solusi OpenTelemetry berbasis untuk memastikan dukungan berkelanjutan dan akses ke fitur terbaru dalam instrumentasi dan observabilitas aplikasi. Disarankan untuk mengadopsi OpenTelemetry sebagai solusi observabilitas untuk menginstrumentasi aplikasi Anda. **Topics** + [Memahami OpenTelemetry](#migration-to-opentelemetry) + [Memahami OpenTelemetry konsep migrasi](#opentelemetry-concepts) + [Ikhtisar migrasi](#migration-overview) + [Migrasi dari X-Ray Daemon ke AWS CloudWatch agen atau kolektor OpenTelemetry](#xray-Daemon-migration) + [Migrasi ke OpenTelemetry Java](xray-migration-opentelemetry.md) + [Migrasi ke Go OpenTelemetry](manual-instrumentation-go.md) + [Migrasi ke Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md) + [Migrasi ke OpenTelemetry .NET](introduction-dotnet.md) + [Migrasi ke Python OpenTelemetry](migrate-xray-to-opentelemetry-python.md) + [Migrasi ke Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md) ## Memahami OpenTelemetry OpenTelemetry adalah kerangka observabilitas standar industri yang menyediakan protokol dan alat standar untuk mengumpulkan data telemetri. Ini menawarkan pendekatan terpadu untuk menginstrumentasi, menghasilkan, mengumpulkan, dan mengekspor data telemetri seperti metrik, log, dan jejak. Ketika Anda bermigrasi dari X-Ray SDKs ke OpenTelemetry, Anda mendapatkan manfaat berikut: + Dukungan instrumentasi kerangka kerja dan perpustakaan yang disempurnakan + Support untuk bahasa pemrograman tambahan + Kemampuan instrumentasi otomatis + Opsi konfigurasi pengambilan sampel yang fleksibel + Koleksi metrik, log, dan jejak terpadu OpenTelemetry Kolektor menyediakan lebih banyak opsi untuk format pengumpulan data dan tujuan ekspor daripada daemon X-Ray. ### OpenTelemetry dukungan di AWS AWS menyediakan beberapa solusi untuk bekerja dengan OpenTelemetry: + AWS Distro untuk OpenTelemetry Ekspor OpenTelemetry jejak sebagai segmen ke X-Ray. Untuk informasi lebih lanjut, lihat [AWS Distro untuk OpenTelemetry](https://aws-otel.github.io/). + CloudWatch Sinyal Aplikasi Ekspor OpenTelemetry jejak dan metrik yang disesuaikan untuk memantau kesehatan aplikasi. Untuk informasi selengkapnya, lihat [Bekerja dengan Sinyal Aplikasi](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). + CloudWatch OTel Titik akhir Ekspor OpenTelemetry jejak ke X-Ray menggunakan OTel titik akhir HTTP dengan OpenTelemetry instrumentasi asli. Untuk informasi selengkapnya, lihat [Menggunakan OTel titik akhir](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html). #### Menggunakan OpenTelemetry dengan AWS CloudWatch AWS CloudWatch mendukung OpenTelemetry jejak melalui instrumentasi aplikasi sisi klien dan AWS CloudWatch layanan asli seperti Sinyal Aplikasi, Jejak, Peta, Metrik, dan Log. Untuk informasi selengkapnya, lihat [OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html). ## Memahami OpenTelemetry konsep migrasi Tabel berikut memetakan konsep X-Ray ke OpenTelemetry padanannya. Memahami pemetaan ini membantu Anda menerjemahkan instrumentasi X-Ray yang ada ke: OpenTelemetry | Konsep X-Ray | OpenTelemetry konsep | | --- | --- | | Perekam X-Ray | Penyedia dan Pelacak Pelacak | | Plugin Layanan | Detektor Sumber Daya | | Segment | Rentang (Server) | | Sub-segmen | Rentang (Non-server) | | Aturan Pengambilan Sampel X-Ray | OpenTelemetry Sampling (Dapat Disesuaikan) | | Pemancar X-Ray | Eksportir Span (Dapat Disesuaikan) | | Anotasi/Metadata | Atribut | | Instrumentasi Perpustakaan | Instrumentasi Perpustakaan | | Konteks Jejak X-Ray | Konteks Rentang | | Propagasi Konteks Jejak Sinar-X | Propagasi Konteks Jejak W3C | | Pengambilan Sampel Jejak X-Ray | OpenTelemetry Pengambilan Sampel Jejak | | N/A | Pemrosesan Rentang | | N/A | Bagasi | | Daemon X-Ray | OpenTelemetry Kolektor | **catatan** Untuk informasi lebih lanjut tentang OpenTelemetry konsep, lihat [OpenTelemetry dokumentasi](https://opentelemetry.io/docs). ### Membandingkan fitur Tabel berikut menunjukkan fitur mana yang didukung di kedua layanan. Gunakan informasi ini untuk mengidentifikasi celah yang perlu Anda atasi selama migrasi: | Fitur | Instrumentasi X-Ray | OpenTelemetry instrumentasi | | --- | --- | --- | | Instrumentasi perpustakaan | Didukung | Didukung | | Pengambilan sampel X-Ray | Didukung | Didukung di OTel Java/.net/Go
Didukung di ADOT Java/. NET/Python/Node.js | | Propagasi konteks jejak X-Ray | Didukung | Didukung | | Deteksi sumber daya | Didukung | Didukung | | Anotasi segmen | Didukung | Didukung | | Metadata segmen | Didukung | Didukung | | Instrumentasi otomatis kode nol | Didukung di Jawa | Didukung di OTel Java/. NET/Python/Node.js
Didukung di ADOT Java/. NET/Python/Node.js | | Lacak pembuatan secara manual | Didukung | Didukung | ### Menyiapkan dan mengonfigurasi penelusuran Untuk membuat jejak OpenTelemetry, Anda memerlukan pelacak. Anda mendapatkan pelacak dengan menginisialisasi *Penyedia Pelacak* di aplikasi Anda. Ini mirip dengan bagaimana Anda menggunakan X-Ray Recorder untuk mengkonfigurasi X-Ray dan membuat segmen dan subsegmen dalam jejak X-Ray. **catatan** *Penyedia OpenTelemetry Tracer* menawarkan lebih banyak opsi konfigurasi daripada Perekam X-Ray. #### Memahami struktur data jejak Setelah memahami konsep dasar dan pemetaan fitur, Anda dapat mempelajari detail implementasi spesifik seperti struktur data jejak dan pengambilan sampel. OpenTelemetry menggunakan *bentang* alih-alih segmen dan subsegmen untuk menyusun data jejak. Setiap rentang mencakup komponen-komponen berikut: + Nama + ID Unik + Mulai dan akhiri stempel waktu + Jenis rentang + Konteks rentang + Atribut (metadata nilai kunci) + Acara (log stempel waktu) + Tautan ke bentang lainnya + Informasi status + Referensi rentang induk Saat Anda bermigrasi ke OpenTelemetry, rentang Anda secara otomatis dikonversi ke segmen atau subsegmen X-Ray. Ini memastikan pengalaman CloudWatch konsol Anda yang ada tetap tidak berubah. ##### Bekerja dengan atribut span X-Ray SDK menyediakan dua cara untuk menambahkan data ke segmen dan subsegmen: Anotasi Pasangan nilai kunci yang diindeks untuk pemfilteran dan pencarian Metadata Pasangan nilai kunci yang berisi data kompleks yang tidak diindeks untuk pencarian Secara default, atribut OpenTelemetry rentang dikonversi ke metadata dalam data mentah X-Ray. Untuk mengonversi atribut tertentu menjadi anotasi, tambahkan kuncinya ke daftar `aws.xray.annotations` atribut. + Untuk informasi selengkapnya tentang OpenTelemetry konsep, lihat [OpenTelemetry Jejak](https://opentelemetry.io/docs/concepts/signals/traces/) + Untuk detail tentang cara memetakan OpenTelemetry data ke data X-Ray, lihat [OpenTelemetry terjemahan model data X-Ray](https://aws-otel.github.io/docs/getting-started/X-Ray#otel-to-X-Ray-data-model-translation-behavior-of-aws-X-Ray-exporter) ### Mendeteksi sumber daya di lingkungan Anda OpenTelemetry menggunakan *Detektor Sumber Daya* untuk mengumpulkan metadata tentang sumber daya yang menghasilkan data telemetri. Metadata ini disimpan sebagai Atribut *Sumber Daya*. Misalnya, entitas yang memproduksi telemetri dapat berupa klaster Amazon ECS atau instans Amazon EC2, dan Atribut Sumber Daya yang dapat direkam dari entitas ini dapat menyertakan ARN Cluster Amazon ECS atau ID Instans Amazon EC2. + Untuk informasi tentang jenis sumber daya yang didukung, lihat Konvensi [Semantik OpenTelemetry Sumber Daya](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/) + Untuk informasi tentang plugin layanan X-Ray, lihat [Mengonfigurasi X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html) SDK ### Mengelola strategi pengambilan sampel Trace sampling membantu Anda mengelola biaya dengan mengumpulkan data dari subset permintaan yang representatif, bukan semua permintaan. Keduanya OpenTelemetry dan X-Ray mendukung pengambilan sampel, tetapi menerapkannya secara berbeda. **catatan** Pengambilan sampel kurang dari 100% jejak mengurangi biaya observabilitas Anda sambil mempertahankan wawasan yang berarti tentang kinerja aplikasi Anda. OpenTelemetry menyediakan beberapa strategi pengambilan sampel bawaan dan memungkinkan Anda membuat yang khusus. Anda juga dapat mengonfigurasi *X-Ray Remote Sampler* dalam beberapa bahasa SDK untuk menggunakan aturan sampling X-Ray. OpenTelemetry Strategi pengambilan sampel tambahan dari OpenTelemetry adalah: + Pengambilan Sampel Berbasis Orang Tua — Menghormati keputusan pengambilan sampel rentang induk sebelum menerapkan strategi pengambilan sampel tambahan + Trace ID Ratio Based Sampling -> Sampel secara acak persentase rentang tertentu + Pengambilan sampel ekor - Menerapkan aturan pengambilan sampel untuk menyelesaikan jejak di Kolektor OpenTelemetry + Custom sampler - Menerapkan logika sampling Anda sendiri menggunakan antarmuka sampling Untuk informasi tentang aturan pengambilan sampel X-Ray, lihat [Aturan pengambilan sampel di konsol X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) Untuk informasi tentang pengambilan sampel OpenTelemetry ekor, lihat Prosesor pengambilan [sampel ekor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) ### Mengelola konteks jejak X-Ray SDKs mengelola Konteks Segmen untuk menangani hubungan induk-anak dengan benar antara Segmen dan Subsegmen dalam jejak. OpenTelemetry menggunakan mekanisme serupa untuk memastikan bahwa bentang memiliki rentang induk yang benar. Ini menyimpan dan menyebarkan data penelusuran di seluruh konteks permintaan. Misalnya, ketika aplikasi Anda memproses permintaan dan membuat rentang server untuk mewakili permintaan itu, OpenTelemetry akan menyimpan rentang server dalam OpenTelemetry Konteks sehingga ketika rentang anak dibuat, rentang anak tersebut dapat mereferensikan rentang dalam Konteks sebagai induknya. ### Menyebarkan konteks jejak Baik X-Ray dan OpenTelemetry menggunakan header HTTP untuk menyebarkan konteks jejak di seluruh layanan. Ini memungkinkan Anda untuk menautkan data jejak yang dihasilkan oleh berbagai layanan dan mempertahankan keputusan pengambilan sampel. X-Ray SDK secara otomatis menyebarkan konteks jejak menggunakan header jejak X-Ray. Ketika satu layanan memanggil yang lain, header trace berisi konteks yang diperlukan untuk mempertahankan hubungan induk-anak antar jejak. OpenTelemetry mendukung beberapa format header jejak untuk propagasi konteks, termasuk: + Konteks Jejak W3C (default) + Header jejak X-Ray + Format kustom lainnya **catatan** Anda dapat mengonfigurasi OpenTelemetry untuk menggunakan satu atau beberapa format header. Misalnya, gunakan Propagator X-Ray untuk mengirim konteks jejak ke AWS layanan yang mendukung penelusuran X-Ray. Konfigurasikan dan gunakan Propagator X-Ray untuk memungkinkan penelusuran di seluruh AWS layanan. Ini memungkinkan Anda untuk menyebarkan konteks jejak ke titik akhir API Gateway dan layanan lain yang mendukung X-Ray. + Untuk informasi tentang header jejak X-Ray, lihat [Menelusuri header](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) di Panduan Pengembang X-Ray + Untuk informasi tentang propagasi OpenTelemetry konteks, lihat [Propagasi Konteks dan Konteks](https://opentelemetry.io/docs/concepts/context-propagation/) dalam dokumentasi OpenTelemetry ### Menggunakan instrumentasi perpustakaan X-Ray dan OpenTelemetry menyediakan instrumentasi perpustakaan yang memerlukan perubahan kode minimal untuk menambahkan penelusuran ke aplikasi Anda. X-Ray menyediakan fungsionalitas instrumentasi perpustakaan. Ini memungkinkan Anda untuk menambahkan instrumentasi X-Ray pra-bangun dengan perubahan kode aplikasi minimal. Instrumentasi ini mendukung pustaka tertentu seperti Klien AWS SDK dan HTTP, serta kerangka kerja web seperti Spring Boot atau Express.js. OpenTelemetryPustaka instrumentasi menghasilkan rentang detail untuk pustaka Anda melalui kait pustaka atau modifikasi kode otomatis, yang memerlukan sedikit perubahan kode. [Untuk menentukan apakah Library OpenTelemetry Instrumentations mendukung library Anda, cari di OpenTelemetry OpenTelemetry Registry at Registry.](https://opentelemetry.io/ecosystem/registry/) ### Mengekspor jejak X-Ray dan OpenTelemetry menggunakan metode yang berbeda untuk mengekspor data jejak. #### Ekspor jejak X-Ray X-Ray SDKs menggunakan emitor untuk mengirim data jejak: + Mengirim segmen dan subsegmen ke Daemon X-Ray + Menggunakan UDP untuk I/O non-pemblokiran + Dikonfigurasi secara default di SDK #### OpenTelemetry jejak ekspor OpenTelemetry menggunakan *Eksportir Span* yang dapat dikonfigurasi untuk mengirim data jejak: + *Menggunakan protokol *http/protobuf* atau grpc* + Ekspor mencakup titik akhir yang dipantau oleh Kolektor atau Agen OpenTelemetry CloudWatch + Memungkinkan konfigurasi eksportir khusus ### Memproses dan meneruskan jejak Baik X-Ray dan OpenTelemetry menyediakan komponen untuk menerima, memproses, dan meneruskan data jejak. #### Pemrosesan jejak X-Ray X-Ray Daemon menangani pemrosesan jejak: + Mendengarkan lalu lintas UDP dari X-Ray SDKs + Batch segmen dan subsegmen + Mengunggah batch ke layanan X-Ray #### OpenTelemetry pemrosesan jejak OpenTelemetry Kolektor menangani pemrosesan jejak: + Menerima jejak dari layanan berinstrumen + Memproses dan secara opsional memodifikasi data jejak + Mengirim jejak yang diproses ke berbagai backend, termasuk X-Ray **catatan** AWS CloudWatch Agen juga dapat menerima dan mengirim OpenTelemetry jejak ke X-Ray. Untuk informasi selengkapnya, lihat [Mengumpulkan metrik dan jejak dengan OpenTelemetry](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html). ### Pemrosesan rentang (OpenTelemetry-konsep spesifik) OpenTelemetry menggunakan Prosesor Span untuk memodifikasi rentang saat dibuat: + Memungkinkan membaca dan memodifikasi rentang saat pembuatan atau penyelesaian + Mengaktifkan logika kustom untuk penanganan rentang ### Bagasi (konsep OpenTelemetry -soecific) OpenTelemetryFitur Bagasi memungkinkan penyebaran data nilai kunci: + Memungkinkan meneruskan data arbitrer di samping konteks penelusuran + Berguna untuk menyebarkan informasi spesifik aplikasi melintasi batas layanan Untuk informasi tentang OpenTelemetry Kolektor, lihat [OpenTelemetry Kolektor](https://opentelemetry.io/docs/collector/) Untuk informasi tentang konsep X-Ray, lihat [konsep X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html) di Panduan Pengembang X-Ray ## Ikhtisar migrasi Bagian ini memberikan gambaran umum tentang perubahan kode yang diperlukan untuk migrasi. Daftar di bawah ini adalah panduan khusus bahasa dan langkah-langkah migrasi Daemon X-Ray. **penting** Untuk sepenuhnya bermigrasi dari instrumentasi X-Ray ke OpenTelemetry instrumentasi, Anda perlu: Ganti penggunaan X-Ray SDK dengan solusi OpenTelemetry Ganti Daemon X-Ray dengan CloudWatch Agen atau OpenTelemetry Kolektor (dengan Eksportir X-Ray) + [Migrasi ke OpenTelemetry Java](xray-migration-opentelemetry.md) + [Migrasi ke Go OpenTelemetry](manual-instrumentation-go.md) + [Migrasi ke Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md) + [Migrasi ke OpenTelemetry .NET](introduction-dotnet.md) + [Migrasi ke Python OpenTelemetry](migrate-xray-to-opentelemetry-python.md) + [Migrasi ke Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md) ### Rekomendasi untuk aplikasi baru dan yang sudah ada Untuk aplikasi baru dan yang sudah ada, disarankan untuk menggunakan solusi berikut untuk mengaktifkan penelusuran di aplikasi Anda: Instrumentasi + OpenTelemetry SDKs + AWS Distro untuk Instrumentasi OpenTelemetry Pengumpulan Data + OpenTelemetry Kolektor + CloudWatch Agen Setelah bermigrasi ke solusi OpenTelemetry berbasis, CloudWatch pengalaman Anda akan tetap sama. Anda masih dapat melihat jejak Anda dalam format yang sama di halaman Jejak dan Jejak Peta CloudWatch konsol, atau mengambil data jejak Anda melalui [ APIsX-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-api.html). ### Menelusuri perubahan pengaturan Anda perlu mengganti pengaturan X-Ray dengan OpenTelemetry pengaturan. **Perbandingan X-Ray dan OpenTelemetry Pengaturan** | Fitur | SDK X-Ray | OpenTelemetry | | --- | --- | --- | | Konfigurasi default | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/xray/latest/devguide/xray-sdk-migration.html) | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/xray/latest/devguide/xray-sdk-migration.html) | | Konfigurasi manual | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/xray/latest/devguide/xray-sdk-migration.html) | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/xray/latest/devguide/xray-sdk-migration.html) | ### Perubahan instrumentasi perpustakaan Perbarui kode Anda untuk menggunakan Instrumentasi OpenTelemetry Perpustakaan alih-alih Instrumentasi Perpustakaan X-Ray untuk AWS SDK, Klien HTTP, Kerangka Web, dan pustaka lainnya. Ini menghasilkan OpenTelemetry Jejak alih-alih Jejak X-Ray. **catatan** Perubahan kode bervariasi menurut bahasa dan perpustakaan. Lihat panduan migrasi khusus bahasa untuk petunjuk terperinci. ### Perubahan instrumentasi lingkungan Lambda Untuk digunakan OpenTelemetry dalam fungsi Lambda Anda, pilih salah satu opsi pengaturan berikut: 1. Gunakan Layer Lambda instrumentasi otomatis: + (Disarankan) Lapisan [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html) untuk OpenTelemetry **catatan** Untuk hanya menggunakan penelusuran, atur variabel lingkungan Lambda. `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` + [AWS Lapisan Lambda terkelola untuk ADOT](https://aws-otel.github.io/docs/getting-started/lambda) 1. Siapkan secara manual OpenTelemetry untuk fungsi Lambda Anda: + Konfigurasikan Prosesor Rentang Sederhana dengan Eksportir Rentang UDP X-Ray + Siapkan propagator X-Ray Lambda ### Membuat data jejak secara manual Ganti segmen X-Ray dan sub-segmen dengan OpenTelemetry Span: + Gunakan OpenTelemetry Tracer untuk membuat Span + Tambahkan atribut ke Span (setara dengan metadata dan anotasi X-Ray) **penting** Saat dikirim ke X-Ray: Rentang Server dikonversi ke segmen X-Ray Rentang lainnya dikonversi ke sub-segmen X-Ray Atribut dikonversi ke metadata secara default Untuk mengonversi atribut ke anotasi, tambahkan kuncinya ke daftar `aws.xray.annotations` atribut. 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). ## Migrasi dari X-Ray Daemon ke AWS CloudWatch agen atau kolektor OpenTelemetry Anda dapat menggunakan CloudWatch agen atau OpenTelemetry kolektor untuk menerima jejak dari aplikasi instrumentasi Anda dan mengirimkannya ke X-Ray. **catatan** CloudWatch Agen versi 1.300025.0 dan yang lebih baru dapat mengumpulkan jejak. OpenTelemetry Menggunakan CloudWatch agen alih-alih Daemon X-Ray mengurangi jumlah agen yang perlu Anda kelola. Untuk informasi selengkapnya, lihat [Mengumpulkan metrik, log, dan jejak dengan CloudWatch agen](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html). **Topics** + [Migrasi di Amazon EC2 atau server lokal](#ec2-onprem-migration) + [Migrasi di Amazon ECS](#ecs-migration) + [Migrasi pada Elastic Beanstalk](#beanstalk-migration) ### Migrasi di Amazon EC2 atau server lokal **penting** Hentikan proses Daemon X-Ray sebelum menggunakan CloudWatch agen atau OpenTelemetry kolektor untuk mencegah konflik port. #### Pengaturan Daemon X-Ray yang ada ##### Memasang daemon Penggunaan Daemon X-Ray Anda yang ada telah diinstal menggunakan salah satu metode berikut: Instalasi manual Unduh dan jalankan file yang dapat dieksekusi dari bucket X-Ray daemon Amazon S3. Instalasi otomatis Gunakan skrip ini untuk menginstal daemon saat meluncurkan instance: ``` #!/bin/bash curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \ -o /home/ec2-user/xray.rpm yum install -y /home/ec2-user/xray.rpm ``` ##### Mengonfigurasi daemon Penggunaan Daemon X-Ray Anda yang ada telah dikonfigurasi menggunakan: + Argumen baris perintah + File konfigurasi (`xray-daemon.yaml`) **Example Menggunakan file konfigurasi** ``` ./xray -c ~/xray-daemon.yaml ``` ##### Menjalankan daemon Penggunaan Daemon X-Ray Anda sudah dimulai dengan perintah berikut: ``` ~/xray-daemon$ ./xray -o -n us-east-1 ``` ##### Menghapus daemon Untuk menghapus Daemon X-Ray dari instans Amazon EC2 Anda: 1. Hentikan layanan daemon: ``` systemctl stop xray ``` 1. Hapus file konfigurasi: ``` rm ~/{{path}}/{{to}}/xray-daemon.yaml ``` 1. Jika dikonfigurasi, hapus file log: **catatan** Lokasi file log tergantung pada konfigurasi Anda: Konfigurasi baris perintah: `/var/log/xray-daemon.log` File konfigurasi: Periksa `LogPath` pengaturan #### Menyiapkan CloudWatch agen ##### Instalasi agen Untuk petunjuk penginstalan, lihat [Menginstal CloudWatch agen di server lokal](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_user-first). ##### Mengkonfigurasi agen 1. Buat file konfigurasi untuk mengaktifkan koleksi jejak. Untuk informasi selengkapnya, lihat [Membuat file konfigurasi CloudWatch agen](AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html). 1. Siapkan izin IAM: + Lampirkan peran IAM atau tentukan kredensil untuk agen. Untuk informasi selengkapnya, lihat [Menyiapkan peran IAM](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_permissions-first). + Pastikan peran atau kredensialnya menyertakan izin. `xray:PutTraceSegments` ##### Memulai agen Untuk instruksi untuk memulai agen, lihat [Memulai CloudWatch agen menggunakan baris perintah](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#start-CloudWatch-Agent-EC2-commands-fleet). #### Menyiapkan OpenTelemetry kolektor ##### Memasang kolektor Unduh dan instal OpenTelemetry kolektor untuk sistem operasi Anda. Untuk instruksi, lihat [Memasang kolektor](https://opentelemetry.io/docs/collector/installation/). ##### Mengkonfigurasi kolektor Konfigurasikan komponen berikut di kolektor Anda: + ekstensi awsproxy Diperlukan untuk pengambilan sampel X-Ray + OTel penerima Mengumpulkan jejak dari aplikasi Anda + eksportir xray Mengirim jejak ke X-Ray **Example Konfigurasi kolektor sampel - otel-collector-config .yaml** ``` extensions: awsproxy: endpoint: 127.0.0.1:2000 health_check: receivers: otlp: protocols: grpc: endpoint: 127.0.0.1:4317 http: endpoint: 127.0.0.1:4318 processors: batch: exporters: awsxray: region: 'us-east-1' service: pipelines: traces: receivers: [otlp] exporters: [awsxray] extensions: [awsproxy, health_check] ``` **penting** Konfigurasikan AWS kredensil dengan izin. `xray:PutTraceSegments` Untuk informasi selengkapnya, lihat [Menentukan kredensil](sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials). ##### Memulai kolektor Jalankan kolektor dengan file konfigurasi Anda: ``` otelcol --config=otel-collector-config.yaml ``` ### Migrasi di Amazon ECS **penting** Peran tugas Anda harus memiliki `xray:PutTraceSegments` izin untuk kolektor yang Anda gunakan. Hentikan kontainer X-Ray Daemon yang ada sebelum menjalankan CloudWatch agen atau wadah OpenTelemetry kolektor pada host yang sama untuk mencegah konflik port. #### Menggunakan CloudWatch agen 1. Dapatkan gambar Docker dari Galeri [Publik Amazon ECR](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent). 1. Buat file konfigurasi bernama`cw-agent-otel.json`: ``` { "traces": { "traces_collected": { "xray": { "tcp_proxy": { "bind_address": "0.0.0.0:2000" } }, "otlp": { "grpc_endpoint": "0.0.0.0:4317", "http_endpoint": "0.0.0.0:4318" } } } } ``` 1. Simpan konfigurasi di Systems Manager Parameter Store: 1. Buka [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 1. Pilih **Buat parameter** 1. Masukkan nilai berikut: + Nama: `/ecs/cwagent/otel-config` + Tingkat: Standar + Tipe: String + Tipe data: Teks + Nilai: [Tempel cw-agent-otel konfigurasi.json di sini] 1. Buat definisi tugas menggunakan mode jaringan jembatan: Dalam ketentuan tugas Anda, konfigurasi tergantung pada mode jaringan yang Anda gunakan. Jaringan jembatan adalah default dan dapat digunakan di VPC default Anda. Dalam jaringan jembatan, atur variabel `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` lingkungan untuk memberi tahu OpenTelemetry SDK apa titik akhir dan port untuk agen. CloudWatch Anda juga harus membuat link dari wadah aplikasi Anda ke wadah Collector untuk jejak yang akan dikirim dari OpenTelemetry SDK dalam aplikasi Anda ke wadah Collector. **Example CloudWatch definisi tugas agen** ``` { "containerDefinitions": [ { "name": "cwagent", "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "portMappings": [ { "containerPort": 4318, "hostPort": 4318, "protocol": "tcp" }, { "containerPort": 4317, "hostPort": 4317, "protocol": "tcp" }, { "containerPort": 2000, "hostPort": 2000, "protocol": "tcp" } ], "secrets": [ { "name": "CW_CONFIG_CONTENT", "valueFrom": "/ecs/cwagent/otel-config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["cwagent"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://cwagent:4318/v1/traces" } ] } ] } ``` Untuk informasi selengkapnya, lihat [Menerapkan CloudWatch agen untuk mengumpulkan metrik tingkat instans Amazon EC2](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html) di Amazon ECS. #### Menggunakan OpenTelemetry kolektor 1. Dapatkan gambar Docker `otel/opentelemetry-collector-contrib` dari [Docker Hub](https://hub.docker.com/r/otel/opentelemetry-collector-contrib). 1. Buat file konfigurasi yang disebut `otel-collector-config.yaml` menggunakan konten yang sama seperti yang ditunjukkan di **Amazon EC2 yang mengonfigurasi bagian kolektor, tetapi perbarui** titik akhir untuk digunakan, bukan. `0.0.0.0` `127.0.0.1` 1. Untuk menggunakan konfigurasi ini di Amazon ECS, Anda dapat menyimpan konfigurasi di Systems Manager Parameter Store. Pertama, buka konsol Systems Manager Parameter Store, dan pilih **Create new parameter**. Buat parameter baru dengan informasi berikut: + Nama:/ecs/otel/config(nama ini akan direferensikan dalam Definisi Tugas untuk Kolektor) + Tingkat: Standar + Tipe: String + Tipe data: Teks + Nilai: [Tempel otel-collector-config konfigurasi.yaml di sini] 1. Buat definisi tugas untuk menyebarkan OpenTelemetry kolektor menggunakan mode jaringan jembatan sebagai contoh. Dalam definisi tugas, konfigurasi tergantung pada mode jaringan yang Anda gunakan. Jaringan jembatan adalah default dan dapat digunakan di VPC default Anda. Dalam jaringan jembatan, atur variabel `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` lingkungan untuk memberi tahu OpenTelemetry SDK apa titik akhir dan port untuk Kolektor. OpenTelemetry Anda juga harus membuat link dari wadah aplikasi Anda ke wadah Collector untuk jejak yang akan dikirim dari OpenTelemetry SDK dalam aplikasi Anda ke wadah Collector. **Example OpenTelemetry definisi tugas kolektor** ``` { "containerDefinitions": [ { "name": "otel-collector", "image": "otel/opentelemetry-collector-contrib", "portMappings": [ { "containerPort": 2000, "hostPort": 2000 }, { "containerPort": 4317, "hostPort": 4317 }, { "containerPort": 4318, "hostPort": 4318 } ], "command": [ "--config", "env:SSM_CONFIG" ], "secrets": [ { "name": "SSM_CONFIG", "valueFrom": "/ecs/otel/config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["otel-collector"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://otel-collector:4318/v1/traces" } ] } ] } ``` ### Migrasi pada Elastic Beanstalk **penting** Hentikan proses Daemon X-Ray sebelum menggunakan CloudWatch agen untuk mencegah konflik port. Integrasi X-Ray Daemon Anda yang ada diaktifkan dengan menggunakan konsol Elastic Beanstalk, atau dengan mengonfigurasi X-Ray Daemon dalam kode sumber aplikasi Anda dengan file konfigurasi. #### Menggunakan CloudWatch agen Pada platform Amazon Linux 2, konfigurasikan CloudWatch agen menggunakan file `.ebextensions` konfigurasi: 1. Buat direktori bernama `.ebextensions` di root proyek Anda 1. Buat file bernama `cloudwatch.config` dalam `.ebextensions` direktori dengan konten berikut: ``` files: "/opt/aws/amazon-cloudwatch-agent/etc/config.json": mode: "0644" owner: root group: root content: | { "traces": { "traces_collected": { "otlp": { "grpc_endpoint": "12.0.0.1:4317", "http_endpoint": "12.0.0.1:4318" } } } } container_commands: start_agent: command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s ``` 1. Sertakan `.ebextensions` direktori dalam bundel sumber aplikasi Anda saat Anda menerapkan Untuk informasi selengkapnya tentang file konfigurasi Elastic Beanstalk[, lihat Kustomisasi lingkungan lanjutan](elasticbeanstalk/latest/dg/ebextensions.html) dengan file konfigurasi.