Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Mengkonfigurasi X-Ray SDK untuk Java
X-Ray SDK untuk Java mencakup kelas bernama AWSXRay
yang menyediakan perekam global. Ini adalah TracingHandler
yang dapat Anda gunakan untuk menginstrumentasikan kode Anda. Anda dapat mengonfigurasi perekam global untuk menyesuaikan segmen AWSXRayServletFilter
yang membuat untuk HTTP panggilan masuk.
Bagian-bagian
Plugin layanan
Gunakan plugins
untuk mencatat informasi tentang layanan yang meng-hosting aplikasi Anda.
Plugin
Amazon EC2 —
EC2Plugin
menambahkan ID instans, Availability Zone, dan Grup CloudWatch Log.Elastic Beanstalk –
ElasticBeanstalkPlugin
menambahkan nama lingkungan, label versi, dan ID deployment.Amazon ECS -
ECSPlugin
menambahkan ID penampung.Amazon EKS —
EKSPlugin
menambahkan ID kontainer, nama cluster, ID pod, dan Grup CloudWatch Log.
![Segmentasikan data sumber daya dengan plugin Amazon EC2 dan Elastic Beanstalk.](images/scorekeep-PUTrules-segment-resources.png)
Untuk menggunakan plugin, hubungi withPlugin
di AWSXRayRecorderBuilder
Anda.
contoh src/main/java/scorekeep/ WebConfig .java - perekam
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
SDKJuga menggunakan pengaturan plugin untuk mengatur origin
bidang pada segmen. Ini menunjukkan jenis AWS sumber daya yang menjalankan aplikasi Anda. Bila Anda menggunakan beberapa plugin, SDK menggunakan urutan resolusi berikut untuk menentukan asal: ElasticBeanstalk > > EKS ECS >EC2.
Aturan pengambilan sampel
SDKMenggunakan aturan pengambilan sampel yang Anda tentukan di konsol X-Ray untuk menentukan permintaan mana yang akan direkam. Aturan default menelusuri permintaan pertama setiap detik, dan lima persen permintaan tambahan di semua layanan yang mengirim pelacakan ke X-Ray. Buat aturan tambahan di konsol X-Ray untuk menyesuaikan jumlah data yang dicatat untuk setiap aplikasi Anda.
Aturan kustom SDK berlaku dalam urutan di mana mereka didefinisikan. Jika permintaan cocok dengan beberapa aturan kustom, hanya SDK berlaku aturan pertama.
catatan
Jika tidak SDK dapat mencapai X-Ray untuk mendapatkan aturan sampling, itu akan kembali ke aturan lokal default dari permintaan pertama setiap detik, dan lima persen dari permintaan tambahan per host. Hal ini dapat terjadi jika host tidak memiliki izin untuk memanggil samplingAPIs, atau tidak dapat terhubung ke daemon X-Ray, yang bertindak sebagai TCP proxy untuk API panggilan yang dilakukan oleh. SDK
Anda juga dapat mengonfigurasi aturan pengambilan sampel SDK untuk memuat dari JSON dokumen. SDKDapat menggunakan aturan lokal sebagai cadangan untuk kasus di mana pengambilan sampel X-Ray tidak tersedia, atau menggunakan aturan lokal secara eksklusif.
contoh sampling-rules.json
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
Contoh ini menentukan satu aturan kustom dan aturan default. Aturan kustom menerapkan tingkat pengambilan sampel lima persen tanpa jumlah minimum permintaan untuk melacak jalur di /api/move/
. Aturan default menelusuri permintaan pertama setiap detik dan 10 persen dari permintaan tambahan.
Kerugian dari menentukan aturan secara lokal adalah bahwa target tetap diterapkan oleh setiap instans pencatat secara independen, alih-alih dikelola oleh layanan X-Ray. Ketika Anda men-deploy lebih banyak host, laju tetap akan dikalikan, sehingga sulit untuk mengontrol jumlah data yang dicatat.
AWS Lambda Aktif, Anda tidak dapat mengubah laju pengambilan sampel. Jika fungsi Anda dipanggil oleh layanan yang diinstrumentasikan, panggilan yang menghasilkan permintaan yang sampelnya diambil oleh layanan yang akan dicatat oleh Lambda. Jika pelacakan aktif diaktifkan dan tidak ada header pelacakan, Lambda membuat keputusan pengambilan sampel.
Untuk memberikan aturan cadangan di Spring, konfigurasi pencatat global dengan CentralizedSamplingStrategy
di kelas konfigurasi.
contoh src/main/java/myapp/ .java WebConfig - konfigurasi perekam
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
Untuk Tomcat, tambahkan listener yang memperluas ServletContextListener
dan mendaftarkan listener di pendeskripsi deployment.
contoh src/com/myapp/web/Startup.java
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
public class Startup implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent event) {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = Startup.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
@Override
public void contextDestroyed(ServletContextEvent event) { }
}
contoh WEB- INF /web.xml
...
<listener>
<listener-class>com.myapp.web.Startup</listener-class>
</listener>
Untuk menggunakan aturan lokal saja, ganti CentralizedSamplingStrategy
dengan LocalizedSamplingStrategy
.
builder.withSamplingStrategy(new
LocalizedSamplingStrategy
(ruleFile));
Pencatatan log
Secara default, SDK menampilkan pesan ERROR
-level ke log aplikasi Anda. Anda dapat mengaktifkan logging tingkat debug SDK untuk mengeluarkan log yang lebih rinci ke file log aplikasi Anda. Level log yang valid adalah DEBUG
INFO
,WARN
,,ERROR
, danFATAL
. FATAL
tingkat log membungkam semua pesan log karena SDK tidak log pada tingkat fatal.
contoh application.properties
Atur tingkat pencatatan dengan properti logging.level.com.amazonaws.xray
.
logging.level.com.amazonaws.xray = DEBUG
Gunakan log debug untuk mengidentifikasi masalah, seperti subsegmen yang tidak tertutup, saat Anda menghasilkan subsegmen secara manual.
Injeksi ID pelacakan ke log
Untuk mengekspos ID jejak yang sepenuhnya memenuhi syarat saat ini ke pernyataan log Anda, Anda dapat menyuntikkan ID ke dalam konteks diagnostik yang dipetakan (). MDC Menggunakan antarmuka SegmentListener
, metode dipanggil dari pencatat X-Ray selama peristiwa siklus hidup segmen. Ketika segmen atau subsegmen dimulai, ID jejak yang memenuhi syarat disuntikkan ke dalam MDC dengan kunciAWS-XRAY-TRACE-ID
. Ketika segmen itu berakhir, kunci dihapus dariMDC. Hal ini memperlihatkan ID pelacakan ke pustaka pencatatan yang digunakan. Ketika subsegmen berakhir, ID induknya disuntikkan ke dalam. MDC
contoh ID pelacakan yang memenuhi syarat
ID yang memenuhi syarat direpresentasikan sebagai TraceID@EntityID
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3
Fitur ini bekerja dengan aplikasi Java yang diinstrumentasi dengan AWS X-Ray SDK untuk Java, dan mendukung konfigurasi logging berikut:
-
SLF4Jfront-end API dengan backend Logback
-
SLF4Jfront-end dengan backend API Log4J2
-
Log4J2 front-end API dengan backend Log4J2
Lihat tab berikut untuk kebutuhan setiap front end dan backend.
Contoh Injeksi ID pelacakan
Berikut menunjukkan string PatternLayout
yang diubah untuk menyertakan pelacakan ID. ID pelacakan dicetak setelah nama thread (%t
) dan sebelum tingkat log (%-5p
).
contoh PatternLayout
Dengan Injeksi ID
%d{HH:mm:ss.SSS} [%t]
%X{AWS-XRAY-TRACE-ID}
%-5p %m%n
AWS X-Ray secara otomatis mencetak kunci dan ID jejak dalam pernyataan log untuk memudahkan penguraian. Berikut ini menunjukkan pernyataan log menggunakan PatternLayout
yang diubah.
contoh Pernyataan log dengan injeksi ID
2019-09-10 18:58:30.844 [nio-5000-exec-4]
AWS-XRAY-TRACE-ID
: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 -Your logging message here
Pesan pencatatan itu sendiri ditempatkan dalam pola %m
dan diatur saat memanggil pencatat.
Listener segmen
Pendengar segmen adalah antarmuka untuk mencegat peristiwa siklus hidup seperti awal dan akhir segmen yang dihasilkan oleh. AWSXRayRecorder
Implementasi fungsi peristiwa pendengar segmen mungkin dengan menambahkan anotasi yang sama ke semua subsegmen saat dibuat onBeginSubsegment
, mencatat pesan setelah setiap segmen dikirim ke daemon menggunakan afterEndSegment
, atau merekam kueri yang dikirim oleh SQL pencegat menggunakan beforeEndSubsegment
untuk memverifikasi apakah subsegmen mewakili kueri, menambahkan metadata tambahan jika demikian. SQL
Untuk melihat daftar lengkap SegmentListener
fungsi, kunjungi dokumentasi untuk AWS X-Ray Perekam SDK untuk Java API.
Contoh berikut menunjukkan cara menambahkan anotasi yang konsisten untuk semua subsegmen pada pembuatan dengan onBeginSubsegment
dan untuk mencetak pesan log di akhir setiap segmen dengan afterEndSegment
.
contoh MySegmentListener.jawa
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;
public class MySegmentListener implements SegmentListener {
.....
@Override
public void onBeginSubsegment(Subsegment subsegment) {
subsegment.putAnnotation("annotationKey
", "annotationValue
");
}
@Override
public void afterEndSegment(Segment segment) {
// Be mindful not to mutate the segment
logger.info("Segment with ID " + segment.getId()
);
}
}
Listener segmen kustom ini kemudian direferensikan ketika membangun AWSXRayRecorder
.
contoh AWSXRayRecorderBuilder pernyataan
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new MySegmentListener()
);
Variabel-variabel lingkungan
Anda dapat menggunakan variabel lingkungan untuk mengkonfigurasi X-Ray SDK untuk Java. SDKMendukung variabel-variabel berikut.
AWS_XRAY_CONTEXT_MISSING
— SetelRUNTIME_ERROR
untuk melempar pengecualian saat kode instrumentasi Anda mencoba merekam data saat tidak ada segmen yang terbuka.Nilai Valid
-
RUNTIME_ERROR
— Lempar pengecualian runtime. -
LOG_ERROR
— Log kesalahan dan lanjutkan (default). -
IGNORE_ERROR
— Abaikan kesalahan dan lanjutkan.
Kesalahan yang berkaitan dengan segmen atau subsegmen yang hilang dapat terjadi ketika Anda mencoba untuk menggunakan klien yang diinstrumentasi dalam kode perusahaan rintisan yang berjalan ketika tidak ada permintaan terbuka, atau dalam kode yang memunculkan thread baru.
-
AWS_XRAY_DAEMON_ADDRESS
– Mengatur host dan port pendengar daemon X-Ray. Secara default, SDK penggunaan127.0.0.1:2000
untuk kedua trace data (UDP) dan sampling (TCP). Gunakan variabel ini jika Anda telah mengonfigurasi daemon untuk mendengarkan di port berbeda atau jika berjalan pada host yang berbeda.format
-
Port yang sama –
address
:port
-
Port yang berbeda –
tcp:
address
:port
udp:address
:port
-
-
AWS_LOG_GROUP
— Tetapkan nama grup log ke grup log yang terkait dengan aplikasi Anda. Jika grup log Anda menggunakan AWS akun dan wilayah yang sama dengan aplikasi Anda, X-Ray akan secara otomatis mencari data segmen aplikasi Anda menggunakan grup log yang ditentukan ini. Untuk informasi selengkapnya tentang grup log, lihat Bekerja dengan grup log dan aliran. -
AWS_XRAY_TRACING_NAME
— Tetapkan nama layanan yang SDK digunakan untuk segmen. Menimpa nama layanan yang Anda tetapkan pada strategi penamaan segmen filter servlet.
Variabel lingkungan mengesampingkan Properti sistem yang setara dan nilai yang ditetapkan dalam kode.
Properti sistem
Anda dapat menggunakan properti sistem sebagai alternatif JVM -spesifik untuk variabel lingkungan. SDKMendukung properti berikut:
-
com.amazonaws.xray.strategy.tracingName
– Setara denganAWS_XRAY_TRACING_NAME
. -
com.amazonaws.xray.emitters.daemonAddress
– Setara denganAWS_XRAY_DAEMON_ADDRESS
. -
com.amazonaws.xray.strategy.contextMissingStrategy
– Setara denganAWS_XRAY_CONTEXT_MISSING
.
Jika kedua properti sistem dan variabel lingkungan setara ditetapkan, nilai variabel lingkungan digunakan. Salah satu metode menimpa nilai yang diatur dalam kode.