1. ANNEXURE - 2
  2. Document Tracing Zipkin

1 Document Tracing Zipkin

This topic describes the procedure to install and run the document tracing zipkin.

1.1 Zipkin Installation

This topic describes the systematic instructions to download and install the zipkin.

1.1.1 Download the Zipkin

This topic provides systematic instructions to download the Zipkin.

The Zipkin works as an independent application and can be downloaded as a runnable jar from the official website of Zipkin https://zipkin.io/. The latest version of Zipkin needs a Java version above 8.

Note:

For the exact version to be installed, refer to Software Prerequisites section in Release Notes.
  1. Download the Zipkin from the direct link of jar is https://search.maven.org/remote_content?g=io.zipkin&a=zipkin-server&v=LATEST&c=exec.
  2. Execute the downloaded jar using the java –jar JAR_NAME command.

1.1.2 Configure the Zipkin

This topic provides systematic instructions to configure the Zipkin.

The configuration of Zipkin can be done with environment variables.

  1. Set the port of the Zipkin using the QUERY_PORT environment variable.
    The application starts on the port number assigned for QUERY_PORT environment variable or its default value of 9411.
  2. Access the web UI of Zipkin at http://localhost:PORT.

1.2 Troubleshoot Zipkin

This topic describes the systematic instructions to troubleshoot using Zipkin Traces.

  1. Launch the Zipkin URL.

    Note:

    The basic layout of Zipkin is shown below.
  2. Use Search to find the traces of required API calls and services.

    Note:

    The search options given in the user interface are self-explanatory, and there is another UI option (Try Lens UI). It is given a different user interface with the same functionality.

    Some error API calls are made to showcase how to track errors. The blue listing shows the successful API hits, and the red listing indicates the errors. Each block indicates a single trace in the listing. The below figure shows the list of traces.

  3. Open an individual trace.
    It describes the time taken for each block. As the two custom spans are created inside two service calls, user can find a total of four blocks.
    The time taken for an individual block is shown below.

    Figure 1-3 Individual Trace


    Description of Figure 1-3 follows
    Description of "Figure 1-3 Individual Trace"

  4. Click an individual block to display the details.

    Figure 1-4 Details of Individual Block


    Description of Figure 1-4 follows
    Description of "Figure 1-4 Details of Individual Block"

    The user can also view the logging events in the Zipkin UI as small circular blocks. An example of an error log is shown below.

    Figure 1-5 Sample Error Log


    Description of Figure 1-5 follows
    Description of "Figure 1-5 Sample Error Log"

  5. Click the error to get clear details and place of the error.

    Figure 1-6 Details of Error


    Description of Figure 1-6 follows
    Description of "Figure 1-6 Details of Error"

    If the Lens UI is used in Zipkin, the above figures are not applicable but are relatable to the Lens UI as well. Traces of the application can be found using TraceId. The TraceId can be found in the debug logs of the deployment when spring-cloud-sleuth is included in the dependencies (included in spring-cloud-starter-Zipkin dependency).

  6. Click Dependencies to get the dependency graph information between micro-services.

    Figure 1-7 Sample Dependency Graph


    Description of Figure 1-7 follows
    Description of "Figure 1-7 Sample Dependency Graph"