Package org.microproxy.otel

Class Telemetry.Builder

java.lang.Object
org.microproxy.otel.Telemetry.Builder
Enclosing class:
Telemetry
public static final class Telemetry.Builder extends Object
Configures a Telemetry; every setting has OpenTelemetry's default.

  • Method Details

    • enabled

      public Telemetry.Builder enabled(boolean enabled)
      Turns everything on (the default) or off; off, Telemetry.install(org.microproxy.HttpProxyServerBootstrap) changes nothing.
      Parameters:
      enabled - whether to trace and export
      Returns:
      this builder

    • endpoint

      public Telemetry.Builder endpoint(String endpoint)
      The collector's OTLP/HTTP base URL; each signal goes to <endpoint>/v1/<signal>.
      Parameters:
      endpoint - such as http://otel-collector:4318
      Returns:
      this builder

    • tracesEndpoint

      public Telemetry.Builder tracesEndpoint(String url)
      The URL spans go to, as it is (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT).
      Parameters:
      url - the full URL, such as http://collector:4318/v1/traces
      Returns:
      this builder

    • metricsEndpoint

      public Telemetry.Builder metricsEndpoint(String url)
      The URL metrics go to, as it is.
      Parameters:
      url - the full URL
      Returns:
      this builder

    • logsEndpoint

      public Telemetry.Builder logsEndpoint(String url)
      The URL log records go to, as it is.
      Parameters:
      url - the full URL
      Returns:
      this builder

    • protocol

      public Telemetry.Builder protocol(Telemetry.Protocol protocol)
      How OTLP is sent: protobuf (the default) or JSON.
      Parameters:
      protocol - the protocol
      Returns:
      this builder

    • header

      public Telemetry.Builder header(String name, String value)
      Adds a header to every export, such as authorization.
      Parameters:
      name - the header's name
      value - its value
      Returns:
      this builder

    • compression

      public Telemetry.Builder compression(boolean gzip)
      Gzips the exports (OTEL_EXPORTER_OTLP_COMPRESSION=gzip).
      Parameters:
      gzip - whether to compress
      Returns:
      this builder

    • timeout

      public Telemetry.Builder timeout(Duration timeout)
      How long one export attempt may take, connecting included (10 seconds by default).
      Parameters:
      timeout - the timeout
      Returns:
      this builder

    • retry

      public Telemetry.Builder retry(int maxAttempts, Duration initial, Duration max)
      How failed exports are retried: attempts in all (5 by default), and the backoff between them, growing by half each time from initial (1 s) up to max (5 s), with jitter, and never shorter than a Retry-After.
      Parameters:
      maxAttempts - the attempts per batch, at least 1
      initial - the first wait
      max - the longest wait
      Returns:
      this builder

    • serviceName

      public Telemetry.Builder serviceName(String name)
      service.name (OTEL_SERVICE_NAME); microproxy by default.
      Parameters:
      name - the service's name
      Returns:
      this builder

    • resourceAttribute

      public Telemetry.Builder resourceAttribute(String key, String value)
      A resource attribute (OTEL_RESOURCE_ATTRIBUTES), besides service.*, host.name, process.* and telemetry.sdk.*, which it may override.
      Parameters:
      key - the attribute
      value - its value
      Returns:
      this builder

    • sampler

      public Telemetry.Builder sampler(Sampler sampler)
      The sampler; parentbased_always_on by default.
      Parameters:
      sampler - the sampler
      Returns:
      this builder

    • forceTraceHeader

      public Telemetry.Builder forceTraceHeader(String header)
      Samples every request that has header, whatever the sampler says (Envoy's x-envoy-force-trace); none by default.
      Parameters:
      header - the header's name, or null for none
      Returns:
      this builder

    • propagators

      public Telemetry.Builder propagators(List<Propagator> propagators)
      The propagators, as OpenTelemetry's composite propagator: they extract in order, so the last that finds a valid context in a request gives the parent, and all write the proxy's context upstream; W3C Trace Context by default.
      Parameters:
      propagators - the propagators, possibly none
      Returns:
      this builder

    • trustIncoming

      public Telemetry.Builder trustIncoming(boolean trust)
      Whether to continue the traces clients send (the default), or start a new trace for every request, as a trust boundary.
      Parameters:
      trust - whether to read the clients' trace context
      Returns:
      this builder

    • whenStripped

      public Telemetry.Builder whenStripped(Telemetry.WhenStripped mode)
      What goes upstream when the proxy strips tracing headers: the proxy's own context (the default) or nothing.
      Parameters:
      mode - the mode
      Returns:
      this builder

    • requestId

      public Telemetry.Builder requestId(Telemetry.RequestIdMode mode)
      What happens to X-Request-Id: kept, or made when missing (the default), always made, or left alone.
      Parameters:
      mode - the mode
      Returns:
      this builder

    • traces

      public Telemetry.Builder traces(boolean on)
      Whether spans are exported (OTEL_TRACES_EXPORTER); without them the proxy still propagates.
      Parameters:
      on - whether to export spans
      Returns:
      this builder

    • metrics

      public Telemetry.Builder metrics(boolean on)
      Whether the proxy's stats are exported as metrics (OTEL_METRICS_EXPORTER).
      Parameters:
      on - whether to export metrics
      Returns:
      this builder

    • logs

      public Telemetry.Builder logs(boolean on)
      Whether access-log records are exported as log records (OTEL_LOGS_EXPORTER).
      Parameters:
      on - whether to export logs
      Returns:
      this builder

    • metricInterval

      public Telemetry.Builder metricInterval(Duration interval)
      How often metrics are exported (OTEL_METRIC_EXPORT_INTERVAL, 60 s).
      Parameters:
      interval - the interval
      Returns:
      this builder

    • metricPrefix

      public Telemetry.Builder metricPrefix(String prefix)
      The prefix of exported metric names; the registry's (envoy) by default.
      Parameters:
      prefix - the prefix, or an empty string for none
      Returns:
      this builder

    • spanQueue

      public Telemetry.Builder spanQueue(int maxQueue, int maxBatch, Duration delay)
      The span queue (OTEL_BSP_*): its size (2048), the largest batch (512) and how long a span waits for its batch to fill (5 s).
      Parameters:
      maxQueue - spans waiting at most; more are dropped
      maxBatch - spans per export at most
      delay - the wait
      Returns:
      this builder

    • logQueue

      public Telemetry.Builder logQueue(int maxQueue, int maxBatch, Duration delay)
      The log record queue (OTEL_BLRP_*): 2048, 512 and 1 s by default.
      Parameters:
      maxQueue - log records waiting at most; more are dropped
      maxBatch - log records per export at most
      delay - the wait
      Returns:
      this builder

    • spanLimits

      public Telemetry.Builder spanLimits(SpanLimits limits)
      The span limits.
      Parameters:
      limits - the limits
      Returns:
      this builder

    • logFormat

      public Telemetry.Builder logFormat(AccessLogFormat format)
      The body of exported log records: an access-log format; Envoy's default by default.
      Parameters:
      format - the format
      Returns:
      this builder

    • build

      public Telemetry build()
      Returns the telemetry; its exporters' threads start now.
      Returns:
      the telemetry; its exporters' threads start now