Todos los productos
Search
Centro de documentos

Managed Service for OpenTelemetry:Use Zipkin to report Java application data

Última actualización: Sep 05, 2026

Zipkin es un sistema de rastreo distribuido de código abierto desarrollado por Twitter para el seguimiento de datos en tiempo real. Este sistema agrega información de monitoreo en tiempo real recopilada de varios sistemas heterogéneos. Esta guía le muestra cómo instrumentar su aplicación Java con la biblioteca Brave y reportar datos de traza a ARMS Tracing Analysis mediante un endpoint compatible con Zipkin.

Elección del método de instrumentación

Seleccione el método que corresponda a su framework. Spring Sleuth requiere la menor cantidad de configuración y se recomienda para proyectos de Spring Boot.

Método

Recomendado para

Complejidad

Spring Sleuth

Microservices de Spring Cloud (recomendado)

Baja

Spring 4.0 MVC o Spring Boot

Proyectos modernos basados en anotaciones de Spring

Media

Spring 2.5 o 3.0 MVC

Proyectos heredados basados en XML de Spring

Media

Dubbo

Aplicaciones Dubbo RPC

Media

Instrumentación manual

Control total sobre spans y etiquetas

Alta

Flujo de datos

Su aplicación utiliza la biblioteca Brave para crear spans y reportarlos a ARMS a través de un endpoint compatible con Zipkin.

Use Zipkin to report data

Requisitos previos

Obtención de un endpoint de Zipkin

Para reportar datos de traza, necesita un endpoint compatible con Zipkin desde la consola de Tracing Analysis.

  1. Inicie sesión en la consola de Tracing Analysis.

  2. En el panel de navegación izquierdo, haga clic en Cluster Configurations. Luego, haga clic en la pestaña Access point information.

  3. En la barra de navegación superior, seleccione una región. En la sección Cluster Information, active Show Token.

  4. En la sección Client, haga clic en Zipkin.

Copie el endpoint de la columna Related Information.

Endpoint of Jaeger or Zipkin

Si su aplicación se ejecuta en un entorno de producción de Alibaba Cloud, utilice un punto de acceso VPC de Alibaba Cloud. De lo contrario, use un endpoint público.
Utilice el endpoint v2 a menos que tenga un motivo específico para usar v1.

Frameworks compatibles

Brave proporciona instrumentación para los siguientes frameworks de Java. Para consultar la lista completa, véase brave-instrumentation.

Apache HttpClient, Dubbo, gRPC, JAX-RS 2.X, Jersey Server, JMS, Kafka, MySQL, Netty, OkHttp, Servlet, Spark, Spring Boot, Spring MVC

Proyecto de demostración

Hay una demostración funcional disponible para cada método de instrumentación. Descargue el proyecto de demostración y siga las instrucciones del archivo README en el directorio correspondiente.

Método

Directorio de demostración

Instrumentación manual

manualDemo

Spring 2.5 o 3.0 MVC

`springMvcDemo\webmvc3

webmvc25`

Spring 4.0 MVC o Spring Boot

`springMvcDemo\webmvc4-boot

webmv4`

Dubbo

dubboDemo

Spring Sleuth

sleuthDemo

Instrumentación con Spring Sleuth

Spring Cloud Sleuth ofrece rastreo distribuido automático para aplicaciones Spring Boot con una configuración mínima. Se integra de forma nativa con Zipkin para el reporte de trazas.

Paso 1: Agregar dependencias

Agregue las siguientes dependencias a su archivo pom.xml:

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave</artifactId>
    <version>5.4.2</version>
</dependency>

<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-sender-okhttp3</artifactId>
    <version>2.7.9</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.0.1.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-sleuth-core</artifactId>
    <version>2.0.1.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-sleuth-zipkin</artifactId>
    <version>2.0.1.RELEASE</version>
</dependency>

Paso 2: Configurar application.yml

Establezca la URL base de Zipkin y la tasa de muestreo. Reemplace <endpoint_short> con el endpoint público que termina en api/v2/spans, obtenido de la pestaña Access point information en la consola de Tracing Analysis.

spring:
   application:
     # This ends up as the service name in zipkin
     name: sleuthDemo
   zipkin:
     # Uncomment to send to zipkin, replacing 192.168.99.100 with your zipkin IP address
     baseUrl: <endpoint_short>

   sleuth:
     sampler:
       probability: 1.0

   sample:
   zipkin:
     # When enabled=false, traces log to the console. Comment to send to zipkin
     enabled: true

