Trazado y Otras Telemetría Con OpenTelemetry

Esta página explica cómo implementar el registro, el seguimiento y las métricas utilizando OpenTelemetry.

Habilitando OpenTelemetry

Para habilitar OpenTelemetry para una aplicación, consiste en los siguientes pasos:

  1. Agregue las dependencias de Lightbend Telemetry ("Cinnamon"):

    <dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-opentracing-zipkin</artifactId>
</dependency>
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-opentracing_${scala.version}</artifactId>
</dependency>
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-agent</artifactId>
</dependency>
     A partir de IPF 2024. 2. 0, se requiere una solución alternativa para evitar un conflicto entre las versiones de la biblioteca.
Por favor, añada lo siguiente al `<dependencyManagement>` bloque de su raíz `pom.xml` para utilizar OTel y OpenTracing
juntos:
    <dependency>
    <groupId>io.opentracing</groupId>
    <artifactId>opentracing-util</artifactId>
    <version>0. 33. 0</version>
</dependency>
<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-sender-urlconnection</artifactId>
    <version>2. 16. 3</version>
</dependency>
<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-reporter</artifactId>
    <version>2. 16. 3</version>
</dependency>
<dependency>
    <groupId>io.zipkin.zipkin2</groupId>
    <artifactId>zipkin</artifactId>
    <version>2. 23. 2</version>
</dependency>

  2. Habilite la Telemetría de Lightbend Java Agente, por ejemplo, en el CMD sección del Docker imagen:

exec java -javaagent:/${project.artifactId}/lib/com.lightbend.cinnamon-cinnamon-agent-${cinnamon.version}.jar
+
NOTE: This is already done as part of the Icon Project Archetype so this step is usually not required

  1. Habilite la métrica relevante o event exportadores según la documentación de OpenTelemetry de Lightbend para métricas, eventos, registros.

  2. Para habilitar el seguimiento, asegúrese de que el OpenTelemetry Collector esté configurado para recibir spans en formato OpenTracing, y siga el instructions in Reportero de Zipkin.

