Package brave.rpc

Class RpcClientHandler

java.lang.Object

brave.rpc.RpcClientHandler

public final class RpcClientHandler
extends Object

This standardizes a way to instrument RPC clients, particularly in a way that encourages use of portable customizations via RpcRequestParser and RpcResponseParser.

Synchronous interception is the most straight forward instrumentation.

You generally need to:

1. Start the span and add trace headers to the request
2. Put the span in scope so things like log integration works
3. Invoke the request
4. If there was a Throwable, add it to the span
5. Complete the span

 RpcClientRequestWrapper requestWrapper = new RpcClientRequestWrapper(request);
 Span span = handler.handleSend(requestWrapper); // 1.
 ClientResponse response = null;
 Throwable error = null;
 try (Scope ws = currentTraceContext.newScope(span.context())) { // 2.
   return response = invoke(request); // 3.
 } catch (Throwable e) {
   error = e; // 4.
   throw e;
 } finally {
   RpcClientResponseWrapper responseWrapper =
     new RpcClientResponseWrapper(requestWrapper, response, error);
   handler.handleReceive(responseWrapper, span); // 5.
 }
 

Since:

5.12

Method Summary

Modifier and Type	Method	Description
static RpcClientHandler	create(RpcTracing rpcTracing)
void	handleReceive(RpcClientResponse response, Span span)	Finishes the client span after assigning it tags according to the response or error.
Span	handleSend(RpcClientRequest request)	Starts the client span after assigning it a name and tags.
Span	handleSend(RpcClientRequest request, Span span)	Like handleSend(RpcClientRequest), except explicitly controls the span representing the request.
Span	handleSendWithParent(RpcClientRequest request, TraceContext parent)	Like handleSend(RpcClientRequest), except explicitly controls the parent of the client span.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

create

public static RpcClientHandler create(RpcTracing rpcTracing)

Since:

5.12

handleSend

public Span handleSend(RpcClientRequest request)

Starts the client span after assigning it a name and tags. This injects the trace context onto the request before returning.

Call this before sending the request on the wire.

Since:

5.12

See Also:

handleSendWithParent(RpcClientRequest, TraceContext), RpcTracing.clientSampler(), RpcTracing.clientRequestParser()

handleSendWithParent

public Span handleSendWithParent(RpcClientRequest request, @Nullable TraceContext parent)

Like handleSend(RpcClientRequest), except explicitly controls the parent of the client span.

Parameters:

parent - the parent of the client span representing this request, or null for a new trace.

Since:

5.12

See Also:

Tracer.nextSpanWithParent(SamplerFunction, Object, TraceContext)

handleSend

public Span handleSend(RpcClientRequest request, Span span)

Like handleSend(RpcClientRequest), except explicitly controls the span representing the request.

Since:

5.12

handleReceive

public void handleReceive(RpcClientResponse response, Span span)

Finishes the client span after assigning it tags according to the response or error.

This is typically called once the response headers are received, and after the span is no longer in scope.

Note: It is valid to have a RpcClientResponse that only includes an error. However, it is better to also include the request.

Since:

5.12

See Also:

RpcResponseParser.parse(RpcResponse, TraceContext, SpanCustomizer)