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
    Esto ya está hecho como parte de la Icon El arquetipo del proyecto, por lo que este paso generalmente no es necesario.

  3. Habilite los exportadores de métricas o eventos relevantes según Lightbend Telemetry. OpenTelemetry docs para métricas, eventos, registros.

  4. Para habilitar el seguimiento, asegúrese de que el OpenTelemetry El colector está configurado para recibir OpenTracing-formatted spans, y siga las instrucciones en 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 trazado 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 agregar 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), se perderá el contexto de trazado, y se requiere alguna intervención para conecte las trazas.

Para conectar las trazas, siga las instrucciones en Inyectar y Extraer para extraer el SpanContext cuando se envía e inyecta 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 activo OpenTracing 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á obsoleta en favor de OpenTelemetry. Esta página se actualizará cuando Lightbend Telemetry se actualice para soportar nativo OpenTelemetry trazado.

Soporte de Lightbend Telemetry ("Cinnamon") para trazado

Lightbend Telemetry ("Cinnamon") no soporta actualmente el OpenTelemetry estándar para trazas y solo implementa el legado OpenTracing API. Sin embargo, el OpenTelemetry recolector y AWS X-Ray soportan el legado OpenTracing Formato de 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 agregar 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 un requisito para 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

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

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

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

    -javaagent:/path/to/cinnamon-agent-2.20.1.jar
-javaagent:/path/to/opentelemetry-javaagent.jar

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

    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 de la Spring consumidor de mensajes 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);
}