View a markdown version of this page

Perubahan dalam penerbitan metrik SDK dari versi 1 ke versi 2 - AWS SDK for Java 2.x
High-level perubahanPerubahan dependensiPerubahan APIBatasanSumber daya tambahan

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

Perubahan dalam penerbitan metrik SDK dari versi 1 ke versi 2

Topik ini merinci perubahan dalam penerbitan metrik SDK sisi klien dari versi 1.x (v1) ke versi 2.x (v2) dari. AWS SDK untuk Java

High-level perubahan

Arsitektur berubah

Di v1, koleksi metrik adalah JVM-wide pengaturan global yang Anda aktifkan dengan properti sistem. SDK secara otomatis menerbitkan semua metrik yang dikumpulkan ke. CloudWatch Hanya ada satu tujuan metrik.

Di v2, koleksi metrik menggunakan MetricPublisherantarmuka pluggable yang Anda lampirkan ke klien atau permintaan layanan individual. SDK menyediakan tiga implementasi:

  • CloudWatchMetricPublisher: Mengagregat dan mengunggah metrik secara berkala ke. CloudWatch Paling cocok untuk aplikasi yang berjalan lama.

  • EmfMetricLoggingPublisher: Menulis metrik sebagai entri log terstruktur dalam CloudWatch Embedded Metric Format (EMF). Paling cocok untuk fungsi Lambda dan lingkungan berumur pendek lainnya.

  • LoggingMetricPublisher: Mengeluarkan metrik ke konsol melalui logging SLF4J. Paling cocok untuk pengembangan lokal dan debugging.

Perubahan ruang lingkup

Di v1, mengaktifkan metrik menerbitkan data untuk semua klien AWS layanan di JVM. Di v2, Anda mengontrol metrik di tingkat klien layanan atau di tingkat permintaan individu.

Perubahan tipe metrik

v1 mengumpulkan tiga kategori metrik: Metrik AWS Permintaan, Metrik AWS Layanan, dan Metrik Mesin (memori heap, jumlah utas, deskriptor file terbuka).

v2 berfokus pada metrik permintaan dan respons SDK, seperti durasi panggilan API, durasi penyusunan, durasi penandatanganan, dan hitungan coba lagi. v2 tidak mengumpulkan metrik mesin seperti memori heap, jumlah utas, dan deskriptor file terbuka. Untuk terus mengumpulkan metrik JVM CloudWatch, Anda dapat menggunakan koleksi metrik CloudWatch Agen dengan JMX.

Perubahan dependensi

Tabel berikut menunjukkan ketergantungan Maven dan perubahan nama paket antara v1 dan v2.

Ubah v1 v2

Ketergantungan Maven

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.x1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-cloudwatchmetrics</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.x.x2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>cloudwatch-metric-publisher</artifactId>
    </dependency>
</dependencies>
Nama paket com.amazonaws.metrics software.amazon.awssdk.metrics

1 Versi terbaru. 2 Versi terbaru.

Artefak v2 tergantung pada kasus penggunaan, seperti yang ditunjukkan pada tabel berikut.

Kasus penggunaan v2 Artifactid Versi SDK minimum
Long-running aplikasi cloudwatch-metric-publisher 2.14.0
Fungsi Lambda emf-metric-logging-publisher 2.30.3
Pengembangan dan debugging Tidak diperlukan ketergantungan tambahan (LoggingMetricPublisherada di inti SDK) 2.14.0

Perubahan API

Mengaktifkan metrik

Tabel berikut membandingkan cara mengaktifkan metrik di v1 dan v2 untuk kasus penggunaan yang berbeda.

Kasus penggunaan v1 v2

Aktifkan metrik secara global

Tambahkan properti sistem JVM:

-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties
 Tidak didukung. Lampirkan a MetricPublisher ke setiap klien layanan.

Aktifkan metrik di Amazon EC2 tanpa file kredensional

 
-Dcom.amazonaws.sdk.enableDefaultMetrics
 Tidak berlaku. v2 menggunakan resolusi kredensialnya standar.

Aktifkan metrik untuk klien layanan

 Tidak didukung. Metrik bersifat global atau tidak aktif. 
