View a markdown version of this page

Debug aplikasi dengan Instrumentasi Dinamis - Amazon CloudWatch
KonsepBahasa yang didukungPrasyaratTambahkan instrumentasi dinamis ke aplikasi AndaPenyimpanan dataLihat dan kelola konfigurasiMemahami statusBatas tangkap

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

Debug aplikasi dengan Instrumentasi Dinamis

Dengan Instrumentasi Dinamis, Anda dapat menangkap status runtime dari aplikasi langsung tanpa memulai ulang atau menerapkan ulang. Status runtime mencakup nilai variabel, argumen metode, nilai pengembalian, dan jejak tumpukan. Anda menentukan konfigurasi instrumentasi yang menentukan tempat dalam kode Anda untuk menangkap data, dan agen yang sedang berjalan menginstrumentasikan aplikasi saat runtime.

Konsep

Breakpoint

Instrumentasi sementara yang kedaluwarsa otomatis. Kedaluwarsa default adalah 24 jam, dapat dikonfigurasi dari 5 menit hingga 24 jam. Gunakan breakpoint untuk debugging dan investigasi.

Menyelidiki

Instrumentasi permanen yang bertahan hingga dihapus secara eksplisit. Gunakan probe untuk observabilitas berkelanjutan.

Snapshot

Penangkapan point-in-time dari status program termasuk variabel lokal, argumen, nilai pengembalian, pengecualian, dan jejak tumpukan. Instrumentasi Dinamis memancarkan snapshot sebagai catatan log ke Log. CloudWatch

Lokasi

Lokasi kode tempat instrumentasi diterapkan. Bidang yang diperlukan berbeda menurut bahasa.

Bahasa yang didukung

  • Java

  • Python

  • JavaScript atau TypeScript

Prasyarat

Untuk menggunakan Instrumentasi Dinamis, perbarui komponen instrumentasi Anda ke versi terbaru berdasarkan jenis penerapan Anda:

  • Pelanggan Amazon EKS — Perbarui add-on Amazon CloudWatch Observability EKS ke versi terbaru. Add-on termasuk ADOT SDK dan Agen. CloudWatch Untuk informasi selengkapnya, lihat Menginstal add-on CloudWatch Observability EKS.

  • Semua pelanggan lain - Perbarui kedua komponen berikut:

    • AWS Distro for OpenTelemetry (ADOT) instrumentasi SDK untuk bahasa Anda (Java, Python, atau). Node.js

    • CloudWatch Agen ke versi terbaru.

Ketentuan berikut juga harus dipenuhi:

  • CloudWatch Sinyal Aplikasi harus diaktifkan untuk aplikasi Anda.

  • Tetapkan variabel lingkungan OTEL_AWS_DYNAMIC_INSTRUMENTATION_ENABLED=true pada aplikasi Anda.

  • Tetapkan variabel lingkungan OTEL_SERVICE_NAME ke nama layanan Anda.

  • Mengatur variabel lingkunganOTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=my_deployment_env_name. Untuk pengguna Sinyal Aplikasi yang ada, nilainya harus sesuai dengan nama Lingkungan untuk layanan Anda seperti yang muncul di konsol Sinyal Aplikasi.

  • CloudWatch Agen harus berjalan dengan konfigurasi Sinyal Aplikasi.

  • Instrumentasi Dinamis tidak didukung di lingkungan Lambda.

Tambahkan instrumentasi dinamis ke aplikasi Anda

Setelah Anda instrumen aplikasi Anda (lihatPrasyarat), Anda membuat konfigurasi instrumentasi yang menentukan bagian mana dari kode Anda yang ingin Anda perkenalkan telemetri dinamis. Setiap konfigurasi mendefinisikan dua hal:

  1. Dimana dalam kode untuk memantau — Lokasi kode tempat breakpoint atau probe diterapkan.

  2. Data apa yang harus diambil - Status runtime ditangkap saat breakpoint atau probe dijalankan.

