Package org.microproxy

Interface FlowTrace

public interface FlowTrace
The distributed trace of one exchange, made by a FlowTracer when the request head arrives: its trace and span ids, which FlowContext.trace(), access logs ( %TRACE_ID%, %SPAN_ID%) and scripts (ctx.trace_id) show, and the calls through which the proxy reports each attempt to reach the server and asks for the headers that carry the trace to it.

The proxy calls the attempt methods on the exchange's thread, in this order for each attempt: attemptStarted(java.lang.String, org.microproxy.ChainedProxy, boolean) when it begins to connect to the server or a chained proxy (or to send the request on a connection at hand), upstreamRequest(boolean, org.microproxy.http.HttpVersion) once the exchange's request is about to go on the connection, injectUpstream(org.microproxy.http.HttpHeaders, boolean) right before a request head (the exchange's, or a CONNECT to a chained proxy) is written, and attemptEnded(int, java.lang.String). A failed connection to one chained proxy, the next one tried, and a request sent again after a stale keep-alive connection are attempts of their own. Every method has a no-op default; NONE is the trace of an exchange nobody traces.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    FlowTrace.Span
    A span startSpan(java.lang.String) started, used by one thread at a time.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final FlowTrace
    NONE
    No trace: ids are null and every call does nothing.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    addEvent(String name, Map<String,?> attributes)
    Adds an event, at the current time, to the exchange's span; ignored when it is not sampled.
    default void
    attemptEnded(int status, String errorType)
    The current attempt is over.
    default void
    attemptStarted(String hostAndPort, ChainedProxy chainedProxy, boolean tls)
    An attempt to reach the server begins: a connection to it or to a chained proxy, or a request on a connection at hand.
    default void
    injectUpstream(HttpHeaders headers, boolean tracingHeadersStripped)
    A request head is about to be written upstream for the current attempt, after the proxy removed the headers it strips (HttpProxyServerBootstrap.withStrippedRequestHeaders(java.lang.String...)): the trace may put its propagation headers on it.
    default boolean
    isSampled()
    Returns whether the trace is sampled: its spans are recorded and exported.
    default String
    requestId()
    The exchange's request id (X-Request-Id), which access logs show as %UNIQUE_ID% too, or null to leave FlowRecord.uniqueId() random.
    default void
    setAttribute(String key, Object value)
    Adds an attribute to the exchange's span; ignored when it is not sampled.
    default String
    spanId()
    Returns the id of the proxy's span for the exchange, 16 lower-case hex digits, or null.
    default FlowTrace.Span
    startSpan(String name)
    Starts a span of the proxy's own work for the exchange, such as a script's hook call: an INTERNAL span, a child of the exchange's span (of the tunnel's or flow's, for the hooks of a tunnel or a flow), which ends when FlowTrace.Span.end(java.lang.String) is called.
    default String
    traceId()
    Returns the trace id, 32 lower-case hex digits, or null for no trace.
    default void
    upstreamRequest(boolean tls, HttpVersion version)
    The exchange's request is about to go to the server on the current attempt's connection, as that connection really is.

  • Field Details

    • NONE

      static final FlowTrace NONE
      No trace: ids are null and every call does nothing.

  • Method Details

    • traceId

      default String traceId()
      Returns the trace id, 32 lower-case hex digits, or null for no trace.
      Returns:
      the trace id, 32 lower-case hex digits, or null for no trace

    • spanId

      default String spanId()
      Returns the id of the proxy's span for the exchange, 16 lower-case hex digits, or null.
      Returns:
      the id of the proxy's span for the exchange, 16 lower-case hex digits, or null

    • isSampled

      default boolean isSampled()
      Returns whether the trace is sampled: its spans are recorded and exported.
      Returns:
      whether the trace is sampled: its spans are recorded and exported

    • requestId

      default String requestId()
      The exchange's request id (X-Request-Id), which access logs show as %UNIQUE_ID% too, or null to leave FlowRecord.uniqueId() random.
      Returns:
      the request id, or null

    • setAttribute

      default void setAttribute(String key, Object value)
      Adds an attribute to the exchange's span; ignored when it is not sampled.
      Parameters:
      key - the attribute's name
      value - a String, Boolean, integer, floating-point number, or a list of those; other values are recorded as their toString()

    • addEvent

      default void addEvent(String name, Map<String,?> attributes)
      Adds an event, at the current time, to the exchange's span; ignored when it is not sampled.
      Parameters:
      name - the event's name
      attributes - the event's attributes (values as for setAttribute(java.lang.String, java.lang.Object)), possibly empty

    • startSpan

      default FlowTrace.Span startSpan(String name)
      Starts a span of the proxy's own work for the exchange, such as a script's hook call: an INTERNAL span, a child of the exchange's span (of the tunnel's or flow's, for the hooks of a tunnel or a flow), which ends when FlowTrace.Span.end(java.lang.String) is called. A trace that is not sampled returns FlowTrace.Span.NONE, so callers that only start spans when isSampled() pay nothing otherwise.
      Parameters:
      name - the span's name, such as starlark on_request
      Returns:
      the span, or FlowTrace.Span.NONE

    • attemptStarted

      default void attemptStarted(String hostAndPort, ChainedProxy chainedProxy, boolean tls)
      An attempt to reach the server begins: a connection to it or to a chained proxy, or a request on a connection at hand.
      Parameters:
      hostAndPort - the server's host:port
      chainedProxy - the chained proxy the attempt goes through, or null for a direct connection
      tls - whether the proxy speaks TLS to the server itself (to an https origin, an intercepted session's server or a reverse proxy's https:// upstream), whatever the connection to a chained proxy is

    • upstreamRequest

      default void upstreamRequest(boolean tls, HttpVersion version)
      The exchange's request is about to go to the server on the current attempt's connection, as that connection really is.
      Parameters:
      tls - whether the proxy speaks TLS to the server on it (HTTP/2 and HTTP/3 always do)
      version - the protocol of the connection: HttpVersion.HTTP_1_1, HttpVersion.HTTP_2_0 (a stream of a shared HTTP/2 connection) or HttpVersion.HTTP_3_0

    • injectUpstream

      default void injectUpstream(HttpHeaders headers, boolean tracingHeadersStripped)
      A request head is about to be written upstream for the current attempt, after the proxy removed the headers it strips (HttpProxyServerBootstrap.withStrippedRequestHeaders(java.lang.String...)): the trace may put its propagation headers on it.
      Parameters:
      headers - the request's headers, to change in place
      tracingHeadersStripped - whether the proxy strips the tracing headers ( traceparent among them) from requests sent upstream

    • attemptEnded

      default void attemptEnded(int status, String errorType)
      The current attempt is over.
      Parameters:
      status - the status of the server's response, or 0 when none came
      errorType - why the attempt failed, as a short low-cardinality name ( connect_failed, server_timeout, stale_connection, ...), or null when it did not