MetricPublisher metricsPub =
    CloudWatchMetricPublisher.create();

DynamoDbClient ddb = DynamoDbClient.builder()
    .overrideConfiguration(c -> c
        .addMetricPublisher(metricsPub))
    .build();

// ... use the client ...

metricsPub.close();
ddb.close();

Aktifkan metrik untuk satu permintaan

 Tidak didukung. 
ddb.listTables(ListTablesRequest.builder()
    .overrideConfiguration(c -> c
        .addMetricPublisher(metricsPub))
    .build());

Mengkonfigurasi tujuan CloudWatch

Tabel berikut menunjukkan cara mengkonfigurasi CloudWatch tujuan di v1 dibandingkan dengan v2.

Kasus penggunaan v1 v2

Tetapkan CloudWatch wilayah

Atribut properti sistem:

-Dcom.amazonaws.sdk.enableDefaultMetrics=cloudwatchRegion=us-west-2
 
CloudWatchMetricPublisher.builder()
    .cloudWatchClient(
        CloudWatchAsyncClient.builder()
            .region(Region.US_WEST_2)
            .build())
    .build();

Atur frekuensi unggah

 Tidak dapat dikonfigurasi. Unggah kira-kira sekali per menit. 
CloudWatchMetricPublisher.builder()
    .uploadFrequency(Duration.ofMinutes(5))
    .build();

Setel CloudWatch namespace

 Diperbaiki keAWSSDK/Java.

Diatur secara default ke AwsSdk/JavaSdk2. Dapat dikonfigurasi melalui:

CloudWatchMetricPublisher.builder()
    .namespace("MyApp/SDK")
    .build();
catatan

Jika Anda memiliki CloudWatch dasbor atau alarm yang mereferensikan namespace AWSSDK/Java v1, setel untuk mempertahankan kontinuitas. .namespace("AWSSDK/Java")

Kecualikan metrik mesin

Atribut properti sistem:

-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics
 Tidak berlaku. v2 tidak mengumpulkan metrik mesin.

Metrik untuk fungsi Lambda

v1 tidak memiliki solusi Lambda-specific metrik. Di v2, gunakan EmfMetricLoggingPublisher yang menulis metrik sebagai entri log terstruktur dalam CloudWatch Embedded Metric Format (EMF):

// v2 - Lambda-optimized metrics publishing
EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder()
        .namespace("MyApp")
        .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME)
        .build();

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher))
        .build();
catatan

Di lingkungan Lambda, otomatis logGroupName terdeteksi dari variabel lingkungan. AWS_LAMBDA_LOG_GROUP_NAME Di lingkungan non-Lambda seperti Amazon ECS atau Amazon EC2, Anda harus menetapkan logGroupName secara eksplisit pada builder.

Metrik untuk pengembangan dan debugging

v1 tidak memiliki keluaran metrik berbasis konsol. Di v2, gunakanLoggingMetricPublisher:

// v2 - Console output for debugging
MetricPublisher loggingPublisher = LoggingMetricPublisher.create();

S3Client s3 = S3Client.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher))
        .build();

Manajemen siklus hidup

Di v1, pengumpulan metrik berjalan selama masa pakai JVM setelah properti sistem disetel. Di v2, Anda harus mengelola siklus hidup: MetricPublisher

// v2 - Close the publisher when no longer needed
MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
        .build();

// ... use the client ...

metricsPub.close(); // Flushes remaining metrics to CloudWatch
ddb.close();
penting

Panggil close MetricPublisher instance ketika tidak lagi diperlukan. Kegagalan untuk melakukannya dapat mengakibatkan kebocoran thread atau deskriptor file.

Izin yang diperlukan

Tabel berikut mencantumkan izin IAM yang diperlukan untuk setiap penerbit metrik.

Jenis izin v1 v2 (CloudWatchMetricPublisher) v2 (EmfMetricLoggingPublisher)
Izin IAM cloudwatch:PutMetricData cloudwatch:PutMetricData logs:PutLogEvents

Batasan

Klien AWS CRT-based S3 saat ini tidak mendukung pengumpulan metrik SDK di v2.

Sumber daya tambahan