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.

Untuk menggunakan plugin, hubungi withPlugin di AWSXRayRecorderBuilder Anda.

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.

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.

{
  "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.

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.

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) { }
}

...
  <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.

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

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

Fitur ini bekerja dengan aplikasi Java yang diinstrumentasi dengan AWS X-Ray SDK untuk Java, dan mendukung konfigurasi logging berikut:

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).

%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.

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.

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.

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.

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:

Jika kedua properti sistem dan variabel lingkungan setara ditetapkan, nilai variabel lingkungan digunakan. Salah satu metode menimpa nilai yang diatur dalam kode.