Package org.microproxy.otel

Class Telemetry

java.lang.Object
org.microproxy.otel.Telemetry
All Implemented Interfaces:
AutoCloseable, FlowTracer
public final class Telemetry extends Object implements FlowTracer
OpenTelemetry for the proxy, with nothing but the JDK: context propagation (W3C Trace Context, and B3 and Jaeger when configured), an X-Request-Id per request, a SERVER span per exchange (HTTP/1, HTTP/2 and HTTP/3) with a CLIENT span per attempt to reach the server, an INTERNAL span per tunnel or flow (CONNECT, SOCKS, WebSocket, CONNECT-UDP, QUIC), and the export over OTLP/HTTP, as protobuf or JSON, of those spans, of the proxy's stats as metrics, and of its access-log records as log records. 

 Telemetry otel = Telemetry.fromEnvironment()          // OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, ...
         .serviceName("edge")
         .sampler(Sampler.parentBased(Sampler.traceIdRatio(0.1)))
         .build();
 HttpProxyServer proxy = otel.install(MicroProxy.bootstrap().withPort(8080)).start();

Disabled (OTEL_SDK_DISABLED=true, enabled(false)), install(org.microproxy.HttpProxyServerBootstrap) leaves the proxy untouched, so it does no work at all. Enabled, a request whose trace is not sampled costs its ids and the headers written upstream; only sampled exchanges allocate spans. Spans and log records wait in bounded queues and are exported in batches by a virtual thread per signal; when a queue is full they are dropped and counted ( otel.spans_dropped, otel.logs_dropped), never waited for.

  • Method Details

    • builder

      public static Telemetry.Builder builder()
      Returns a builder with the defaults: everything exported to http://localhost:4318.
      Returns:
      a builder with the defaults: everything exported to http://localhost:4318

    • fromEnvironment

      public static Telemetry.Builder fromEnvironment()
      A builder configured from the process's environment (OTEL_* variables, see fromEnvironment(Map)).
      Returns:
      the builder
      Throws:
      IllegalArgumentException - if a variable has a bad value

    • fromEnvironment

      public static Telemetry.Builder fromEnvironment(Map<String,String> env)
      A builder configured from env, OpenTelemetry's environment variables: OTEL_SDK_DISABLED, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_{TRACES,METRICS,LOGS}_EXPORTER (otlp or none), OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS, OTEL_METRIC_EXPORT_INTERVAL, OTEL_BSP_* and OTEL_BLRP_* ( SCHEDULE_DELAY, MAX_QUEUE_SIZE, MAX_EXPORT_BATCH_SIZE), and the span limits (OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT, OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT, OTEL_SPAN_EVENT_COUNT_LIMIT, OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT).
      Parameters:
      env - the environment
      Returns:
      the builder
      Throws:
      IllegalArgumentException - if a variable has a bad value

    • isEnabled

      public boolean isEnabled()
      Returns whether this telemetry does anything: false once the SDK is disabled.
      Returns:
      whether this telemetry does anything: false once the SDK is disabled

    • install

      public HttpProxyServerBootstrap install(HttpProxyServerBootstrap bootstrap)
      Wires this telemetry into bootstrap: its tracer (HttpProxyServerBootstrap.withTracer(org.microproxy.FlowTracer)), metrics turned on when they are exported, and the access-log exporter as an ActivityTracker when logs are. Disabled, it changes nothing.
      Parameters:
      bootstrap - the proxy's configuration
      Returns:
      bootstrap

    • accessLogExporter

      public ActivityTracker accessLogExporter()
      Returns the access-log exporter, which install(org.microproxy.HttpProxyServerBootstrap) adds as a tracker; null without log export.
      Returns:
      the access-log exporter, which install(org.microproxy.HttpProxyServerBootstrap) adds as a tracker; null without log export

    • startExchange

      public FlowTrace startExchange(FlowContext flow, HttpRequest request)
      Description copied from interface: FlowTracer
      Called when a request head arrives from the client, before trackers, authentication and filters see it, so that headers the tracer adds (an X-Request-Id) are seen by all of them and the access log. The request may also be a CONNECT (real, or made up for a SOCKS client or a transparent connection), which opens a tunnel or a flow.
      Specified by:
      startExchange in interface FlowTracer
      Parameters:
      flow - the exchange's context
      request - the request head, which may be changed in place
      Returns:
      the exchange's trace, or FlowTrace.NONE to trace nothing

    • flowEnded

      public void flowEnded(FlowRecord record)
      Description copied from interface: FlowTracer
      Called once per finished exchange or flow, with the record ActivityTracker.flowEnded(org.microproxy.FlowRecord) gets: FlowRecord.trace() is the trace FlowTracer.startExchange(org.microproxy.FlowContext, org.microproxy.http.HttpRequest) made, or FlowTrace.NONE for a flow that had no request of its own (a relayed transparent QUIC flow, a request a transport answered itself).
      Specified by:
      flowEnded in interface FlowTracer
      Parameters:
      record - the finished exchange or flow

    • proxyStarted

      public void proxyStarted(HttpProxyServer server)
      Description copied from interface: FlowTracer
      Called once a proxy that uses this tracer has started, for instance to read its stats.
      Specified by:
      proxyStarted in interface FlowTracer
      Parameters:
      server - the running proxy

    • flush

      public boolean flush(Duration timeout)
      Exports what is queued now (spans, log records) and the metrics, waiting up to timeout for each.
      Parameters:
      timeout - how long to wait for each signal
      Returns:
      whether everything was sent in time

    • close

      public void close()
      Exports what is left, then stops the exporters; the proxy calls it once it has stopped.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface FlowTracer

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • description

      public String description()
      Returns what this telemetry exports, and where.
      Returns:
      what this telemetry exports, and where