遷移至 OpenTelemetry Java

若要啟用 X-Ray Java 代理程式，需要修改應用程式的 JVM 引數。

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

使用 OpenTelemetry 型 Java 代理程式。

若要使用適用於 Java 的 X-Ray 開發套件來檢測程式碼，首先需要使用服務外掛程式和本機取樣規則來設定 AWSXRay類別，然後使用提供的記錄器。

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

需要下列相依性。

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

透過執行個體化 TracerProvider和全域註冊OpenTelemetrySdk物件來設定 OpenTelemetry SDK。設定這些元件：

如需有關如何使用 X-Ray 開發套件搭配彈簧架構來檢測應用程式的資訊，請參閱搭配 Spring 的 AOP 和適用於 Java 的 X-Ray 開發套件。若要在 Spring 中啟用 AOP，請完成以下步驟。

OpenTelemetry 提供檢測程式庫，可收集 Spring Boot 應用程式傳入請求的追蹤。若要以最少的組態啟用 Spring Boot 檢測，請包含下列相依性。

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

如需如何為 OpenTelemetry 設定啟用和設定 Spring Boot 檢測的詳細資訊，請參閱 OpenTelemetry 入門。

檢測 Spring Boot 應用程式的預設建議方法是使用 OpenTelemetry Java 代理程式搭配位元組碼檢測，與直接使用 SDK 相比，它還提供更多out-of-the-box檢測和組態。如需入門，請參閱 零程式碼自動檢測解決方案。

當您在建置中新增aws-xray-recorder-sdk-aws-sdk-v2-instrumentor子模組時，適用於 Java 的 X-Ray 開發套件可以自動檢測所有 AWS SDK v2 用戶端。

若要使用適用於 Java 的 AWS SDK 2.2 和更新版本來檢測個別用戶端對 AWS 服務的下游用戶端呼叫，已排除建置組態中的aws-xray-recorder-sdk-aws-sdk-v2-instrumentor 模組，並包含aws-xray-recorder-sdk-aws-sdk-v2模組。透過使用 設定個別用戶端來進行檢測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();
//...

若要自動檢測所有 AWS SDK 用戶端，請新增 opentelemetry-aws-sdk-2.2-autoconfigure子模組。

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

若要檢測個別 AWS SDK 用戶端，請新增 opentelemetry-aws-sdk-2.2子模組。

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

然後，在建立 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();

若要使用 X-Ray 檢測傳出的 HTTP 請求，需要適用於 Java 的 X-Ray 開發套件的 Apache HttpClient 版本。

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

與 X-Ray Java 開發套件類似，OpenTelemetry 提供的 ApacheHttpClientTelemetry類別具有建置器方法，允許建立 的執行個體HttpClientBuilder，為 Apache HttpClient 提供 OpenTelemetry 型跨度和內容傳播。

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

以下是 opentelemetry-java-instrumentation 的程式碼範例。newHttpClient() 提供的 HTTP 用戶端將為執行的請求產生追蹤。

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();
  }
}

使用 X-Ray SDK，需要 beginSegment和 beginSubsegment方法來手動建立 X-Ray 區段和子區段。

  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();
        }

您可以使用自訂範圍來監控檢測程式庫未擷取的內部活動效能。請注意，只有跨度類型伺服器會轉換為 X-Ray 區段，所有其他跨度則會轉換為 X-Ray 子區段。

首先，您需要建立追蹤器來產生跨度，您可以透過 openTelemetry.getTracer方法取得。這將提供來自 的 Tracer 執行個體TracerProvider，該執行個體已在 使用 SDK 的手動檢測解決方案範例中全域註冊。您可以視需要建立任意數量的 Tracer 執行個體，但整個應用程式通常會有一個 Tracer。

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

您可以使用 Tracer 來建立跨度。

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();

跨度的預設類型為 INTERNAL。

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

使用 OpenTelemetry SDK 將註釋和中繼資料新增至追蹤

在上述範例中， setAttribute方法用於將屬性新增至每個跨度。根據預設，所有跨度屬性都會轉換為 X-Ray 原始資料中的中繼資料。為了確保屬性轉換為註釋而非中繼資料，上述範例會將該屬性的索引鍵新增至aws.xray.annotations屬性清單。如需詳細資訊，請參閱啟用自訂 X-Ray 註釋和註釋和中繼資料。

使用 OpenTelemetry 型 Java 代理程式

如果您使用 Java 代理程式自動檢測應用程式，則需要在應用程式中執行手動檢測。例如，針對任何自動檢測程式庫未涵蓋的區段，在應用程式中檢測程式碼。

若要使用代理程式執行手動檢測，您需要使用opentelemetry-api 成品。成品版本不能比代理程式版本更新。

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();

使用 X-Ray 開發套件，在 Lambda 啟用主動追蹤之後，使用 X-Ray 開發套件不需要額外的組態。Lambda 將建立代表 Lambda 處理常式調用的區段，而且您可以使用 X-Ray SDK 建立子區段或儀器程式庫，而不需要任何額外的組態。

自動檢測 Lambda 圖層 – 您可以使用下列解決方案，自動檢測 Lambda 與已 AWS 佈建的 Lambda 圖層：

若要搭配自動檢測層使用手動檢測，請參閱 使用 SDK 的手動檢測解決方案。為了減少冷啟動，請考慮使用 OpenTelemetry 手動檢測為您的 Lambda 函數產生 OpenTelemetry 追蹤。