Paso 3: Verificar la configuración

Envíe una solicitud HTTP para activar el reporte de trazas:

http://localhost:3380/traced

Después de enviar la solicitud, revise la consola de Tracing Analysis para comprobar los datos de traza entrantes. Para conocer rutas de solicitud adicionales, consulte los métodos bajo com.alibaba.apm.SampleController en el proyecto de demostración.

Instrumentación con Spring 4.0 MVC o Spring Boot

Configure el rastreo mediante anotaciones de Java para aplicaciones Spring 4.0 MVC o Spring Boot.

Para ver un ejemplo funcional, consulte el directorio springMvcDemo\webmvc4-boot|webmv4 en el proyecto de demostración .

Paso 1: Configurar beans de rastreo y filtro

Agregue la siguiente clase de configuración. Reemplace <endpoint> con el endpoint que obtuvo en los requisitos previos.

/** Configuration for how to send spans to Zipkin */
@Bean Sender sender() {
  return OkHttpSender.create("<endpoint>");
}

/** Configuration for how to buffer spans into messages for Zipkin */
@Bean AsyncReporter<Span> spanReporter() {
  return AsyncReporter.create(sender());
}

/** Controls aspects of tracing such as the name that shows up in the UI */
@Bean Tracing tracing(@Value("${spring.application.name}") String serviceName) {
  return Tracing.newBuilder()
      .localServiceName(serviceName)
      .propagationFactory(ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, "user-name"))
      .currentTraceContext(ThreadLocalCurrentTraceContext.newBuilder()
          .addScopeDecorator(MDCScopeDecorator.create()) // puts trace IDs into logs
          .build()
      )
      .spanReporter(spanReporter()).build();
}

/** decides how to name and tag spans. By default they are named the same as the http method. */
@Bean HttpTracing httpTracing(Tracing tracing) {
  return HttpTracing.create(tracing);
}

/** Creates client spans for http requests */
// We are using a BPP as the Frontend supplies a RestTemplate bean prior to this configuration
@Bean BeanPostProcessor connectionFactoryDecorator(final BeanFactory beanFactory) {
  return new BeanPostProcessor() {
    @Override public Object postProcessBeforeInitialization(Object bean, String beanName) {
      return bean;
    }

    @Override public Object postProcessAfterInitialization(Object bean, String beanName) {
      if (!(bean instanceof RestTemplate)) return bean;

      RestTemplate restTemplate = (RestTemplate) bean;
      List<ClientHttpRequestInterceptor> interceptors =
          new ArrayList<>(restTemplate.getInterceptors());
      interceptors.add(0, getTracingInterceptor());
      restTemplate.setInterceptors(interceptors);
      return bean;
    }

    // Lazy lookup so that the BPP doesn't end up needing to proxy anything.
    ClientHttpRequestInterceptor getTracingInterceptor() {
      return TracingClientHttpRequestInterceptor.create(beanFactory.getBean(HttpTracing.class));
    }
  };
}

/** Creates server spans for http requests */
@Bean Filter tracingFilter(HttpTracing httpTracing) {
  return TracingFilter.create(httpTracing);
}

@Autowired SpanCustomizingAsyncHandlerInterceptor webMvcTracingCustomizer;

/** Decorates server spans with application-defined web tags */
@Override public void addInterceptors(InterceptorRegistry registry) {
  registry.addInterceptor(webMvcTracingCustomizer);
}

Paso 2: Habilitar la autoconfiguración

Agregue la siguiente línea a src/main/resources/META-INF/spring.factories:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
brave.webmvc.TracingConfiguration

Instrumentación con Spring 2.5 o 3.0 MVC

Configure el rastreo mediante definiciones de beans en XML para aplicaciones Spring 2.5 o 3.0 MVC.

Para ver un ejemplo funcional, consulte el directorio springMvcDemo\webmvc3|webmvc25 en el proyecto de demostración .

Paso 1: Configurar el objeto de rastreo

Agregue las siguientes definiciones de beans a su archivo applicationContext.xml. Reemplace <endpoint> con el endpoint que obtuvo en los requisitos previos.

<bean class="zipkin2.reporter.beans.OkHttpSenderFactoryBean">
  <property name="endpoint" value="<endpoint>"/>
</bean>

<!-- allows us to read the service name from spring config -->
<context:property-placeholder/>

