Module brave.http

Package brave.http

Class HttpClientHandler<Req,Resp>

java.lang.Object

brave.http.HttpClientHandler<Req,Resp>

Type Parameters:

Req - the native http request type of the client.

Resp - the native http response type of the client.

public final class HttpClientHandler<Req,Resp>
extends java.lang.Object

This standardizes a way to instrument http clients, particularly in a way that encourages use of portable customizations via HttpClientParser.

This is an example of synchronous instrumentation:

 Span span = handler.handleSend(request);
 Throwable error = null;
 try (Tracer.SpanInScope ws = tracer.withSpanInScope(span)) {
   // any downstream code can see Tracer.currentSpan() or use Tracer.currentSpanCustomizer()
   response = invoke(request);
 } catch (RuntimeException | Error e) {
   error = e;
   throw e;
 } finally {
   handler.handleReceive(response, error, span);
 }
 

Since:

4.3

Method Summary

Modifier and Type	Method	Description
static HttpClientHandler<HttpClientRequest,HttpClientResponse>	create(HttpTracing httpTracing)
static <Req,Resp> HttpClientHandler<Req,Resp>	create(HttpTracing httpTracing, HttpClientAdapter<Req,Resp> adapter)	Deprecated. Since 5.7, use create(HttpTracing) as it is more portable.
void	handleReceive(Resp response, java.lang.Throwable error, Span span)	Finishes the client span after assigning it tags according to the response or error.
Span	handleSend(HttpClientRequest request)	Starts the client span after assigning it a name and tags.
Span	handleSend(HttpClientRequest request, Span span)	Like handleSend(HttpClientRequest), except explicitly controls the span representing the request.
<C> Span	handleSend(TraceContext.Injector<C> injector, C carrier, Req request)	Deprecated. Since 5.7, use handleSend(HttpClientRequest) to handle any difference between carrier and request via wrapping in HttpClientRequest.
<C> Span	handleSend(TraceContext.Injector<C> injector, C carrier, Req request, Span span)	Deprecated. Since 5.7, use handleSend(HttpClientRequest) to handle any difference between carrier and request via wrapping in HttpClientRequest.
Span	handleSend(TraceContext.Injector<Req> injector, Req request)	Deprecated. Since 5.7, use handleSend(HttpClientRequest), as this allows more advanced samplers to be used.
Span	handleSend(TraceContext.Injector<Req> injector, Req request, Span span)	Deprecated. Since 5.7, use handleSend(HttpClientRequest), as this allows more advanced samplers to be used.
Span	nextSpan(Req request)	Creates a potentially noop span representing this request.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static HttpClientHandler<HttpClientRequest,HttpClientResponse> create(HttpTracing httpTracing)

Since:

5.7

create

@Deprecated
public static <Req,Resp> HttpClientHandler<Req,Resp> create(HttpTracing httpTracing,
                                                                        HttpClientAdapter<Req,Resp> adapter)

Deprecated.

Since 5.7, use create(HttpTracing) as it is more portable.

handleSend

public Span handleSend(HttpClientRequest 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.7

handleSend

public Span handleSend(HttpClientRequest request,
                       Span span)

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

Since:

5.7

handleSend

@Deprecated
public Span handleSend(TraceContext.Injector<Req> injector,
                       Req request)

Deprecated.

Since 5.7, use handleSend(HttpClientRequest), as this allows more advanced samplers to be used.

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.

handleSend

@Deprecated
public <C> Span handleSend(TraceContext.Injector<C> injector,
                           C carrier,
                           Req request)

Deprecated.

Since 5.7, use handleSend(HttpClientRequest) to handle any difference between carrier and request via wrapping in HttpClientRequest.

Like handleSend(Injector, Object), except for when the carrier of trace data is not the same as the request.

See Also:

HttpClientParser.request(HttpAdapter, Object, SpanCustomizer)

handleSend

@Deprecated
public Span handleSend(TraceContext.Injector<Req> injector,
                       Req request,
                       Span span)

Deprecated.

Since 5.7, use handleSend(HttpClientRequest), as this allows more advanced samplers to be used.

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

Since:

4.4

handleSend

@Deprecated
public <C> Span handleSend(TraceContext.Injector<C> injector,
                           C carrier,
                           Req request,
                           Span span)

Deprecated.

Since 5.7, use handleSend(HttpClientRequest) to handle any difference between carrier and request via wrapping in HttpClientRequest.

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

Since:

4.4

nextSpan

public Span nextSpan(Req request)

Creates a potentially noop span representing this request. This is used when you need to provision a span in a different scope than where the request is executed.

Since:

4.4

handleReceive

public void handleReceive(@Nullable
                          Resp response,
                          @Nullable
                          java.lang.Throwable error,
                          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.

See Also:

HttpClientParser.response(HttpAdapter, Object, Throwable, SpanCustomizer)