To have a better overview in the search pane of a tracer, you can customize the top-level span name using configuration.

Example:

tracing.components.web-server.spans.0.name="HTTP Request"
tracing.components.web-server.spans.0.new-name: "HTTP %1$s %2$s"

This is supported ONLY for the span named "HTTP Request" on component "web-server".

Parameters provided:

1. Method - HTTP method
2. Path - path of the request (such as '/greet')
3. Query - query of the request (may be null)

Update the pom.xml file and add the following Zipkin dependency to the <dependencies> section (not <dependencyManagement>). This will enable Helidon to use Zipkin at the default host and port, localhost:9411.

<dependency>
  <groupId>io.helidon.tracing</groupId>
  <artifactId>helidon-tracing-zipkin</artifactId>
</dependency>

All spans sent by Helidon to Zipkin need to be associated with a service. Specify the service name below.

tracing.service=helidon-mp-1

mvn package -DskipTests=true
java -jar target/helidon-quickstart-mp.jar

curl http://localhost:8080/greet

{
  "message": "Hello World!"
}

Because tracing is now enabled, the previous /greet endpoint invocation resulted in a new trace being created. Let’s get the trace data that was generated using the Zipkin API. First, get the service information.

curl http://localhost:9411/api/v2/services

["helidon-mp-1"] 

• This is the tracing service name specified in META-INF/microprofile-config.properties.

Each span used by a service has a name, which is unique within a trace. If you invoke the /greet endpoint multiple times, you will still get the same set of names.

curl -X GET "http://localhost:9411/api/v2/spans?serviceName=helidon-mp-1" -H "accept: application/json" 

• Get the span names for the helidon-mp-1 service.

[ 
  "content-read",
  "content-write",
  "get:io.helidon.examples.quickstart.mp.greetresource.getdefaultmessage",
  "security",
  "security:atn",
  "security:atz",
  "security:response"
]

• These are the span names. If you invoke the /greet endpoint again, then invoke the /spans endpoint, you will get the same response.

Next, get the contents of the trace as shown below. Notice that each span has a parentId field, except the get:io.helidon.examples.quickstart.mp.greetresource.getdefaultmessage span, which is the root.

curl -X GET "http://localhost:9411/api/v2/traces?serviceName=helidon-mp-1&limit=1" -H "accept: application/json" 

• Get the newest trace only, using the limit=1 query param. There are other query params that let you restrict results to a specific time window.

[
  [ 
    {
      "traceId": "2e0af8866efdef35",
      "parentId": "2e0af8866efdef35",
      "id": "b5d61690f230fde4",
      "kind": "SERVER",
      "name": "content-read",
      "timestamp": 1568077339998659,
      "duration": 41,
      "localEndpoint": {
        "serviceName": "helidon-mp-1",
        "ipv4": "192.168.1.115"
      },
      "tags": {
        "requested.type": "java.io.InputStream"
      }
    }
  ]
]

• The request will return seven spans, one for each name, along with an unnamed JSON node, which has the status.

The tracing output data is verbose and can be difficult to interpret using the REST API, especially since it represents a structure of spans. Zipkin provides a web-based UI at http://localhost:9411/zipkin, where you can see a visual representation of the same data and the relationship between spans within a trace. If you see a Lens UI button at the top center then click on it and it will take you to the specific UI used by this guide.

Click on the UI refresh button (the search icon) as shown in the image below. Notice that you can change the look-back time to restrict the trace list.

The image below shows the trace summary, including start time and duration of each trace. There are two traces, each one generated in response to a curl http://localhost:8080/greet invocation. The oldest trace will have a much longer duration since there is one-time initialization that occurs.

Click on a trace and you will see the trace detail page where the spans are listed. You can clearly see the root span and the relationship among all the spans in the trace, along with timing information.

You can examine span details by clicking on the span row. Refer to the image below, which shows the security span details, including timing information. You can see times for each space relative to the root span. These rows are annotated with Server Start and Server Finish, as shown in the third column.

So far in this tutorial you have used tracing with JAX-RS without needing to annotate. You can enable tracing on other CDI beans, either at the class level or at the method level, as shown by the following examples.

To trace at the method level, you just annotate a method with @Traced.

import org.eclipse.microprofile.opentracing.Traced; 

@Traced  
String getMessage() {
    return message.get();
}

• Import the Traced annotation.
• Enable tracing for getMessage.

curl http://localhost:8080/greet
curl -X GET "http://localhost:9411/api/v2/spans?serviceName=helidon-mp-1" -H "accept: application/json"

[
  "content-read",
  "content-write",
  "dosomework",
  "get:io.helidon.examples.quickstart.mp.greetresource.getdefaultmessage",
  "io.helidon.examples.quickstart.mp.greetingprovider.getmessage", 
  "security",
  "security:atn",
  "security:atz",
  "security:response"
]

• There is a new span name for the getmessage method, since your code called that method during the invocation of /greet.

