OpenTracing Tutorial - Lesson 4 | opentracing

Set Baggage in the Client

We'll start this lesson where we left the previous one. We are providing the Publisher and the RequestBuilderCarrier on the workspace, as there's no need to change anything on them during this lesson, but refer to the previous versions of the Hello client and Formatter when working on this lesson.

Let's add a new parameter to our Hello's main method, so that it accepts a greeting in addition to a name. This is how the main method would look like in the end:

public static void main(String[] args) {
    if (args.length != 2) {
        throw new IllegalArgumentException("Expecting two arguments, helloTo and greeting");
    }
    String helloTo = args[0];
    String greeting = args[1];
    Tracer tracer = Tracing.init("hello-world");
    new Hello(tracer).sayHello(helloTo, greeting);
}

Don't forget to change the signature of the method sayHello() to accept this new parameter:

private void sayHello(String helloTo, String greeting) {

And add this instruction to sayHello method after starting the span:

scope.span().setBaggageItem("greeting", greeting);

By doing this we read a second command line argument as a "greeting" and store it in the baggage under "greeting" key.

Read Baggage in Formatter

On the formatter side, we want to retrieve the baggage item and use it in our helloStr. To accomplish that, let's add the following code to the formatter's HTTP handler:

String greeting = scope.span().getBaggageItem("greeting");
if (greeting == null) {
    greeting = "Hello";
}
String helloStr = String.format("%s, %s!", greeting, helloTo);

Run it

As in Lesson 3, first start the formatter and publisher in separate terminals, then run the client with two arguments, e.g. Bryan Bonjour. The publisher should print Bonjour, Bryan!.

For each terminal window, run: cd opentracing-tutorial/java and then export JAEGER_ENDPOINT=http://host01:14268/api/traces

Formatter: ./run.sh lesson04.exercise.Formatter server Publisher: ./run.sh lesson04.exercise.Publisher server Client: ./run.sh lesson04.exercise.Hello Bryan Bonjour

Once the client has finished running, check the trace in the UI.

What's the Big Deal?

We may ask - so what, we could've done the same thing by passing the greeting as an HTTP request parameter. However, that is exactly the point of this exercise - we did not have to change any APIs on the path from the root span in Hello.java all the way to the server-side span in formatter, three levels down. If we had a much larger application with much deeper call tree, say the formatter was 10 levels down, the exact code changes we made here would have worked, despite 8 more services being in the path. If changing the API was the only way to pass the data, we would have needed to modify 8 more services to get the same effect.

Some of the possible applications of baggage include:

passing the tenancy in multi-tenant systems
passing identity of the top caller
passing fault injection instructions for chaos engineering
passing request-scoped dimensions for other monitoring data, like separating metrics for prod vs. test traffic

Now, a Warning... NOW a Warning?

Of course, while baggage is an extermely powerful mechanism, it is also dangerous. If we store a 1Mb value/string in baggage, every request in the call graph below that point will have to carry that 1Mb of data. So baggage must be used with caution. In fact, Jaeger client libraries implement centrally controlled baggage restrictions, so that only blessed services can put blessed keys in the baggage, with possible restrictions on the value length.

cd <directory>	Change directory
ls	List directory
echo 'contents' > <file>	Write contents to a file
cat <file>	Output contents of file

i	In Command Mode	Change into Insert Mode, you can now insert and edit text in the file
esc	In Insert Mode	Change into Command Mode, you can now execute commands
:wq	In Command Mode	Save and Exit

Welcome!

OpenTracing Tutorial - Lesson 4

Congratulations!

You've completed the scenario!

Scenario Rating

Steps