Menggunakan ekspresi filter - AWS X-Ray

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

Menggunakan ekspresi filter

Gunakan ekspresi filter untuk melihat peta jejak atau jejak untuk permintaan tertentu, layanan, koneksi antara dua layanan (tepi), atau permintaan yang memenuhi suatu kondisi. X-Ray menyediakan bahasa ekspresi filter untuk memfilter permintaan, layanan, dan edge berdasarkan data dalam header permintaan, status respons, dan bidang yang diindeks pada segmen asli.

Ketika Anda memilih jangka waktu pelacakan untuk dilihat di konsol X-Ray, Anda mungkin mendapatkan lebih banyak hasil daripada yang dapat ditampilkan konsol tersebut. Di sudut kanan atas, konsol menunjukkan jumlah pelacakan yang dipindai dan apakah ada lebih banyak pelacakan yang tersedia. Anda dapat menggunakan ekspresi filter untuk mempersempit hasil hanya jejak yang ingin Anda temukan.

Detail ekspresi filter

Saat Anda memilih node di peta jejak, konsol akan membuat ekspresi filter berdasarkan nama layanan node, dan jenis kesalahan yang ada berdasarkan pilihan Anda. Untuk menemukan pelacakan yang menunjukkan masalah performa atau yang terkait dengan permintaan tertentu, Anda dapat menyesuaikan ekspresi yang disediakan konsol tersebut atau membuat ekspresi Anda sendiri. Jika Anda menambahkan anotasi dengan X-RaySDK, Anda juga dapat memfilter berdasarkan keberadaan kunci anotasi atau nilai kunci.

catatan

Jika Anda memilih rentang waktu relatif di peta jejak dan memilih simpul, konsol mengubah rentang waktu menjadi waktu mulai dan berakhir mutlak. Untuk memastikan bahwa pelacakan untuk simpul muncul di hasil pencarian, dan menghindari waktu pemindaian saat simpul tidak aktif, rentang waktu hanya mencakup waktu ketika simpul mengirim pelacakan. Untuk mencari relatif terhadap waktu saat ini, Anda dapat beralih kembali ke rentang waktu relatif di halaman pelacakan dan memindai kembali.

Jika masih ada lebih banyak hasil yang tersedia daripada yang dapat ditampilkan konsol, konsol menunjukkan kepada Anda berapa banyak pelacakan yang cocok dan jumlah pelacakan yang dipindai. Persentase yang ditampilkan adalah persentase dari kerangka waktu yang dipilih yang dipindai. Untuk memastikan bahwa Anda melihat semua pelacakan yang cocok terwakili dalam hasil, persempit ekspresi filter Anda lebih lanjut, atau pilih jangka waktu yang lebih singkat.

Untuk mendapatkan hasil terbaru terlebih dahulu, konsol mulai memindai pada akhir rentang waktu dan bekerja mundur. Jika ada banyak pelacakan, tetapi sedikit hasil, konsol tersebut membagi rentang waktu menjadi beberapa bagian dan memindainya secara paralel. Bilah kemajuan menunjukkan bagian dari rentang waktu yang telah dipindai.

Progress bar showing 52% of time range scanned, with 49 matching traces found.

Menggunakan ekspresi filter dengan grup

Grup adalah kumpulan pelacakan yang ditentukan oleh ekspresi filter. Anda dapat menggunakan grup untuk menghasilkan grafik layanan tambahan dan menyediakan CloudWatch metrik Amazon.

Grup diidentifikasi berdasarkan namanya atau Amazon Resource Name (ARN), dan berisi ekspresi filter. Layanan membandingkan pelacakan yang masuk dengan ekspresi dan menyimpannya sesuai dengan itu.

Anda dapat membuat dan memodifikasi grup dengan menggunakan menu tarik-turun di sebelah kiri bilah pencarian ekspresi filter.

catatan

Jika layanan mengalami kesalahan dalam kualifikasi grup, grup tersebut tidak lagi disertakan dalam memproses pelacakan masuk dan metrik kesalahan dicatat.

Untuk informasi selengkapnya tentang grup opsi, lihat Mengkonfigurasi grup.

Sintaks ekspresi filter

Ekspresi filter dapat berisi Kata Kunci, unary atau biner Operator, dan nilai untuk perbandingan.

keyword operator value

Operator yang berbeda tersedia untuk berbagai tipe kata kunci. Misalnya, responsetime adalah kata kunci nomor dan dapat dibandingkan dengan operator yang terkait dengan nomor.

contoh – permintaan saat waktu respons lebih besar dari 5 detik
responsetime > 5

Anda dapat menggabungkan beberapa ekspresi dalam ekspresi gabungan dengan menggunakan operator AND atau OR.