catatan

Secara default, Instrumentasi Dinamis hanya menangkap data terbatas. Untuk memaksimalkan nilai fitur ini, pertimbangkan untuk memperluas konfigurasi pengambilan menggunakan opsi yang dijelaskan dalamBatas tangkap.

Anda dapat membuat konfigurasi menggunakan AWS CLI atau SDK, atau dengan menggunakan server Model Context Protocol (MCP) dengan asisten pengkodean AI di IDE Anda.

Buat konfigurasi menggunakan CLI atau SDK

Gunakan AWS CLI atau AWS SDK untuk membuat konfigurasi instrumentasi secara terprogram.

Tentukan lokasi kode

Lokasi menentukan di mana dalam kode Anda instrumentasi diterapkan. Bidang yang diperlukan berbeda menurut bahasa:

Bahasa Bidang yang Wajib Diisi Bidang Opsional
Java CodeUnit(paket),ClassName,MethodName, FilePath LineNumber
Python CodeUnit(modul),MethodName, FilePath LineNumber, ClassName
JavaScript atau TypeScript FilePath, LineNumber Tidak ada. Hanya breakpoint tingkat garis yang didukung. Probe dan breakpoint tingkat fungsi tidak didukung. TypeScript didukung saat Anda menyediakan peta sumber.

Konfigurasikan data apa yang akan diambil

Konfigurasi capture mengontrol status runtime yang dikumpulkan saat instrumentasi diaktifkan. Opsi yang tersedia:

  • CaptureArguments— Daftar nama argumen metode untuk ditangkap.

  • CaptureReturn— Tangkap nilai kembali (boolean).

  • CaptureStackTrace— Tangkap jejak tumpukan (boolean).

  • CaptureLocals— Daftar nama variabel lokal untuk ditangkap.

  • CaptureLimits— Kontrol kedalaman dan ukuran tangkapan (lihatBatas tangkap).

Parameter konfigurasi

Parameter kunci saat membuat konfigurasi:

  • instrumentation-type— BREAKPOINT atau PROBE

  • service— Nama layanan seperti yang dilaporkan oleh Sinyal Aplikasi

  • environment— Nama lingkungan

  • signal-type — SNAPSHOT

  • location— Bidang lokasi kode (lihat di atas)

  • capture-configuration— Opsi pengambilan (lihat di atas)

Contoh

Contoh berikut membuat breakpoint pada metode Java:

aws application-signals create-instrumentation-configuration \
    --instrumentation-type BREAKPOINT \
    --service "my-service" \
    --environment "production" \
    --signal-type SNAPSHOT \
    --location '{
        "CodeLocation": {
            "Language": "Java",
            "CodeUnit": "com.example.service",
            "ClassName": "OrderController",
            "MethodName": "processOrder",
            "FilePath": "OrderController.java"
        }
    }' \
    --capture-configuration '{
        "CodeCapture": {
            "CaptureArguments": ["orderId", "user"],
            "CaptureReturn": true,
            "CaptureStackTrace": true,
            "CaptureLimits": {
                "MaxHits": 100,
                "MaxStringLength": 255,
                "MaxCollectionWidth": 20,
                "MaxObjectDepth": 3,
                "MaxFieldsPerObject": 20,
                "MaxStackFrames": 20
            }
        }
    }'

Buat konfigurasi menggunakan server MCP

Pendekatan yang disarankan untuk menggunakan Instrumentasi Dinamis adalah melalui server CloudWatch Application Signals MCP (Model Context Protocol). MCP memungkinkan asisten dan agen pengkodean AI di IDE Anda untuk membuat, mengelola, dan menanyakan konfigurasi Instrumentasi Dinamis langsung dari lingkungan pengembangan Anda.