<bean class="brave.spring.beans.TracingFactoryBean">
  <property name="localServiceName" value="brave-webmvc3-example"/>
  <property name="spanReporter">
    <bean class="zipkin2.reporter.beans.AsyncReporterFactoryBean">
      <property name="encoder" value="JSON_V2"/>
      <property name="sender" ref="sender"/>
      <!-- wait up to half a second for any in-flight spans on close -->
      <property name="closeTimeout" value="500"/>
    </bean>
  </property>
  <property name="propagationFactory">
    <bean class="brave.propagation.ExtraFieldPropagation" factory-method="newFactory">
      <constructor-arg index="0">
        <util:constant static-field="brave.propagation.B3Propagation.FACTORY"/>
      </constructor-arg>
      <constructor-arg index="1">
        <list>
          <value>user-name</value>
        </list>
      </constructor-arg>
    </bean>
  </property>
  <property name="currentTraceContext">
    <bean class="brave.spring.beans.CurrentTraceContextFactoryBean">
      <property name="scopeDecorators">
        <bean class="brave.context.log4j12.MDCScopeDecorator" factory-method="create"/>
      </property>
    </bean>
  </property>
</bean>

<bean class="brave.spring.beans.HttpTracingFactoryBean">
  <property name="tracing" ref="tracing"/>
</bean>

Paso 2: Agregar interceptores

Registre el constructor de cliente HTTP de rastreo y el interceptor de controlador:

<bean class="brave.httpclient.TracingHttpClientBuilder"
      factory-method="create">
    <constructor-arg type="brave.http.HttpTracing" ref="httpTracing"/>
  </bean>

  <bean factory-bean="httpClientBuilder" factory-method="build"/>

  <bean class="org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping">
    <property name="interceptors">
      <list>
        <bean class="brave.spring.webmvc.SpanCustomizingHandlerInterceptor"/>
      </list>
    </property>
  </bean>

  <!-- Loads the controller -->
  <context:component-scan base-package="brave.webmvc"/>

Paso 3: Agregar un filtro de servlet

Agregue el filtro de rastreo a su archivo web.xml para interceptar todas las solicitudes entrantes:

<!-- Add the delegate to the standard tracing filter and map it to all paths -->
<filter>
  <filter-name>tracingFilter</filter-name>
  <filter-class>brave.spring.webmvc.DelegatingTracingFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>tracingFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Instrumentación con Dubbo

La biblioteca de instrumentación Brave Dubbo añade rastreo distribuido a las aplicaciones Dubbo RPC.

Para ver un ejemplo funcional, consulte el directorio dubboDemo en el proyecto de demostración .

Paso 1: Agregar dependencias

Agregue las siguientes dependencias a su archivo pom.xml:

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave</artifactId>
    <version>5.4.2</version>
</dependency>

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave-instrumentation-dubbo-rpc</artifactId>
    <version>5.4.2</version>
</dependency>

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave-spring-beans</artifactId>
    <version>5.4.2</version>
</dependency>

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave-context-slf4j</artifactId>
    <version>5.4.2</version>
</dependency>

<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-sender-okhttp3</artifactId>
    <version>2.7.9</version>
</dependency>

Paso 2: Configurar el objeto de rastreo

Agregue las siguientes definiciones de beans a su configuración XML de Spring. Reemplace <endpoint> con el endpoint que obtuvo en los requisitos previos.

<bean class="zipkin2.reporter.beans.OkHttpSenderFactoryBean">
    <property name="endpoint" value="<endpoint>"/>
</bean>

<bean class="brave.spring.beans.TracingFactoryBean">
    <property name="localServiceName" value="double-provider"/>
    <property name="spanReporter">
        <bean class="zipkin2.reporter.beans.AsyncReporterFactoryBean">
            <property name="sender" ref="sender"/>
            <!-- wait up to half a second for any in-flight spans on close -->
            <property name="closeTimeout" value="500"/>
        </bean>
    </property>
    <property name="currentTraceContext">
        <bean class="brave.spring.beans.CurrentTraceContextFactoryBean">
            <property name="scopeDecorators">
                <bean class="brave.context.slf4j.MDCScopeDecorator" factory-method="create"/>
            </property>
        </bean>
    </property>
</bean>

Paso 3: Agregar filtros de rastreo

Aplique el filtro de rastreo tanto a la configuración del proveedor como a la del consumidor:

// Server configuration
<dubbo:provider filter="tracing" />
// Client configuration
<dubbo:consumer filter="tracing" />

