Class TelemetryConfig

java.lang.Object
com.codename1.telemetry.TelemetryConfig
public final class TelemetryConfig extends Object

Where Telemetry sends spans, and how.

Two ways to reach a collector:

  • Relay (the default): the app posts OTLP/JSON to its own backend -- a Codename One backend with cn1.otel.relay=true -- which adds the collector's credentials and forwards the spans. Nothing secret ships in the app, and a browser never has to reach a third-party collector, so the JavaScript port needs no CORS setup on it.
  • Direct: the app posts to an OTLP/HTTP collector itself. Simpler to stand up, but whatever header authenticates the export is inside the app package, and anything inside an app package is public. Use an ingest token scoped to writing traces and nothing else.
Telemetry.install(new TelemetryConfig()
        .relay("https://api.example.com")
        .serviceName("shop-app"));

  • Constructor Details

    • TelemetryConfig

      public TelemetryConfig()

  • Method Details

    • relay

      public TelemetryConfig relay(String backendUrl)

      Sends spans through a Codename One backend's relay.

      Parameters
      • backendUrl: the backend's base URL, such as https://api.example.com; /otel/v1/traces is appended. A URL that already names a path ending in /v1/traces is used as it is, for a relay mounted elsewhere.
      Returns

      this configuration

      Throws
      • IllegalArgumentException: when the URL is not http or https with a host and a valid port

    • direct

      public TelemetryConfig direct(String collectorUrl)

      Sends spans straight to an OTLP/HTTP collector.

      Parameters
      • collectorUrl: the collector's base URL, /v1/traces appended unless it is already there -- the same rule OTEL_EXPORTER_OTLP_ENDPOINT follows everywhere
      Returns

      this configuration

      Throws
      • IllegalArgumentException: when the URL is not http or https with a host and a valid port

    • serviceName

      public TelemetryConfig serviceName(String name)

      The service.name the app's spans are reported under. Defaults to the app's name.

      Returns

      this configuration

    • header

      public TelemetryConfig header(String name, String value)

      A header sent with every direct export -- the collector's credential. Ignored in relay mode, where the backend holds the credential.

      Returns

      this configuration

      Throws
      • IllegalArgumentException: when the name is not an HTTP token or the value holds a control character

    • relayToken

      public TelemetryConfig relayToken(String token)

      The shared secret a backend's relay may require (cn1.otel.relay.token). It keeps casual traffic off the relay; it is not a credential, since it ships in the app.

      Returns

      this configuration

      Throws
      • IllegalArgumentException: when the token holds a control character, or begins or ends with whitespace

    • protobuf

      public TelemetryConfig protobuf(boolean protobuf)

      Whether direct exports use binary protobuf (the default) or JSON. Some collectors accept only protobuf. The relay always receives JSON, and re-encodes it for the collector as the backend is configured to.

      Returns

      this configuration

    • sampleRatio

      public TelemetryConfig sampleRatio(double ratio)

      The share of NEW traces recorded, from 0 to 1. A request made inside a span follows that span's decision, and the backend follows the app's.

      Returns

      this configuration

      Throws
      • IllegalArgumentException: for NaN

    • batchSize

      public TelemetryConfig batchSize(int size)

      How many ended spans are buffered before an export. Defaults to 32.

      Returns

      this configuration

    • flushIntervalMillis

      public TelemetryConfig flushIntervalMillis(int millis)

      How often buffered spans are exported even when the batch is not full. Defaults to ten seconds.

      Returns

      this configuration

    • propagateTo

      public TelemetryConfig propagateTo(String host)

      Sends the W3C trace context to requests for this host as well.

      By default the context goes to the relay's host -- the app's own backend -- and, on every platform except the web, to every host. The web is the exception because traceparent is not a CORS-safelisted header: sending it to a server that does not allow it turns a working cross-origin request into a failed preflight. Name the hosts that do allow it here.

      Returns

      this configuration

    • propagateToAllHosts

      public TelemetryConfig propagateToAllHosts()

      Sends the trace context to every host, on every platform, the web included. For an app whose every request goes to servers that allow the header.

      Returns

      this configuration

    • requireAnalyticsConsent

      public TelemetryConfig requireAnalyticsConsent(boolean require)

      Records and propagates traces only while the user has granted ANALYTICS consent through com.codename1.analytics.Analytics, the same consent the analytics providers honour. Off by default: whether trace data needs consent is the app's decision, and depends on what it records and where it ships.

      With it on and no consent, requests are sent exactly as they would be without telemetry -- no span, and no traceparent header -- and spans already buffered are dropped rather than exported. Before the user answers, the analytics ConsentMode decides: OPT_IN (the default) means no.

      Returns

      this configuration