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.

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.

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 DEBUGINFO,WARN,,ERROR, danFATAL. FATALtingkat 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.

SLF4J Frontend

1. Tambahkan dependensi Maven berikut ke proyek Anda:

   <dependency>
       <groupId>com.amazonaws</groupId>
       <artifactId>aws-xray-recorder-sdk-slf4j</artifactId>
       <version>2.11.0</version>
   </dependency>

2. Sertakan metode withSegmentListener ketika membangun AWSXRayRecorder. Ini menambahkan SegmentListener kelas, yang secara otomatis menyuntikkan jejak baru IDs ke dalam. SLF4J MDC

   SegmentListener mengambil string opsional sebagai parameter untuk mengonfigurasi prefiks pernyataan log. Prefiks dapat dikonfigurasi dengan cara berikut:

   • Tidak ada – Menggunakan prefiks AWS-XRAY-TRACE-ID default.

   • Kosong - Menggunakan string kosong (misalnya "").

   • Kustom - Menggunakan prefiks kustom sebagaimana ditentukan dalam string.

   contoh Pernyataan AWSXRayRecorderBuilder

   AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
           .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));

Log4J2 front end

1. Tambahkan dependensi Maven berikut ke proyek Anda:

   <dependency>
       <groupId>com.amazonaws</groupId>
       <artifactId>aws-xray-recorder-sdk-log4j</artifactId>
       <version>2.11.0</version>
   </dependency>

2. Sertakan metode withSegmentListener ketika membangun AWSXRayRecorder. Ini akan menambahkan SegmentListener kelas, yang secara otomatis menyuntikkan jejak baru yang sepenuhnya memenuhi syarat IDs ke dalam. SLF4J MDC

   SegmentListener mengambil string opsional sebagai parameter untuk mengonfigurasi prefiks pernyataan log. Prefiks dapat dikonfigurasi dengan cara berikut:

   • Tidak ada – Menggunakan prefiks AWS-XRAY-TRACE-ID default.

   • Kosong - Menggunakan string kosong (misalnya "") dan menghapus prefiks.

   • Kustom - Menggunakan prefiks kustom sebagaimana ditentukan dalam string.

   contoh Pernyataan AWSXRayRecorderBuilder

   AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
           .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));

Logback backend

Untuk memasukkan ID pelacakan ke log acara Anda, Anda harus mengubah PatternLayout pencatat, yang membuat format setiap pernyataan pencatatan.

1. Temukan tempat patternLayout dikonfigurasi. Anda dapat melakukan ini secara terprogram, atau melalui file XML konfigurasi. Untuk mempelajari selengkapnya, lihat Konfigurasi Longback.

2. Sisipkan di %X{AWS-XRAY-TRACE-ID} mana saja patternLayout untuk menyisipkan ID jejak dalam pernyataan logging future. %X{}menunjukkan bahwa Anda mengambil nilai dengan kunci yang disediakan dari. MDC Untuk mempelajari lebih lanjut tentang PatternLayouts Logback, lihat PatternLayout.

Log4J2 backend

1. Temukan tempat patternLayout dikonfigurasi. Anda dapat melakukan ini secara terprogram, atau melalui file konfigurasi yang ditulis dalamXML,, JSONYAML, atau format properti.

   Untuk mempelajari selengkapnya tentang mengonfigurasi Log4J2 melalui file konfigurasi, lihat Konfigurasi.

   Untuk mempelajari selengkapnya tentang mengonfigurasi Log4J2 secara terprogram, lihat Konfigurasi Terprogram.

2. Sisipkan di %X{AWS-XRAY-TRACE-ID} mana saja PatternLayout untuk menyisipkan ID jejak dalam pernyataan logging future. %X{}menunjukkan bahwa Anda mengambil nilai dengan kunci yang disediakan dari. MDC Untuk mempelajari selengkapnya PatternLayouts di Log4J2, lihat Pattern Layout.

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 %mdan 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 beforeEndSubsegmentuntuk 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— Setel RUNTIME_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 penggunaan 127.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 dengan AWS_XRAY_TRACING_NAME.

• com.amazonaws.xray.emitters.daemonAddress – Setara dengan AWS_XRAY_DAEMON_ADDRESS.

• com.amazonaws.xray.strategy.contextMissingStrategy – Setara dengan AWS_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.