Module brave.http
Package brave.http

Class HttpAdapter<Req,​Resp>

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      long finishTimestamp​(Resp response)
      The timestamp in epoch microseconds of the end of this request or zero to take this implicitly from the current clock.
      abstract java.lang.String method​(Req request)
      The HTTP method, or verb, such as "GET" or "POST" or null if unreadable.
      java.lang.String methodFromResponse​(Resp resp)
      Like method(Object) except used in response parsing.
      java.lang.String path​(Req request)
      The absolute http path, without any query parameters or null if unreadable.
      abstract java.lang.String requestHeader​(Req request, java.lang.String name)
      Returns one value corresponding to the specified header, or null.
      java.lang.String route​(Resp response)
      Returns an expression such as "/items/:itemId" representing an application endpoint, conventionally associated with the tag key "http.route".
      long startTimestamp​(Req request)
      The timestamp in epoch microseconds of the beginning of this request or zero to take this implicitly from the current clock.
      abstract java.lang.Integer statusCode​(Resp response)
      Deprecated.
      Since 5.7, use statusCodeAsInt(Object) which prevents boxing.
      int statusCodeAsInt​(Resp response)
      Like statusCode(Object) except returns a primitive where zero implies absent.
      abstract java.lang.String url​(Req request)
      The entire URL, including the scheme, host and query parameters if available or null if unreadable.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • method

        @Nullable
public abstract java.lang.String method​(Req request)
        The HTTP method, or verb, such as "GET" or "POST" or null if unreadable.

        Conventionally associated with the key "http.method"

        Note

        It is part of the HTTP RFC that an HTTP method is case-sensitive. Do not downcase results. If you do, not only will integration tests fail, but you will surprise any consumers who expect compliant results.

      • path

        @Nullable
public java.lang.String path​(Req request)
        The absolute http path, without any query parameters or null if unreadable. Ex. "/objects/abcd-ff"

        Conventionally associated with the key "http.path"

        See Also:
        route(Object)

      • url

        @Nullable
public abstract java.lang.String url​(Req request)
        The entire URL, including the scheme, host and query parameters if available or null if unreadable.

        Conventionally associated with the key "http.url"

      • requestHeader

        @Nullable
public abstract java.lang.String requestHeader​(Req request,
                                               java.lang.String name)
        Returns one value corresponding to the specified header, or null.

      • startTimestamp

        public long startTimestamp​(Req request)
        The timestamp in epoch microseconds of the beginning of this request or zero to take this implicitly from the current clock. Defaults to zero.

        This is helpful in two scenarios: late parsing and avoiding redundant timestamp overhead. If a server span, this helps reach the "original" beginning of the request, which is always prior to parsing.

        Note: Overriding has the same problems as using Span.start(long). For example, it can result in negative duration if the clock used is allowed to correct backwards. It can also result in misalignments in the trace, unless Tracing.Builder.clock(Clock) uses the same implementation.

        Since:
        5.7
        See Also:
        finishTimestamp(Object), Span.start(long), Tracing.clock(TraceContext)

      • methodFromResponse

        @Nullable
public java.lang.String methodFromResponse​(Resp resp)
        Like method(Object) except used in response parsing.

        Notably, this is used to create a route-based span name.

      • route

        @Nullable
public java.lang.String route​(Resp response)
        Returns an expression such as "/items/:itemId" representing an application endpoint, conventionally associated with the tag key "http.route". If no route matched, "" (empty string) is returned. Null indicates this instrumentation doesn't understand http routes.

        Eventhough the route is associated with the request, not the response, this is present on the response object. The reasons is that many server implementations process the request before they can identify the route route.

      • statusCode

        @Deprecated
@Nullable
public abstract java.lang.Integer statusCode​(Resp response)
        Deprecated.
        Since 5.7, use statusCodeAsInt(Object) which prevents boxing.
        The HTTP status code or null if unreadable.

        Conventionally associated with the key "http.status_code"

        See Also:
        statusCodeAsInt(Object)

      • statusCodeAsInt

        public int statusCodeAsInt​(Resp response)
        Like statusCode(Object) except returns a primitive where zero implies absent.

        Using this method usually avoids allocation, so is encouraged when parsing data.

        Since:
        4.16

      • finishTimestamp

        public long finishTimestamp​(Resp response)
        The timestamp in epoch microseconds of the end of this request or zero to take this implicitly from the current clock. Defaults to zero.

        This is helpful in two scenarios: late parsing and avoiding redundant timestamp overhead. For example, you can asynchronously handle span completion without losing precision of the actual end.

        Note: Overriding has the same problems as using Span.finish(long). For example, it can result in negative duration if the clock used is allowed to correct backwards. It can also result in misalignments in the trace, unless Tracing.Builder.clock(Clock) uses the same implementation.

        Since:
        5.7
        See Also:
        startTimestamp(Object), Span.finish(long), Tracing.clock(TraceContext)