contoh – permintaan saat total durasi adalah 5-8 detik
duration >= 5 AND duration <= 8

Kata kunci dan operator sederhana hanya menemukan masalah di tingkat penelusuran. Jika kesalahan terjadi di hilir, tetapi ditangani oleh aplikasi Anda dan tidak dikembalikan ke pengguna, pencarian untuk error tidak akan menemukannya.

Untuk menemukan pelacakan dengan masalah hilir, Anda dapat menggunakan kata kunci kompleks service() dan edge(). Kata kunci ini memungkinkan Anda menerapkan ekspresi filter ke semua simpul hilir, satu simpul hilir, atau tepi di antara dua simpul. Untuk perincian lebih lanjut, Anda dapat memfilter layanan dan edge berdasarkan tipe dengan fungsi id().

Kata Kunci Boolean

Nilai kata kunci Boolean adalah BETUL atau SALAH. Gunakan kata kunci ini untuk menemukan pelacakan yang mengakibatkan kesalahan.

Kata Kunci Boolean
  • ok – Kode status respons 2XX Berhasil.

  • error – Kode status respons 4XX Kesalahan Klien.

  • throttle – Kode status respons 429 Terlalu Banyak Permintaan.

  • fault – Kode status respons 5XX Kesalahan Server.

  • partial – Permintaan memiliki segmen yang tidak lengkap.

  • inferred – Permintaan memiliki segmen yang disimpulkan.

  • first - Elemen adalah yang pertama dari daftar enumerasi.

  • last - Elemen adalah yang terakhir dari daftar enumerasi.

  • remote – Entitas akar masalah jarak jauh.

  • root – Layanan adalah titik masuk atau segmen akar dari suatu pelacakan.

Operator Boolean menemukan segmen saat kunci yang ditentukan adalah true atau false.

Operator Boolean
  • Tidak ada - Ekspresi benar jika kata kunci benar.

  • ! - Ekspresi benar jika kata kunci salah.

  • =,!= – Bandingkan nilai kata kunci dengan string true atau false. Operator ini bertindak sama dengan operator lain tetapi lebih eksplisit.

contoh – status respons 2XX OK
ok
contoh – status respons bukan 2XX OK
!ok
contoh – status respons bukan 2XX OK
ok = false
contoh – pelacakan kesalahan yang disebutkan terakhir memiliki nama kesalahan "deserialize"
rootcause.fault.entity { last and name = "deserialize" }
contoh – permintaan dengan segmen jarak jauh saat cakupan lebih besar dari 0,7 dan nama layanannya adalah "pelacakan"
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
contoh — permintaan dengan segmen yang disimpulkan di mana jenis layanan adalah “: DynamoDB” AWS
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
contoh – permintaan yang memiliki segmen dengan nama "data-plane" sebagai root
service("data-plane") {root = true and fault = true}

Kata Kunci nomor

Gunakan kata kunci angka untuk mencari permintaan dengan waktu respons, durasi, atau status respons tertentu.

Kata Kunci nomor
  • responsetime – Waktu yang dibutuhkan server untuk mengirim respons.

  • duration – Total permintaan, termasuk semua panggilan hilir.

  • http.status – Kode status respons.

  • index – Posisi elemen dalam daftar enumerasi.

  • coverage – Persentase desimal waktu respons entitas selama waktu respons segmen akar. Hanya berlaku untuk entitas akar masalah waktu respons.

Operasi nomor

Kata kunci angka menggunakan persamaan standar dan operator perbandingan.

  • =,!= – Kata kunci sama dengan atau tidak sama dengan nilai angka.

  • <,<=, >,>= – Kata kunci kurang dari atau lebih besar dari nilai angka.

contoh – status respons bukan 200 OK
http.status != 200
contoh – permintaan saat total durasinya adalah 5–8 detik
duration >= 5 AND duration <= 8
contoh – permintaan yang berhasil diselesaikan dalam waktu kurang dari 3 detik, termasuk semua panggilan hilir
ok !partial duration <3
contoh – entitas daftar enumerasi yang memiliki indeks lebih besar dari 5
rootcause.fault.service { index > 5 }
contoh – permintaan saat entitas terakhir yang memiliki cakupan lebih besar dari 0,8
rootcause.responsetime.entity { last and coverage > 0.8 }

Kata Kunci String

Gunakan kata kunci string untuk menemukan jejak dengan teks tertentu di header permintaan, atau pengguna IDs tertentu.