Click the back button on your browser, then click on the UI refresh button to see the new trace. Select the newest trace in the list to see the trace detail page like the one below. Notice the new span named io.helidon.examples.quickstart.mp.greetingprovider.getmessage.

To trace at the class level, annotate the class with @Traced. This will enable tracing for all class methods, except for the constructor and private methods.

• Update the GreetingProvider class

• Add @Traced to the GreetingProvider class

• Remove @Traced from the getMessage method

@Traced 
@ApplicationScoped
public class GreetingProvider {

    String getMessage() { 
        return message.get();
    }
}

• This will enable tracing for all class methods, except for the constructor and methods that are private.
• Remove @Traced for the getMessage method.

curl http://localhost:8080/greet
curl -X GET "http://localhost:9411/api/v2/spans?serviceName=helidon-mp-1" -H "accept: application/json"

[
  "io.helidon.examples.quickstart.mp.greetingprovider.getmessage" 
]

• The service has the same set of span names as above, since getmessage was the only method called in this bean.

Next, invoke HTTP PUT to change the greeting, which will cause setMessage to be called.

curl -i -X PUT -H "Content-Type: application/json" -d '{"greeting": "Hi"}'  http://localhost:8080/greet/greeting 
curl -X GET "http://localhost:9411/api/v2/spans?serviceName=helidon-mp-1" -H "accept: application/json"

• Invoke the endpoint to change the greeting.

[
  "content-read",
  "content-write",
  "get:io.helidon.examples.quickstart.mp.greetresource.getdefaultmessage",
  "io.helidon.examples.quickstart.mp.greetingprovider.getmessage",
  "io.helidon.examples.quickstart.mp.greetingprovider.setmessage", 
  "put:io.helidon.examples.quickstart.mp.greetresource.updategreeting", 
  "security",
  "security:atn",
  "security:atz",
  "security:response"
]

• The GreetingProvider.setmessage method was traced since you enabled class level tracing.
• The JAX-RS method GreetResource.updategreeting was traced automatically by Helidon.

You can refresh the UI view and drill down the trace to see the new spans.

@ApplicationScoped
public class GreetingProvider {
    private final AtomicReference<String> message = new AtomicReference<>();

    @Inject
    public GreetingProvider(@ConfigProperty(name = "app.greeting") String message) {
        this.message.set(message);
    }

    @Traced 
    String getMessage() {
        return getMessage2();
    }

    @Traced  
    String getMessage2() {
        return message.get();
    }

    void setMessage(String message) {
        this.message.set(message);
    }
}

• The getMessage method will be traced since it is externally invoked by GreetResource.
• The getMessage2 method will not be traced, even with the @Traced annotation, since it is called internally by getMessage.

curl http://localhost:8080/greet
curl -X GET "http://localhost:9411/api/v2/spans?serviceName=helidon-mp-1" -H "accept: application/json"

[
  "io.helidon.examples.quickstart.mp.greetingprovider.getmessage" 
]

• The getMessage method is traced, but getMessage2 is not.

Once you have validated that the second service is running correctly, you need to modify the original application to call it.

package io.helidon.examples.quickstart.mp;

import java.util.Collections;
import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.json.Json;
import jakarta.json.JsonBuilderFactory;
import jakarta.json.JsonObject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.client.WebTarget;
import jakarta.ws.rs.core.MediaType;
import org.glassfish.jersey.server.Uri;

@Path("/greet")
@RequestScoped
public class GreetResource {

  @Uri("http://localhost:8081/greet")
  private WebTarget target; 

  private static final JsonBuilderFactory JSON = Json.createBuilderFactory(Collections.emptyMap());
  private final GreetingProvider greetingProvider;

  @Inject
  public GreetResource(GreetingProvider greetingConfig) {
    this.greetingProvider = greetingConfig;
  }

  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public JsonObject getDefaultMessage() {
    return createResponse("World");
  }

  @GET
  @Path("/outbound") 
  public JsonObject outbound() {
    return target.request().accept(MediaType.APPLICATION_JSON_TYPE).get(JsonObject.class);
  }

  private JsonObject createResponse(String who) {
    String msg = String.format("%s %s!", greetingProvider.getMessage(), who);

    return JSON.createObjectBuilder().add("message", msg).build();
  }
}

• This is the WebTarget needed to send a request to the second service at port 8081.
• This is the new endpoint that will call the second service.

curl -i http://localhost:8080/greet/outbound 

• The request went to the service on 8080, which then invoked the service at 8081 to get the greeting.

{
  "message": "Hello From MP-2 World!" 
}

• Notice the greeting came from the second service.

Refresh the Zipkin UI trace listing page and notice that there is a trace across two services.

Click on the trace with two services to see the detail view.

In the image above, you can see that the trace includes spans from two services. You will notice there is a gap before the sixth span, which is a get operation. This is a one-time client initialization delay. Run the /outbound curl command again and look at the new trace to see that the delay no longer exists.

You can now stop your second service, it is no longer used in this guide.