Migrando para Java OpenTelemetry

Para habilitar o agente Java do X-Ray, os argumentos JVM da sua aplicação precisavam ser modificados.

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

Para usar agentes Java OpenTelemetry baseados.

Para instrumentar seu código com o SDK do X-Ray para Java, primeiro era necessário configurar a classe AWSXRay com plug-ins de serviço e regras de amostragem locais. Depois, um gravador fornecido era usado.

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

As dependências a seguir são obrigatórias.

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

Configure o OpenTelemetry SDK instanciando um objeto TracerProvider e registrando globalmente um objeto. OpenTelemetrySdk Configure estes componentes:

Para obter informações sobre como usar o SDK do X-Ray com o Spring Framework para instrumentar sua aplicação, consulte AOP com Spring e o SDK do X-Ray para Java. Para habilitar o AOP no Spring, conclua as etapas a seguir.

OpenTelemetry fornece bibliotecas de instrumentação para coletar rastreamentos para solicitações recebidas de aplicativos Spring Boot. Para habilitar a instrumentação do Spring Boot com configuração mínima, inclua a dependência a seguir.

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

Para obter mais informações sobre como habilitar e configurar a instrumentação do Spring Boot para sua OpenTelemetry configuração, consulte OpenTelemetry Introdução.

O método padrão recomendado para instrumentar aplicativos Spring Boot é usar o agente OpenTelemetry Java com instrumentação de bytecode, que também fornece mais out-of-the-box instrumentações e configurações quando comparado ao uso direto do SDK. Para começar, consulte Solução de instrumentação automática de código zero.

O X-Ray SDK for Java pode instrumentar automaticamente AWS todos os clientes do SDK v2 quando você adiciona aws-xray-recorder-sdk-aws-sdk-v2-instrumentor o submódulo à sua compilação.

Para instrumentar chamadas posteriores de clientes individuais para AWS serviços com o AWS SDK for Java 2.2 e versões posteriores, aws-xray-recorder-sdk-aws-sdk-v2-instrumentor o módulo da sua configuração de compilação foi excluído e aws-xray-recorder-sdk-aws-sdk-v2 o módulo foi incluído. Clientes individuais foram instrumentados configurando-os com um 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();
//...

Para instrumentar automaticamente todos os clientes AWS do SDK, adicione o opentelemetry-aws-sdk-2.2-autoconfigure submódulo.

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

Para instrumentar clientes AWS SDK individuais, adicione o opentelemetry-aws-sdk-2.2 submódulo.

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

Em seguida, registre um interceptor ao criar um cliente 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();

Para instrumentar as solicitações HTTP de saída com o X-Ray, era necessário o X-Ray SDK para Java, versão do Apache HttpClient .

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

Da mesma forma que o X-Ray Java SDK, OpenTelemetry fornece uma ApacheHttpClientTelemetry classe que tem um método construtor que permite a criação de uma instância de um HttpClientBuilder para fornecer extensões OpenTelemetry baseadas e propagação de contexto para o 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>

A seguir está um exemplo de código do opentelemetry-java-instrumentation. O cliente HTTP fornecido por newHttpClient () gerará rastreamentos para solicitações executadas.

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

Com o SDK do X-Ray, os métodos beginSegment e beginSubsegmentsão necessários para criar manualmente segmentos e subsegmentos do 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();
        }

Você pode usar extensões personalizadas para monitorar o desempenho de atividades internas que não são capturadas pelas bibliotecas de instrumentação. Somente extensões do tipo servidor são convertidas em segmentos do X-Ray. Todas as outras extensões são convertidas em subsegmentos do X-Ray.

Primeiro, você precisará criar um Rastreador para gerar extensões, que podem ser obtidas por meio do método openTelemetry.getTracer. Isso fornecerá uma instância do rastreador de TracerProvider que foi registrada globalmente no exemplo Soluções de instrumentação manual com o SDK. Você pode criar quantas instâncias de rastreador forem necessárias, mas é comum ter um rastreador para toda a aplicação.

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

Você pode usar o rastreador para criar extensões.

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

As extensões têm um tipo padrão 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();
}

Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry

No exemplo acima, o método setAttribute é usado para adicionar atributos a cada extensão. Por padrão, todos os atributos de extensão serão convertidos em metadados nos dados brutos do X-Ray. Para garantir que um atributo seja convertido em uma anotação, e não em metadados, o exemplo acima adiciona a chave desse atributo à lista do atributo aws.xray.annotations. Para obter mais informações, consulte Enable The Customized X-Ray Annotations e Anotações e metadados.

Com agentes Java OpenTelemetry baseados

Se estiver usando o agente Java para instrumentar automaticamente a aplicação, você precisará realizar a instrumentação manual na aplicação. Por exemplo, para instrumentar o código dentro da aplicação para seções que não são cobertas por nenhuma biblioteca de instrumentação automática.

Você precisa usar o artefato opentelemetry-api para realizar a instrumentação manual com o agente. A versão do artefato não pode ser mais recente que a versão do agente.

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

Ao usar o SDK do X-Ray, depois que o Lambda tiver o Rastreamento ativo habilitado, não há necessidade de configuração adicional para usar o SDK do X-Ray. O Lambda criará um segmento representando a invocação do manipulador do Lambda, e você poderá criar subsegmentos ou bibliotecas de instrumentos usando o SDK do X-Ray sem nenhuma configuração adicional.

Camadas Lambda de instrumentação automática — Você pode instrumentar automaticamente seu Lambda AWS com camadas Lambda vendidas usando as seguintes soluções:

Para usar a instrumentação manual com a camada de instrumentação automática, consulte Soluções de instrumentação manual com o SDK. Para reduzir as partidas a frio, considere usar instrumentação OpenTelemetry manual para gerar OpenTelemetry traços para sua função Lambda.