Instrumentación manual de una aplicación Java

La instrumentación manual le otorga un control detallado sobre qué operaciones se rastrean y qué metadatos se adjuntan a cada span. Utilice este método cuando la instrumentación automática no cubra su framework o cuando necesite una granularidad personalizada para los spans.

Para ver un ejemplo funcional, consulte el directorio manualDemo en el proyecto de demostración .

Paso 1: Agregar dependencias

Agregue las siguientes dependencias a su archivo pom.xml:

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave</artifactId>
    <version>5.4.2</version>
</dependency>
<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-sender-okhttp3</artifactId>
    <version>2.7.9</version>
</dependency>

Paso 2: Crear un tracer

Inicialice el tracer con su endpoint de Zipkin. Reemplace <endpoint> con el endpoint que obtuvo en los requisitos previos.

private static final String zipkinEndPoint = "<endpoint>";
...
// Create a sender to transmit span data
OkHttpSender sender = OkHttpSender.newBuilder().endpoint(zipkinEndPoint).build();

// Create an asynchronous reporter
Reporter<Span> reporter = AsyncReporter.builder(sender).build();

tracing = Tracing.newBuilder().localServiceName(localServiceName).spanReporter(reporter).build();

Paso 3: Crear spans

Cree un span raíz y anide spans secundarios para representar suboperaciones:

private void firstBiz() {
    // Create a root span
    tracing.tracer().startScopedSpan("parentSpan");
    Span span =  tracing.tracer().currentSpan();
    span.tag("key", "firstBiz");
    secondBiz();
    span.finish();
}

private void secondBiz() {
    tracing.tracer().startScopedSpanWithParent("childSpan", tracing.tracer().currentSpan().context());
    Span childSpan =  tracing.tracer().currentSpan();
    childSpan.tag("key", "secondBiz");
    childSpan.finish();
    System.out.println("end tracing,id:" + childSpan.context().traceIdString());
}

Paso 4: Agregar etiquetas personalizadas (opcional)

Adjunte metadatos a los spans para facilitar la resolución de problemas. Por ejemplo, registre un código de estado HTTP:

tracer.activeSpan().setTag("http.status_code", "500");

Paso 5: Propagar el contexto de traza entre servicios

En sistemas distribuidos, el contexto de traza (TraceId, ParentSpanId, SpanId, Sampled) debe viajar con cada solicitud RPC. Llame a Inject en el cliente para insertar el contexto en los encabezados de la solicitud, y llame a Extract en el servidor para leerlo nuevamente.

Inject and Extract flow

Lado del cliente -- inyección de contexto

// Start a new span representing a client request
oneWaySend = tracer.nextSpan().name(service + "/" + method).kind(CLIENT);
--snip--

// Add the trace context to the request, so it can be propagated in-band
tracing.propagation().injector(Request::addHeader)
                 .inject(oneWaySend.context(), request);

// Fire off the request asynchronously, totally dropping any response
request.execute();

// Start the client side and flush instead of finish
oneWaySend.start().flush();

Lado del servidor -- extracción de contexto

// Pull the context out of the incoming request
extractor = tracing.propagation().extractor(Request::getHeader);

// Convert that context to a span which you can name and add tags to
oneWayReceive = nextSpan(tracer, extractor.extract(request))
    .name("process-request")
    .kind(SERVER)
    ... add tags etc.

// Start the server side and flush instead of finish
oneWayReceive.start().flush();

// You should not modify this span anymore as it is complete. However,
// you can create children to represent follow-up work.
next = tracer.newSpan(oneWayReceive.context()).name("step2").start();

Preguntas frecuentes

P: No aparecen datos de traza después de ejecutar la demostración.

R: Esto suele indicar una configuración incorrecta del endpoint. Para diagnosticar el problema:

  1. Compruebe que el endpoint coincida con el que se muestra en la pestaña Access point information de la consola de Tracing Analysis.

  2. Asegúrese de haber seleccionado el tipo de cliente correcto (Zipkin, no Jaeger) al copiar el endpoint.

  3. Si utiliza un punto de acceso VPC, confirme que su aplicación se ejecute dentro de la misma VPC.

  4. Para depurar más a fondo, establezca un punto de interrupción en el método parseResponse de zipkin2.reporter.okhttp3.HttpCall e inspeccione la respuesta HTTP. Un error 403 indica que la configuración del nombre de usuario no es válida. Revise la configuración de su endpoint.