Kata Kunci String
  • http.url— PermintaanURL.

  • http.method – Metode permintaan.

  • http.useragent – Meminta string agen pengguna.

  • http.clientip – Alamat IP Peminta.

  • user – Nilai dari bidang pengguna pada setiap segmen dalam pelacakan.

  • name – Nama layanan atau pengecualian.

  • type – Tipe Layanan.

  • message – Pesan pengecualian.

  • availabilityzone – Nilai ketersediaan bidang zona pada setiap segmen dalam pelacakan.

  • instance.id – Nilai bidang ID instans pada setiap segmen dalam pelacakan.

  • resource.arn— Nilai ARN bidang sumber daya pada setiap segmen dalam jejak.

Operator string menemukan nilai yang sama dengan atau berisi teks tertentu. Nilai harus selalu ditentukan dalam tanda kutip.

Operator String
  • =,!= – Kata kunci adalah sama dengan atau tidak sama dengan nilai angka.

  • CONTAINS – Kata kunci berisi string tertentu.

  • BEGINSWITH , ENDSWITH – Kata kunci dimulai atau diakhiri dengan string tertentu.

contoh – filter http.url
http.url CONTAINS "/api/game/"

Untuk menguji apakah suatu bidang ada pada pelacakan, terlepas dari nilainya, periksa untuk melihat apakah bidang tersebut berisi string kosong.

contoh – filter pengguna

Temukan semua jejak dengan penggunaIDs.

user CONTAINS ""
contoh – pilih pelacakan dengan penyebab akar masalah yang mencakup layanan bernama "Auth"
rootcause.fault.service { name = "Auth" }
contoh – pilih pelacakan dengan akar masalah waktu respons yang layanan terakhirnya memiliki tipe DynamoDB
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
contoh – pilih pelacakan dengan akar penyebab kesalahan yang pengecualian terakhirnya memiliki pesan "akses ditolak untuk akun_id: 1234567890"
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"

Kata Kunci Kompleks

Gunakan kata kunci yang kompleks untuk menemukan permintaan berdasarkan nama layanan, nama edge, atau nilai anotasi. Untuk layanan dan edge, Anda dapat menentukan ekspresi filter tambahan yang berlaku untuk layanan atau edge. Untuk anotasi, Anda dapat memfilter nilai anotasi dengan kunci tertentu menggunakan operator Boolean, angka, atau string.

Kata Kunci Kompleks
  • annotation[key]— Nilai anotasi dengan bidang key. Nilai anotasi dapat berupa Boolean, angka, atau string, sehingga Anda dapat menggunakan salah satu operator perbandingan dari jenis tersebut. Anda dapat menggunakan kata kunci ini dalam kombinasi dengan edge kata kunci service atau. Kunci anotasi yang berisi titik (titik) harus dibungkus dengan tanda kurung siku ([]).

  • edge(source, destination) {filter}— Koneksi antar layanan source and destination. Kurung kurawal opsional dapat berisi ekspresi filter yang berlaku untuk segmen pada koneksi ini.

  • group.name / group.arn— Nilai ekspresi filter grup, direferensikan oleh nama grup atau grupARN.

  • json— JSON akar penyebab objek. Lihat Mendapatkan data dari AWS X-Ray untuk langkah-langkah membuat JSON entitas secara terprogram.

  • service(name) {filter}— Layanan dengan nama name. Kurung kurawal opsional dapat berisi ekspresi filter yang berlaku untuk segmen yang dibuat oleh layanan.

Gunakan kata kunci layanan untuk menemukan jejak permintaan yang mengenai node tertentu di peta jejak Anda.

Operator kata kunci yang kompleks menemukan segmen saat kunci yang ditentukan telah diset, atau tidak diset.

Operator kata kunci kompleks
  • Tidak ada - Ekspresi benar jika kata kunci diset. Jika kata kunci bertipe boolean, maka akan dievaluasi ke nilai boolean.

  • ! – Ekspresi benar jika kata kunci tidak diset. Jika kata kunci bertipe boolean, maka akan dievaluasi ke nilai boolean.

  • =,!= – Bandingkan nilai kata kunci.

  • edge(source, destination) {filter}— Koneksi antar layanan source and destination. Kurung kurawal opsional dapat berisi ekspresi filter yang berlaku untuk segmen pada koneksi ini.

  • annotation[key]— Nilai anotasi dengan bidang key. Nilai anotasi dapat berupa Boolean, angka, atau string, sehingga Anda dapat menggunakan salah satu operator perbandingan dari jenis tersebut. Anda dapat menggunakan kata kunci ini dalam kombinasi dengan edge kata kunci service atau.

  • json— JSON akar penyebab objek. Lihat Mendapatkan data dari AWS X-Ray untuk langkah-langkah membuat JSON entitas secara terprogram.

Gunakan kata kunci layanan untuk menemukan jejak permintaan yang mengenai node tertentu di peta jejak Anda.

