Backend API. Server-side code: this runs in a Codename One backend, not in the app on the device.

public final class Tracing

Object
Tracing

Distributed tracing for the server, and the hooks it is instrumented through.

Nothing here does anything until a Tracer is installed. The build installs one when a project asks for it – @OpenTelemetry on any class, or cn1.otel.enabled=true in application.properties – and from then on every request, outbound Web call and Database statement is a span, W3C trace context travels on every outbound request, and an incoming traceparent makes the request part of the caller’s trace. No code in the application changes for any of that.

What an application may still want is here: current() to decorate the request’s span, and inSpan to time a block of its own work.

THE CURRENT SPAN IS PER THREAD, and that is per REQUEST here: a virtual thread serves one request at a time and ThreadLocal is per virtual thread (see the measurement recorded beside HttpServer.SERVING_FD). The server sets it before the handler runs and clears it in the same finally that ends the request, because the next request on a kept-alive connection runs on the same thread and must not inherit it.

Every hook is guarded: a tracer that throws is reported once and the request goes on untraced, because a monitoring fault must never become an outage.

Nested types

interface Tracing.Work What inSpan runs.

Methods

`public static void install(Tracer installed)`	Installs the tracer every hook reports to, replacing any earlier one.
`public static` `Tracer getTracer()`	The installed tracer, or null.
`public static boolean isEnabled()`	Whether a tracer is installed.
`public static` `Span current()`	The span of the work this thread is doing: the request’s, inside a handler.
`public static` `String currentTraceparent()`	The current trace as a W3C `traceparent` value, for a transport the server does not instrument itself – a message queue, a raw socket.
`public static` `Object inSpan(String name, Tracing.Work work) throws Exception`	Runs `work` inside a new span that is a child of the current one, and is current itself while it runs.
`public static` `Span startSpan(String name)`
`public static void setSuppressed(boolean suppressed)`	Turns span creation off, or back on, for the calling thread.
`public static void checkHeaderLines(List lines) throws IOException`	Applies the rules `Web` enforces on request header lines to lines an exporter will send, so a tracer can refuse a bad configuration when it is opened.
`public static boolean isSuppressed()`	Whether `setSuppressed` is in force on this thread.
`public static void route(String template)`	Names the current server span after the route that matched.

Inherited methods

From Object

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

Method details

install

public static void install(Tracer installed)

Installs the tracer every hook reports to, replacing any earlier one. Pass null to turn tracing off. The builder does this itself; a program that starts HttpServer or LambdaRuntime directly calls it after Tracer.open.

A tracer this replaces is shut down: its spans so far are exported, for up to REPLACED_SHUTDOWN_MILLIS, and its exporter stops. Nothing else holds it once it is out of this slot, so leaving it running leaked its export thread and queues on every reconfiguration.

getTracer

public static Tracer getTracer()

The installed tracer, or null.

isEnabled

public static boolean isEnabled()

Whether a tracer is installed.

current

public static Span current()

The span of the work this thread is doing: the request’s, inside a handler. Never null – with no tracer, or outside a request, it is a no-op span.

currentTraceparent

public static String currentTraceparent()

The current trace as a W3C traceparent value, for a transport the server does not instrument itself – a message queue, a raw socket. Null when there is no trace.

inSpan

public static Object inSpan(String name, Tracing.Work work)
throws Exception

Runs work inside a new span that is a child of the current one, and is current itself while it runs. An exception is recorded on the span and rethrown.

Throws

Exception

startSpan

public static Span startSpan(String name)

setSuppressed

public static void setSuppressed(boolean suppressed)

Turns span creation off, or back on, for the calling thread. The exporter uses it so its own requests to the collector are not traced – each export would otherwise produce a span, and exporting that one another.

checkHeaderLines

public static void checkHeaderLines(List lines)
throws IOException

Applies the rules Web enforces on request header lines to lines an exporter will send, so a tracer can refuse a bad configuration when it is opened. Otherwise the server starts, and every export then fails on the same check. One rule set, not a copy of it.

Parameters

lines List: "Name: value" strings

Throws

java.io.IOException: naming the first line that could not be sent; the message never quotes a value, since values carry credentials

isSuppressed

public static boolean isSuppressed()

Whether setSuppressed is in force on this thread.

route

public static void route(String template)

Names the current server span after the route that matched. Called by the generated routers, which are the only code that knows the TEMPLATE – the path alone would make every pet id its own operation.