Migration zu Java OpenTelemetry

Um den X-Ray-Java-Agenten zu aktivieren, mussten die JVM-Argumente Ihrer Anwendung geändert werden.

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

Um OpenTelemetry basierte Java-Agenten zu verwenden.

Um Ihren Code mit dem X-Ray SDK for Java zu instrumentieren, musste die AWSXRay Klasse zunächst mit Service-Plug-ins und lokalen Sampling-Regeln konfiguriert werden. Anschließend wurde ein mitgelieferter Rekorder verwendet.

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

Die folgenden Abhängigkeiten sind erforderlich.

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

Konfigurieren Sie das OpenTelemetry SDK, indem Sie ein Objekt instanziieren TracerProvider und global registrieren. OpenTelemetrySdk Konfigurieren Sie diese Komponenten:

Informationen zur Verwendung des X-Ray-SDK mit dem Spring-Framework zur Instrumentierung Ihrer Anwendung finden Sie unter AOP mit Spring und dem X-Ray-SDK SDK for Java. Gehen Sie wie folgt vor, um AOP in Spring zu aktivieren.

OpenTelemetry bietet Instrumentierungsbibliotheken zum Sammeln von Traces für eingehende Anfragen für Spring Boot-Anwendungen. Um die Spring Boot-Instrumentierung mit minimaler Konfiguration zu aktivieren, schließen Sie die folgende Abhängigkeit ein.

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

Weitere Informationen zur Aktivierung und Konfiguration der Spring Boot-Instrumentation für Ihr OpenTelemetry Setup finden Sie unter OpenTelemetry Erste Schritte.

Die empfohlene Standardmethode für die Instrumentierung von Spring Boot-Anwendungen ist die Verwendung des OpenTelemetry Java-Agenten mit Bytecode-Instrumentierung, der im Vergleich zur direkten Verwendung des SDK auch mehr out-of-the-box Instrumentierungen und Konfigurationen bietet. Informationen zu den ersten Schritten finden Sie unter. Automatische Instrumentierungslösung ohne Code

Das X-Ray SDK for Java kann automatisch alle AWS SDK v2-Clients instrumentieren, wenn Sie das aws-xray-recorder-sdk-aws-sdk-v2-instrumentor Untermodul zu Ihrem Build hinzugefügt haben.

Um die Downstream-Client-Aufrufe einzelner Clients an AWS Dienste mit AWS SDK for Java 2.2 und höher zu instrumentieren, wurde das aws-xray-recorder-sdk-aws-sdk-v2-instrumentor Modul aus Ihrer Build-Konfiguration ausgeschlossen und das aws-xray-recorder-sdk-aws-sdk-v2 Modul wurde aufgenommen. Einzelne Clients wurden instrumentiert, indem sie mit einem TracingInterceptor konfiguriert wurden.

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

Um alle AWS SDK-Clients automatisch zu instrumentieren, fügen Sie das opentelemetry-aws-sdk-2.2-autoconfigure Untermodul hinzu.

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

Um einzelne AWS SDK-Clients zu instrumentieren, fügen Sie das opentelemetry-aws-sdk-2.2 Untermodul hinzu.

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

Registrieren Sie dann einen Interceptor, wenn Sie einen AWS SDK-Client erstellen.

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

Um ausgehende HTTP-Anfragen mit X-Ray zu instrumentieren, HttpClient war das X-Ray SDK für Javas Version des Apache erforderlich.

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

Ähnlich wie das X-Ray Java SDK OpenTelemetry stellt es eine ApacheHttpClientTelemetry Klasse bereit, die über eine Builder-Methode verfügt, die die Erstellung einer Instanz ermöglicht, HttpClientBuilder um OpenTelemetry basierte Spans und Kontextpropagierung für Apache HttpClient bereitzustellen.

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

Im Folgenden finden Sie ein Codebeispiel aus dem opentelemetry-java-instrumentation. Der von newHttpClient () bereitgestellte HTTP-Client generiert Traces für ausgeführte Anfragen.

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

Mit dem X-Ray-SDK sind die beginSubsegment Methoden beginSegment und erforderlich, um X-Ray-Segmente und -Untersegmente manuell zu erstellen.

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

Sie können benutzerdefinierte Zeitspannen verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Span-Kind-Server in X-Ray-Segmente konvertiert werden, alle anderen Spans werden in X-Ray-Untersegmente umgewandelt.

Zunächst müssen Sie einen Tracer erstellen, um Spans zu generieren, die Sie mit dieser Methode abrufen können. openTelemetry.getTracer Dadurch wird eine Tracer-Instanz aus dem bereitgestelltTracerProvider, der im Beispiel global registriert wurde. Lösungen für die manuelle Instrumentierung mit dem SDK Sie können so viele Tracer-Instanzen wie nötig erstellen, aber es ist üblich, einen Tracer für eine gesamte Anwendung zu haben.

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

Sie können den Tracer verwenden, um Spans zu erstellen.

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

Spans haben den Standardtyp 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();
}

Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry

Im obigen Beispiel wird die setAttribute Methode verwendet, um jedem Bereich Attribute hinzuzufügen. Standardmäßig werden alle Span-Attribute in Metadaten in X-Rohdaten umgewandelt. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, fügt das obige Beispiel den Schlüssel dieses Attributs zur Liste des aws.xray.annotations Attributs hinzu. Weitere Informationen finden Sie unter Aktivieren der benutzerdefinierten X-Ray-Anmerkungen und Anmerkungen und Metadaten.

Mit OpenTelemetry basierten Java-Agenten

Wenn Sie den Java-Agenten zur automatischen Instrumentierung Ihrer Anwendung verwenden, müssen Sie in Ihrer Anwendung eine manuelle Instrumentierung durchführen. Zum Beispiel, um Code innerhalb der Anwendung für Abschnitte zu instrumentieren, die von keiner Bibliothek für automatische Instrumentierung abgedeckt werden.

Um eine manuelle Instrumentierung mit dem Agenten durchzuführen, müssen Sie das opentelemetry-api Artefakt verwenden. Die Artefaktversion darf nicht neuer als die Agentenversion sein.

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

Wenn Sie das X-Ray-SDK verwenden, ist nach der Aktivierung von Active Tracing auf Ihrem Lambda keine zusätzliche Konfiguration erforderlich, um das X-Ray-SDK zu verwenden. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie können Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellen.

Lambda-Schichten mit automatischer Instrumentierung — Mithilfe der folgenden Lösungen können Sie Ihr Lambda automatisch mit AWS Lambda-Schichten von Drittanbietern instrumentieren:

Informationen zur Verwendung der manuellen Instrumentierung zusammen mit der Ebene für automatische Instrumentierung finden Sie unterLösungen für die manuelle Instrumentierung mit dem SDK. Um weniger Kaltstarts zu erzielen, sollten Sie erwägen, OpenTelemetry manuelle Instrumente zu verwenden, um OpenTelemetry Traces für Ihre Lambda-Funktion zu generieren.