public final class Telemetry

Object
Telemetry

OpenTelemetry tracing for the app: every network request is a span, and carries W3C trace context to the server it reaches, so the app’s request and the backend’s handling of it are one trace.

Usually installed by the build rather than by hand – put @OpenTelemetry on the main class and the generated bootstrap calls install(TelemetryConfig) before the app starts:

@OpenTelemetry(relay = "https://api.example.com", serviceName = "shop-app")
public class ShopApp extends Lifecycle { ... }

Every ConnectionRequest is covered, which is every REST, gRPC-Web and GraphQL client the build generates. To group the requests a user action causes, time the action:

Telemetry.run("checkout", () -> cart.submit());

Spans are batched and exported with OTLP/HTTP – through the app’s own backend by default, which keeps the collector’s credentials out of the app (see TelemetryConfig).

Methods

`public static void install(TelemetryConfig config)`	Installs telemetry, replacing any earlier installation.
`public static void uninstall()`	Stops recording, exports what is buffered, and removes the network hook.
`public static boolean isInstalled()`	Whether telemetry is installed.
`public static` `TelemetrySpan startSpan(String name)`	A new span, a child of the current one.
`public static void run(String name, Runnable work)`	Runs `work` inside a new span, which is current while it runs: requests queued inside it become its children.
`public static` `TelemetrySpan getCurrentSpan()`	The span `run(String, Runnable)` made current on this thread, or null.
`public static void flush()`	Exports what is buffered now, rather than at the next interval.

Inherited methods

From Object

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

Method details

install

public static void install(TelemetryConfig config)

Installs telemetry, replacing any earlier installation.

Safe to call before Display.init, which is where the generated bootstrap calls it: nothing that needs the platform – not even the secure random source the ids come from – is touched until the first span.

Parameters

config TelemetryConfig: where and how to export; a configuration with no endpoint installs nothing

uninstall

public static void uninstall()

Stops recording, exports what is buffered, and removes the network hook.

isInstalled

public static boolean isInstalled()

Whether telemetry is installed.

startSpan

public static TelemetrySpan startSpan(String name)

A new span, a child of the current one. It is not made current; the caller must end it. Never null – with telemetry off it records nothing.

Parameters

name String: what the span times

run

public static void run(String name, Runnable work)

Runs work inside a new span, which is current while it runs: requests queued inside it become its children. A RuntimeException is recorded on the span and rethrown.

Parameters

name String: what the span times
work Runnable: the work

getCurrentSpan

public static TelemetrySpan getCurrentSpan()

The span run(String, Runnable) made current on this thread, or null.

flush

public static void flush()

Exports what is buffered now, rather than at the next interval. Call it when the app is paused: a span still in memory when the process is reclaimed is lost.