Package brave.http

Class HttpServerHandler<Req,Resp>

java.lang.Object

brave.http.HttpServerHandler<Req,Resp>

Type Parameters:

Req - the native http request type of the server.

Resp - the native http response type of the server.

public final class HttpServerHandler<Req,Resp>
extends Object

This standardizes a way to instrument http servers, 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. Extract any trace IDs from headers and start the span
2. Put the span in scope so things like log integration works
3. Process the request
4. If there was a Throwable, add it to the span
5. Complete the span

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

Since:

4.3

Method Summary

Modifier and Type	Method	Description
static HttpServerHandler<HttpServerRequest,HttpServerResponse>	create(HttpTracing httpTracing)
static <Req,Resp> HttpServerHandler<Req,Resp>	create(HttpTracing httpTracing, HttpServerAdapter<Req,Resp> adapter)	Deprecated. Since 5.7, use create(HttpTracing) as it is more portable.
Span	handleReceive(HttpServerRequest request)	Conditionally joins a span, or starts a new trace, depending on if a trace context was extracted from the request.
<C> Span	handleReceive(TraceContext.Extractor<C> extractor, C carrier, Req request)	Deprecated. Since 5.7, use handleReceive(HttpServerRequest)
Span	handleReceive(TraceContext.Extractor<Req> extractor, Req request)	Deprecated. Since 5.7, use handleReceive(HttpServerRequest)
void	handleSend(HttpServerResponse response, Span span)	Finishes the server span after assigning it tags according to the response or error.
void	handleSend(Resp response, Throwable error, Span span)	Deprecated. Since 5.12, use handleSend(HttpServerResponse, Span)

Methods inherited from class java.lang.Object

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

Method Detail

create

public static HttpServerHandler<HttpServerRequest,HttpServerResponse> create(HttpTracing httpTracing)

Since:

5.7

create

@Deprecated
public static <Req,Resp> HttpServerHandler<Req,Resp> create(HttpTracing httpTracing,
                                                                        HttpServerAdapter<Req,Resp> adapter)

Deprecated.

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

Since:

4.3

handleReceive

public Span handleReceive(HttpServerRequest request)

Conditionally joins a span, or starts a new trace, depending on if a trace context was extracted from the request. Tags are added before the span is started.

This is typically called before the request is processed by the actual library.

Since:

5.7

See Also:

HttpTracing.serverRequestSampler(), HttpTracing.serverRequestParser()

handleReceive

@Deprecated
public Span handleReceive(TraceContext.Extractor<Req> extractor,
                          Req request)

Deprecated.

Since 5.7, use handleReceive(HttpServerRequest)

Since:

4.3

handleReceive

@Deprecated
public <C> Span handleReceive(TraceContext.Extractor<C> extractor,
                              C carrier,
                              Req request)

Deprecated.

Since 5.7, use handleReceive(HttpServerRequest)

Since:

4.3

handleSend

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

Deprecated.

Since 5.12, use handleSend(HttpServerResponse, Span)

Since:

4.3

handleSend

public void handleSend(HttpServerResponse response,
                       Span span)

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

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

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

Since:

5.12

See Also:

HttpResponseParser.parse(HttpResponse, TraceContext, SpanCustomizer)