Join remote spans to existing transaction

When to use: a request made from a transaction causes a new transaction in a remote application where linking it as a child span into the first transaction is desired.

How: In this case, before calling the remote service, the caller should create a child span in the current span by calling first eu.plumbr.api.Span.createChildSpan() and then serializing it using eu.plumbr.api.SpanSerializer. This serialized span can then be included in the request to the other application (which should be also monitored by the Plumbr agent) and deserialized there with eu.plumbr.api.SpanSerializer and should then be started and finished manually using calls to eu.plumbr.api.Span.start() and eu.plumbr.api.Span.finish() respectively. After the call to the remote span finishes, the calling side must acknowledge that by calling eu.plumbr.api.Span.finishChildSpan(childSpan). See full examples below.

Listing 1: Managing a child span in the parent process:

Span childSpan = Plumbr.getCurrentSpan().createChildSpan();
String serializedChildSpan = SpanSerializer.toBase64(childSpan);

// Transfer serializedChildSpan to another machine.
// See Listing 2 about what to do there.
try {
    try {
        // perform remote call
    } finally {
        Plumbr.getCurrentSpan().finishChildSpan(childSpan);
    }
} catch (Exception e) {
	// If this failed remote call should fail the transaction:
	Plumbr.getCurrentSpan().fail(e)
}

Listing 2: Working with a child span on remote JVM:

String serializedChildSpan = … // obtain a serialized child span
Span span = SpanSerializer.fromBase64(serializedChildSpan);
span.start()
try {
	…
} catch (Exception e) {
	span.fail(e);
} finally {
	span.finish()
}