public final class TelemetryConfig

  1. Object
  2. TelemetryConfig

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"));

Nested types

enum TelemetryConfig.ModeHow spans leave the app.

Constructors

public TelemetryConfig()

Methods

public TelemetryConfig relay(String backendUrl)Sends spans through a Codename One backend’s relay.
public TelemetryConfig direct(String collectorUrl)Sends spans straight to an OTLP/HTTP collector.
public TelemetryConfig serviceName(String name)The service.name the app’s spans are reported under.
public TelemetryConfig header(String name, String value)A header sent with every direct export – the collector’s credential.
public TelemetryConfig relayToken(String token)The shared secret a backend’s relay may require (cn1.otel.relay.token).
public TelemetryConfig protobuf(boolean protobuf)Whether direct exports use binary protobuf (the default) or JSON.
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.
public TelemetryConfig batchSize(int size)How many ended spans are buffered before an export.
public TelemetryConfig flushIntervalMillis(int millis)How often buffered spans are exported even when the batch is not full.
public TelemetryConfig propagateTo(String host)Sends the W3C trace context to requests for this host as well.
public TelemetryConfig propagateToAllHosts()Sends the trace context to every host, on every platform, the web included.
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.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Constructor details

TelemetryConfig

public TelemetryConfig()

Method details

relay

public TelemetryConfig relay(String backendUrl)
Sends spans through a Codename One backend’s relay.

Parameters

backendUrl String
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 String
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