Si todo funcionó correctamente, entonces debería ver algunos rastros en su herramienta de rastreo preferida (por ejemplo,https://www.jaegertracing.io/[Jaeger], Zipkin, Grafana Tempo):

span example

Propagación de Contexto

También es posible configurar IPF para que simplemente propague los encabezados relevantes sin crear ningún rastreo adicional. información. Por defecto, Lightbend Telemetry admite el reenvío de los siguientes tipos de contexto:

Tipo Documentos para habilitar

W3C Trace Context (predeterminado para OpenTelemetry)

Haga clic aquí

B3 (por Zipkin)

Haga clic aquí

AWS X-Ray

Haga clic aquí

Limitaciones

El seguimiento y la telemetría en general son un enfoque sin código: simplemente habilitando el Cinnamon Java el agente habilita introspección a nivel de código para añadir los detalles de seguimiento relevantes.

Sin embargo, Lightbend Telemetry actualmente solo admite Kafka y HTTP. Si-en cualquier límite-los mensajes están siendo enviados. JMS (o cualquier otro protocolo que no sea Kafka or HTTP), el contexto de trazado se perderá, y se requiere alguna intervención para conecte las trazas.

Para conectar las trazas, siga el instructions in Inyectar y Extraer para extraer el SpanContext al enviar e inyectar al recibir mensajes. Un ejemplo utilizando un a custom CorrelationService podría ser:

import com.iconsolutions.ipf.core.shared.correlation. CorrelationService;
import lombok. AllArgsConstructor;

@AllArgsConstructor
public class OpenTracingAwareCorrelationService implements CorrelationService {

    private final CorrelationService delegate;

    @Override
    public CompletionStage<Correlation> save(Correlation correlation) {
        var map = new HashMap<String, String>();
        GlobalTracer.get().inject(ActiveSpan.getContext(), Format. Builtin. TEXT_MAP, new TextMapAdapter(map));
        correlation.getSupportingContext().mergedWith(SupportingContext.of(map));
        return delegate.save(correlation);
    }

    @Override
    public CompletionStage<Optional<Correlation>> findByCorrelationId(CorrelationId correlationId) {
        return delegate.findByCorrelationId(correlationId)
                .thenApply(maybeCorrelation -> {
                    maybeCorrelation.ifPresent(it -> GlobalTracer.get().extract(Format. Builtin. TEXT_MAP, new TextMapAdapter(it.getSupportingContext().getMetaData().getValues())));
                    return maybeCorrelation;
                });
    }
}

Este CorrelationService la implementación guardará el OpenTracing activo Span en el almacén de correlación donde posible, y extráigalo donde sea posible.

Tenga en cuenta que esto requerirá introducir una dependencia en OpenTracing, que es una biblioteca que está en desuso en favor de OpenTelemetry. Esta página se actualizará cuando Lightbend Telemetry se actualice para soportar el trazado nativo de OpenTelemetry.

Soporte de Lightbend Telemetry ("Cinnamon") para trazado

Lightbend Telemetry ("Cinnamon") no admite actualmente el estándar OpenTelemetry para trazas y solo implementa el legado de OpenTracing API. Sin embargo, el OpenTelemetry recolector y AWS X-Ray admiten el formato legado OpenTracing Zipkin. Por lo tanto, no debe necesitar hacer nada más para obtener trazas. trabajando en OpenTelemetry.

No se debería necesitar ninguna configuración aparte de simplemente añadir las bibliotecas en el paso 1, pero Haga clic aquí para ver qué la configuración está disponible para ajustar en la biblioteca.

Combinando OpenTelemetry y OpenTracing

Puede tener la necesidad de propagar el contexto de trazas entre OpenTelemetry y OpenTracing. Por ejemplo, si la siguiente combinación se aplica:

  • Está utilizando el OpenTelemetry Java Agente

  • Está iniciando un flujo desde un Spring @RestController,@KafkaListener,@JmsListener, o similar

  • Usted está recibiendo un contexto de traza en forma de encabezados de un sistema o corredor ascendente.

Por defecto, el rastro se interrumpirá entre el lado de Spring y el lado de IPF, porque Lightbend Telemetry (y por extension Akka y IPF) utiliza OpenTracing API, y no será consciente del contexto de traza OTel que fue poblado por Primavera. El contexto debe ser propagado manualmente de OTel a OpenTracing; siga estos pasos para configurar su aplicación para conectar el contexto de trazado entre OTel y OpenTracing:

  1. Agregue primero el agente de Telemetría de Lightbend y segundo el agente OTel:

    -javaagent:/path/to/cinnamon-agent-2. 20. 1.jar
-javaagent:/path/to/opentelemetry-javaagent.jar

  2. Deshabilite OTel Akka y Akka HTTP instrumentación con las propiedades del sistema (o variables de entorno, o archivo de configuración entradas):

    otel.instrumentation.akka-http.enabled=false
otel.instrumentation.akka.enabled=false

  3. Asegúrese de que los valores de otel.service.name y cinnamon.application son los mismos, de modo que las huellas parecen provenir desde el mismo IPF application(a menos que desee que sean diferentes)

    Valores predeterminados:

    • cinnamon.application: nombre completamente calificado de dónde JVM se inició en minúsculas, por ejemplo.com.mycorp.application

    • otel.service.name:`unknown_service:java`

  4. Al ir del consumidor de mensajes de Spring o REST controlador, inyecte el contexto OTel en un mapa y extráigalo en OpenTracing:

    @PostMapping(value = "/submit")
public CompletionStage<ResponseEntity<Void>> helloMapping(@RequestHeader Map<String, String> headers, @RequestBody String number) {
    //make an empty map to transport the context
    var otelContext = new HashMap<String, String>();
    //put the OTel Context into the map
    GlobalOpenTelemetry.get().getPropagators().getTextMapPropagator().inject(Context.current(), otelContext, (carrier, key, value) -> carrier.put(key, value));
    //put the map's contents into an OpenTracing SpanContext
    var openTracingContext = GlobalTracer.get().extract(Format. Builtin. TEXT_MAP, new TextMapAdapter(otelContext));
    //set the new OpenTracing SpanContext to be the current one
    GlobalExtendedTracer.get().local().activateContext(openTracingContext);

    //call IPF
    return MyDomain.initiation().handle(new InitiateMyFlowInput. Builder().build())
        .thenCompose(__ -> ResponseEntity.accepted().build);
}