contoh – Filter layanan

Permintaan yang mencakup panggilan ke api.example.com dengan kesalahan (kesalahan seri 500).

service("api.example.com") { fault }

Anda dapat mengecualikan nama layanan untuk menerapkan ekspresi filter ke semua simpul di peta layanan Anda.

contoh – Filter layanan

Permintaan yang menyebabkan kesalahan di mana saja di peta jejak Anda.

service() { fault }

Kata kunci edge menerapkan ekspresi filter ke koneksi antara dua simpul.

contoh – filter edge

Permintaan saat layanan api.example.com melakukan panggilan ke backend.example.com yang gagal dengan kesalahan.

edge("api.example.com", "backend.example.com") { error }

Anda juga dapat menggunakan operator ! dengan kata kunci layanan dan edge untuk mengecualikan layanan atau edge dari hasil ekspresi filter lain.

contoh – filter layanan dan permintaan

Permintaan di mana URL dimulai dengan http://api.example.com/ dan berisi /v2/ tetapi tidak mencapai layanan bernamaapi.example.com.

http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
contoh – filter layanan dan waktu respons

Temukan pelacakan saat http url diset dan waktu respons lebih dari 2 detik.

http.url AND responseTime > 2

Untuk anotasi, Anda dapat menghubungi semua pelacakan tempat annotation[key] diatur, atau menggunakan operator perbandingan yang sesuai dengan tipe nilai.

contoh – anotasi dengan nilai string

Permintaan dengan anotasi bernama gameid dengan nilai string "817DL6VO".

annotation[gameid] = "817DL6VO"
contoh – anotasi diset

Permintaan dengan anotasi bernama set age.

annotation[age]
contoh – anotasi tidak diset

Permintaan tanpa anotasi bernama set age.

!annotation[age]
contoh – anotasi dengan nilai angka

Permintaan dengan usia anotasi dengan nilai numerik lebih besar dari 29.

annotation[age] > 29
contoh — anotasi dalam kombinasi dengan layanan atau tepi

service { annotation[request.id] = "917DL6VO" }
edge { source.annotation[request.id] = "916DL6VO" }
edge { destination.annotation[request.id] = "918DL6VO" }
contoh – grup dengan pengguna

Permintaan saat pelacakan memenuhi filter grup high_response_time (misalnya responseTime > 3), dan pengguna bernama Alice.

group.name = "high_response_time" AND user = "alice"
contoh — JSON dengan entitas akar penyebab

Permintaan dengan entitas akar masalah yang cocok.

rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

fungsi id

Ketika Anda memberikan nama layanan untuk kata kunci service atau edge, Anda mendapatkan hasil untuk semua simpul yang memiliki nama tersebut. Untuk pemfilteran yang lebih tepat, Anda dapat menggunakan fungsi id untuk menentukan tipe layanan selain nama untuk membedakan antara simpul dengan nama yang sama.

Gunakan account.id fungsi untuk menentukan akun tertentu untuk layanan, saat melihat jejak dari beberapa akun di akun pemantauan.

id(name: "service-name", type:"service::type", account.id:"account-ID")

Anda dapat menggunakan fungsi id sebagai pengganti nama layanan dalam filter layanan dan edge.

service(id(name: "service-name", type:"service::type")) { filter }
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }

Misalnya, AWS Lambda fungsi menghasilkan dua node di peta jejak; satu untuk pemanggilan fungsi, dan satu untuk layanan Lambda. Kedua simpul memiliki nama yang sama tetapi berbeda tipe. Filter layanan standar akan menemukan pelacakan untuk keduanya.

contoh – Filter layanan

Permintaan yang mencakup kesalahan pada layanan bernama random-name.

service("function-name") { error }

Gunakan fungsi id untuk mempersempit pencarian ke kesalahan pada fungsi itu sendiri, tidak termasuk kesalahan dari layanan.

contoh – filter layanan dengan fungsi id

Permintaan yang mencakup kesalahan pada layanan bernama random-namedengan tipe AWS::Lambda::Function.

service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }

Untuk mencari simpul berdasarkan tipe, Anda juga dapat mengecualikan nama sepenuhnya.

contoh — filter layanan dengan fungsi id dan jenis layanan

Permintaan yang menyertakan kesalahan pada layanan dengan tipe AWS::Lambda::Function.

service(id(type: "AWS::Lambda::Function")) { error }

Untuk mencari node tertentu Akun AWS, tentukan ID akun.

contoh — filter layanan dengan fungsi id dan ID akun

Permintaan yang menyertakan layanan dalam ID akun tertentuAWS::Lambda::Function.

service(id(account.id: "account-id"))