Package brave.http

Class HttpRequest

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract String header​(String name)
      Returns one value corresponding to the specified header, or null.
      abstract String method()
      The HTTP method, or verb, such as "GET" or "POST".
      abstract String path()
      The absolute http path, without any query parameters.
      String route()
      Returns an expression such as "/items/:itemId" representing an application endpoint, conventionally associated with the tag key "http.route".
      long startTimestamp()
      The timestamp in epoch microseconds of the beginning of this request or zero to take this implicitly from the current clock.
      abstract String url()
      The entire URL, including the scheme, host and query parameters if available or null if unreadable.

      • Methods inherited from class brave.Request

        spanKind, toString, unwrap

    • Method Detail

      • startTimestamp

        public long startTimestamp()
        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.8
        See Also:
        HttpResponse.finishTimestamp(), Span.start(long), Tracing.clock(TraceContext)

      • method

        public abstract String method()
        The HTTP method, or verb, such as "GET" or "POST".

        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.

        See Also:
        HttpTags.METHOD

      • path

        @Nullable
public abstract String path()
        The absolute http path, without any query parameters. Ex. "/objects/abcd-ff"

        Conventionally associated with the key "http.path"

        null could mean not applicable to the HTTP method (ex CONNECT).

        Implementation notes

        Some HTTP client abstractions, such as JAX-RS and spring-web, return the input as opposed to the absolute path. One common problem is a path requested as "", not "/". When that's the case, normalize "" to "/". This ensures values are consistent with wire-level clients and behaviour consistent with RFC 7230 Section 2.7.3.

        Ex. 

        {@code
        See Also:
        url(), HttpResponse.route(), HttpTags.PATH

      • route

        @Nullable
public String route()
        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.

        The route is associated with the request, but it may not be visible until response processing. The reasons is that many server implementations process the request before they can identify the route. Parsing should expect this and look at HttpResponse.route() as needed.

        Since:
        5.10
        See Also:
        path(), HttpTags.ROUTE

      • url

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

        Conventionally associated with the key "http.url"

        See Also:
        path(), HttpResponse.route(), HttpTags.URL

      • header

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