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 Object

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

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

 HttpClientRequestWrapper requestWrapper = new HttpClientRequestWrapper(request);
 Span span = handler.handleSend(requestWrapper); // 1.
 HttpClientResponse 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 {
   HttpClientResponseWrapper responseWrapper =
     new HttpClientResponseWrapper(requestWrapper, response, error);
   handler.handleReceive(responseWrapper, span); // 5.
 }
 

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(HttpClientResponse response, Span span)	Finishes the client span after assigning it tags according to the response or error.
void	handleReceive(Resp response, Throwable error, Span span)	Deprecated. since 5.12 use handleReceive(HttpClientResponse, Span)
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).
<C> Span	handleSend(TraceContext.Injector<C> injector, C carrier, Req request, Span span)	Deprecated. Since 5.7, use handleSend(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, Span).
Span	handleSendWithParent(HttpClientRequest request, TraceContext parent)	Like handleSend(HttpClientRequest), except explicitly controls the parent of the client span.
Span	nextSpan(Req request)	Deprecated. since 5.8 use Tracer.nextSpan(SamplerFunction, Object)

Methods inherited from class java.lang.Object

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

Method Details

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.

Since:

4.3

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

See Also:

handleSendWithParent(HttpClientRequest, TraceContext), HttpTracing.clientRequestSampler(), HttpTracing.clientRequestParser()

handleSendWithParent

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

Like handleSend(HttpClientRequest), 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.10

See Also:

Tracer.nextSpanWithParent(SamplerFunction, Object, TraceContext)

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.

Since:

4.3

handleSend

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

Deprecated.

Since 5.7, use handleSend(HttpClientRequest).

Since:

4.3

handleSend

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

Deprecated.

Since 5.7, use handleSend(HttpClientRequest, Span).

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).

Since:

4.4

nextSpan

@Deprecated public Span nextSpan(Req request)

Deprecated.

since 5.8 use Tracer.nextSpan(SamplerFunction, Object)

Since:

4.4

handleReceive

@Deprecated public void handleReceive(@Nullable Resp response, @Nullable Throwable error, Span span)

Deprecated.

since 5.12 use handleReceive(HttpClientResponse, Span)

Since:

4.3

handleReceive

public void handleReceive(HttpClientResponse 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 HttpClientResponse that only includes an error. However, it is better to also include the request.

Since:

5.12

See Also:

HttpResponseParser.parse(HttpResponse, TraceContext, SpanCustomizer)