Package brave.rpc

Class RpcTracing

java.lang.Object

brave.rpc.RpcTracing

All Implemented Interfaces:

Closeable, AutoCloseable

public class RpcTracing
extends Object
implements Closeable

Instances built via create(Tracing) or newBuilder(Tracing) are registered automatically such that statically configured instrumentation like RPC clients can use current().

Since:

5.8

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	RpcTracing.Builder

Method Summary

Modifier and Type	Method	Description
RpcRequestParser	clientRequestParser()	Used by RpcClientHandler.handleSend(RpcClientRequest) to add a span name and tags about the request before it is sent to the server.
RpcResponseParser	clientResponseParser()	Used by RpcClientHandler.handleReceive(RpcClientResponse, Span) to add tags about the response received from the server.
SamplerFunction<RpcRequest>	clientSampler()	Returns an overriding sampling decision for a new trace.
void	close()
static RpcTracing	create(Tracing tracing)
static RpcTracing	current()	Returns the most recently created tracing component iff it hasn't been closed.
static RpcTracing.Builder	newBuilder(Tracing tracing)
Propagation<String>	propagation()	Returns the propagation component used by RPC instrumentation.
RpcRequestParser	serverRequestParser()	Used by RpcServerHandler.handleReceive(RpcServerRequest) to add a span name and tags about the request before the server processes it.
RpcResponseParser	serverResponseParser()	Used by RpcServerHandler.handleSend(RpcServerResponse, Span) to add tags about the response sent to the client.
SamplerFunction<RpcRequest>	serverSampler()	Returns an overriding sampling decision for a new trace.
RpcTracing.Builder	toBuilder()
Tracing	tracing()

Methods inherited from class java.lang.Object

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

Method Detail

create

public static RpcTracing create(Tracing tracing)

Since:

5.8

newBuilder

public static RpcTracing.Builder newBuilder(Tracing tracing)

Since:

5.8

tracing

public Tracing tracing()

Since:

5.8

clientRequestParser

public RpcRequestParser clientRequestParser()

Used by RpcClientHandler.handleSend(RpcClientRequest) to add a span name and tags about the request before it is sent to the server.

Since:

5.12

clientResponseParser

public RpcResponseParser clientResponseParser()

Used by RpcClientHandler.handleReceive(RpcClientResponse, Span) to add tags about the response received from the server.

Since:

5.12

serverRequestParser

public RpcRequestParser serverRequestParser()

Used by RpcServerHandler.handleReceive(RpcServerRequest) to add a span name and tags about the request before the server processes it.

Since:

5.12

serverResponseParser

public RpcResponseParser serverResponseParser()

Used by RpcServerHandler.handleSend(RpcServerResponse, Span) to add tags about the response sent to the client.

Since:

5.12

clientSampler

public SamplerFunction<RpcRequest> clientSampler()

Returns an overriding sampling decision for a new trace. Defaults to ignore the request and use the trace ID instead.

This decision happens when a trace was not yet started in process. For example, you may be making an RPC request as a part of booting your application. You may want to opt-out of tracing client requests that did not originate from a server request.

Since:

5.8

See Also:

SamplerFunctions, RpcRuleSampler

serverSampler

public SamplerFunction<RpcRequest> serverSampler()

Returns an overriding sampling decision for a new trace. Defaults to ignore the request and use the trace ID instead.

This decision happens when trace IDs were not in headers, or a sampling decision has not yet been made. For example, if a trace is already in progress, this function is not called. You can implement this to skip paths that you never want to trace.

Since:

5.8

See Also:

SamplerFunctions, RpcRuleSampler

propagation

public Propagation<String> propagation()

Returns the propagation component used by RPC instrumentation.

Typically, this is the same as Tracing.propagation(). Overrides will apply to all RPC instrumentation in use. For example, Dubbo and also gRPC. If only trying to change B3 related headers, use the more efficient B3Propagation.FactoryBuilder.injectFormat(Span.Kind, B3Propagation.Format) instead.

Use caution when overriding

If overriding this via RpcTracing.Builder.propagation(Propagation), take care to also delegate to Tracing.propagation(). Otherwise, you can break features something else may have set, such as BaggagePropagation.

Library-specific formats

RPC instrumentation can localize propagation changes by calling toBuilder(), then RpcTracing.Builder.propagation(Propagation). This allows library-specific formats.

For example, gRPC has an undocumented format "grpc-trace-bin". Brave's implementation of GrpcTracing internally does the following to override, but only for this library:

 if (grpcPropagationFormatEnabled) {
   rpcTracing = builder.rpcTracing.toBuilder()
     .propagation(GrpcPropagation.create(builder.rpcTracing.propagation()))
     .build();
 } else {
   rpcTracing = builder.rpcTracing;
 }
 

Since:

5.13

See Also:

Tracing.propagation()

toBuilder

public RpcTracing.Builder toBuilder()

current

@Nullable
public static RpcTracing current()

Returns the most recently created tracing component iff it hasn't been closed. null otherwise.

This object should not be cached.

Since:

5.9

close

public void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Since:

5.9