Menggunakan MCP, asisten AI Anda dapat:

  • Buat breakpoint dan probe di lokasi kode tertentu tanpa meninggalkan editor Anda.

  • Kueri diambil snapshot untuk memeriksa nilai variabel runtime dan jalur panggilan.

  • Secara otomatis mengkorelasikan data snapshot dengan kode yang sedang Anda kerjakan untuk menyarankan perbaikan.

  • Mengelola siklus hidup konfigurasi instrumentasi (melihat status, menghapus breakpoint kedaluwarsa).

Untuk petunjuk penyiapan dan penggunaan, lihat server MCP Sinyal Aplikasi di GitHub situs web.

Penyimpanan data

Saat breakpoint atau probe diaktifkan, Dynamic Instrumentation membuat grup CloudWatch log di Log dengan awalan /aws/application-signals/service-name (di mana service-name nilai variabel OTEL_SERVICE_NAME lingkungan Anda) dan menulis snapshot yang diambil sebagai catatan log ke grup log tersebut.

Jika grup log belum ada, Dynamic Instrumentation membuatnya secara otomatis saat pertama kali snapshot dipancarkan. Anda ditagih untuk konsumsi log dan penyimpanan dengan tarif Log standar CloudWatch .

Lihat dan kelola konfigurasi

Di CloudWatch konsol, navigasikan ke halaman detail layanan dan pilih tab Instrumentasi.

  • Beralih antara Breakpoint dan Probe untuk melihat konfigurasi berdasarkan jenis.

  • Lihat detail konfigurasi termasuk deskripsi, konfigurasi pengambilan, lokasi, ARN, dan waktu kedaluwarsa.

  • Lihat riwayat status untuk melacak transisi: Siap Aktif ke Error/Disabled.

  • Hapus konfigurasi yang tidak lagi diperlukan.

Memahami status

Setiap konfigurasi instrumentasi memiliki status yang menunjukkan keadaan saat ini.

Status Deskripsi
SEDIA Agen menerima konfigurasi.
AKTIF Agen menerapkan instrumentasi ke aplikasi yang sedang berjalan.
ERROR Instrumentasi gagal diterapkan. Lihat penyebab kesalahan untuk detailnya.
DISABLED Instrumentasi kedaluwarsa, atau Anda menghapusnya.

Ketika instrumentasi memasuki status ERROR, penyebab berikut mungkin dilaporkan:

Penyebab Kesalahan Deskripsi
FILE_NOT_FOUND Jalur file yang ditentukan tidak ada dalam aplikasi.
METHOD_NOT_FOUND Metode yang ditentukan tidak ada di kelas target atau modul.
LINE_NOT_EXECUTABLE Nomor baris yang ditentukan tidak sesuai dengan pernyataan yang dapat dieksekusi.
OVERLOADED_METHODS Beberapa metode cocok dengan nama yang ditentukan. Berikan detail lokasi tambahan untuk mengidentifikasi metode yang benar.
LANGUAGE_MISMATCH Bidang lokasi tidak cocok dengan bahasa aplikasi yang sedang berjalan.
RUNTIME_ERROR Terjadi kesalahan tak terduga saat menerapkan instrumentasi.

Batas tangkap

Batas pengambilan mengontrol ukuran dan kedalaman data yang diambil. Konfigurasikan nilai-nilai ini di capture-limits bidang konfigurasi tangkapan.

Kuota Default Kisaran Deskripsi
maks StringLength 255 1—255 Karakter maksimum yang ditangkap per nilai string.
maks CollectionWidth 20 1—20 Elemen maksimum ditangkap per koleksi atau array.
maks ObjectDepth 3 1—5 Kedalaman maksimum untuk traversal objek bersarang.
maks FieldsPerObject 20 1—20 Bidang maksimum yang ditangkap per objek.
maks StackFrames 20 1—20 Bingkai tumpukan maksimum ditangkap.
MaxHits 100 1—1000 Tangkapan maksimum sebelum menonaktifkan otomatis. Hanya breakpoint.

Setiap titik instrumentasi dibatasi kecepatan hingga 5 tangkapan per detik.