Migrasi ke OpenTelemetry Java

Untuk mengaktifkan agen Java X-Ray, argumen JVM aplikasi Anda harus dimodifikasi.

-javaagent:/path-to-disco/disco-java-agent.jar=pluginPath=/path-to-disco/disco-plugins

Untuk menggunakan agen Java OpenTelemetry berbasis.

Untuk menginstruksikan kode Anda dengan X-Ray SDK for Java, pertama, AWSXRay kelas harus dikonfigurasi dengan plug-in layanan dan aturan pengambilan sampel lokal, kemudian perekam yang disediakan digunakan.

static { AWS XRayRecorderBuilder builder = AWS XRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ECSPlugin()); AWS XRay.setGlobalRecorder(builder.build());
}

Dependensi berikut diperlukan.

<dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.opentelemetry</groupId>
                <artifactId>opentelemetry-bom</artifactId>
                <version>1.49.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>io.opentelemetry.instrumentation</groupId>
                <artifactId>opentelemetry-instrumentation-bom</artifactId>
                <version>2.15.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-sdk</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.semconv</groupId>
            <artifactId>opentelemetry-semconv</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-exporter-otlp</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-xray</artifactId>
            <version>1.46.0</version>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-xray-propagator</artifactId>
            <version>1.46.0-alpha</version>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-resources</artifactId>
            <version>1.46.0-alpha</version>
        </dependency>
    </dependencies>

Konfigurasikan OpenTelemetry SDK dengan membuat instance TracerProvider dan mendaftarkan objek secara global. OpenTelemetrySdk Konfigurasikan komponen-komponen ini:

Untuk informasi tentang cara menggunakan X-Ray SDK dengan framework pegas untuk instrumen aplikasi Anda, lihat AOP dengan Spring dan X-Ray SDK for Java. Untuk mengaktifkan AOP di Musim Semi, selesaikan langkah-langkah ini.

OpenTelemetry menyediakan pustaka instrumentasi untuk mengumpulkan jejak permintaan masuk untuk aplikasi Spring Boot. Untuk mengaktifkan instrumentasi Spring Boot dengan konfigurasi minimal, sertakan ketergantungan berikut.

<dependency>
           <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-spring-boot-starter</artifactId>
        </dependency>

Untuk informasi selengkapnya tentang cara mengaktifkan dan mengonfigurasi instrumentasi Spring Boot untuk OpenTelemetry penyiapan Anda, lihat OpenTelemetry Memulai.

Metode default yang direkomendasikan untuk menginstrumentasi aplikasi Spring Boot adalah dengan menggunakan agen OpenTelemetry Java dengan instrumentasi bytecode, yang juga menyediakan lebih banyak out-of-the-box instrumentasi dan konfigurasi jika dibandingkan dengan langsung menggunakan SDK. Untuk memulai, lihatSolusi instrumentasi otomatis kode nol.

X-Ray SDK for Java dapat secara otomatis AWS menginstruksikan semua klien SDK v2 saat Anda menambahkan sub-modul aws-xray-recorder-sdk-aws-sdk-v2-instrumentor dalam build Anda.

Untuk menginstrumentasikan panggilan klien hilir klien individual ke AWS layanan dengan AWS SDK for Java 2.2 dan yang lebih baru, aws-xray-recorder-sdk-aws-sdk-v2-instrumentor modul dari konfigurasi build Anda dikecualikan dan aws-xray-recorder-sdk-aws-sdk-v2 modul disertakan. Klien individu diinstrumentasi dengan mengonfigurasinya dengan a. TracingInterceptor

import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...

public class MyModel {
  private DynamoDbClient client = DynamoDbClient.builder()
    .region(Region.US_WEST_2)
    .overrideConfiguration(
      ClientOverrideConfiguration.builder()
        .addExecutionInterceptor(new TracingInterceptor())
        .build()
      )
    .build();
//...

Untuk menginstruksikan semua klien AWS SDK secara otomatis, tambahkan opentelemetry-aws-sdk-2.2-autoconfigure sub-modul.

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-aws-sdk-2.2-autoconfigure</artifactId>
            <version>2.15.0-alpha</version>
            <scope>runtime</scope>
        </dependency>

Untuk menginstrumentasikan klien AWS SDK individual, tambahkan opentelemetry-aws-sdk-2.2 sub-modul.

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-aws-sdk-2.2</artifactId>
            <version>2.15.0-alpha</version>
            <scope>compile</scope>
        </dependency>

Kemudian, daftarkan pencegat saat membuat Klien AWS SDK.

import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;

// ...

    AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
    private final S3Client S3_CLIENT = S3Client.builder()
      .overrideConfiguration(ClientOverrideConfiguration.builder()
        .addExecutionInterceptor(telemetry.newExecutionInterceptor())
        .build())
      .build();

Untuk instrumen permintaan HTTP keluar dengan X-Ray, X-Ray SDK untuk Apache HttpClient versi Java diperlukan.

import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
...
  public String randomName() throws IOException {
    CloseableHttpClient httpclient = HttpClientBuilder.create().build();

Demikian pula dengan X-Ray Java SDK, OpenTelemetry menyediakan ApacheHttpClientTelemetry kelas yang memiliki metode pembangun yang memungkinkan pembuatan instance dari sebuah HttpClientBuilder untuk menyediakan rentang OpenTelemetry berbasis dan propagasi konteks untuk Apache. HttpClient

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-apache-httpclient-5.2</artifactId>
            <version>2.15.0-alpha</version>
            <scope>compile</scope>
        </dependency>

Berikut ini adalah contoh kode dari opentelemetry-java-instrumentation. Klien HTTP yang disediakan oleh newHttpClient () akan menghasilkan jejak untuk permintaan yang dieksekusi.

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.apachehttpclient.v5_2.ApacheHttpClientTelemetry;
import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;

public class ApacheHttpClientConfiguration {

  private OpenTelemetry openTelemetry;

  public ApacheHttpClientConfiguration(OpenTelemetry openTelemetry) {
    this.openTelemetry = openTelemetry;
  }

  // creates a new http client builder for constructing http clients with open telemetry instrumentation
  public HttpClientBuilder createBuilder() {
    return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClientBuilder();
  }

  // creates a new http client with open telemetry instrumentation
  public HttpClient newHttpClient() {
    return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClient();
  }
}

Dengan X-Ray SDK, beginSubsegment metode beginSegment dan metode diperlukan untuk secara manual membuat segmen X-Ray dan sub-segmen.

  Segment segment = xrayRecorder.beginSegment("ManualSegment");
        segment.putAnnotation("annotationKey", "annotationValue");
        segment.putMetadata("metadataKey", "metadataValue");

        try {
            Subsegment subsegment = xrayRecorder.beginSubsegment("ManualSubsegment");
            subsegment.putAnnotation("key", "value");

            // Do something here

        } catch (Exception e) {
            subsegment.addException(e);
        } finally {
            xrayRecorder.endSegment();
        }

Anda dapat menggunakan rentang kustom untuk memantau kinerja aktivitas internal yang tidak ditangkap oleh pustaka instrumentasi. Perhatikan bahwa hanya server jenis rentang yang diubah menjadi segmen X-Ray, semua rentang lainnya diubah menjadi sub-segmen X-Ray.

Pertama, Anda perlu membuat Tracer untuk menghasilkan bentang, yang dapat Anda peroleh melalui metode iniopenTelemetry.getTracer. Ini akan memberikan instance Tracer dari TracerProvider yang terdaftar secara global dalam Solusi instrumentasi manual dengan SDK contoh. Anda dapat membuat instance Tracer sebanyak yang diperlukan, tetapi biasanya memiliki satu Tracer untuk seluruh aplikasi.

Tracer tracer = openTelemetry.getTracer("my-app");

Anda dapat menggunakan Tracer untuk membuat bentang.

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;

...

// SERVER span will become an X-Ray segment
Span span = tracer.spanBuilder("get-token")
  .setKind(SpanKind.SERVER)
  .setAttribute("key", "value")
  .startSpan();
try (Scope ignored = span.makeCurrent()) {

  span.setAttribute("metadataKey", "metadataValue");
  span.setAttribute("annotationKey", "annotationValue");
  
  // The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
  span.setAttribute(AttributeKey.stringArrayKey("aws.xray.annotations"), List.of("annotationKey"));

  // Do something here
}

span.end();

Rentang memiliki tipe internal default.

// Default span of type INTERNAL will become an X-Ray subsegment
Span span = tracer.spanBuilder("process-header")
  .startSpan();
try (Scope ignored = span.makeCurrent()) {
  doProcessHeader();
}

Menambahkan anotasi dan metadata ke jejak dengan SDK OpenTelemetry

Dalam contoh di atas, setAttribute metode ini digunakan untuk menambahkan atribut ke setiap rentang. Secara default, semua atribut rentang akan diubah menjadi metadata dalam data mentah X-Ray. Untuk memastikan bahwa atribut diubah menjadi anotasi dan bukan metadata, contoh di atas menambahkan kunci atribut tersebut ke daftar atribut. aws.xray.annotations Untuk informasi selengkapnya, lihat Mengaktifkan Anotasi dan Anotasi X-Ray yang Disesuaikan dan metadata.

Dengan agen Java OpenTelemetry berbasis

Jika Anda menggunakan agen Java untuk secara otomatis instrumen aplikasi Anda, Anda perlu melakukan instrumentasi manual dalam aplikasi Anda. Misalnya, ke kode instrumen dalam aplikasi untuk bagian yang tidak dicakup oleh pustaka instrumentasi otomatis apa pun.

Untuk melakukan instrumentasi manual dengan agen, Anda perlu menggunakan opentelemetry-api artefak. Versi artefak tidak bisa lebih baru dari versi agen.

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;

// ...
  
        Span parentSpan = Span.current();
        Tracer tracer = GlobalOpenTelemetry.getTracer("my-app");
        Span span = tracer.spanBuilder("my-span-name")
            .setParent(io.opentelemetry.context.Context.current().with(parentSpan))
            .startSpan();
        span.end();

Menggunakan X-Ray SDK, setelah Lambda Anda mengaktifkan Active Tracing, tidak ada konfigurasi tambahan yang diperlukan untuk menggunakan X-Ray SDK. Lambda akan membuat segmen yang mewakili pemanggilan penangan Lambda, dan Anda dapat membuat sub-segmen atau pustaka instrumen menggunakan X-Ray SDK tanpa konfigurasi tambahan.

Lapisan Lambda instrumentasi otomatis - Anda dapat secara otomatis menginstrumentasi Lambda Anda dengan lapisan Lambda yang dijual menggunakan solusi berikut AWS :

Untuk menggunakan instrumentasi manual bersama dengan lapisan instrumentasi otomatis, lihat. Solusi instrumentasi manual dengan SDK Untuk mengurangi start dingin, pertimbangkan untuk menggunakan instrumentasi OpenTelemetry manual untuk menghasilkan OpenTelemetry jejak untuk fungsi Lambda Anda.