Class Tracing

java.lang.Object
com.codename1.backend.Tracing
public final class Tracing extends Object

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(String, Tracing.Work) 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 Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Tracing.Work
    What inSpan(String, Tracing.Work) runs.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    checkHeaderLines(List lines)
    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.
    static Span
    current()
    The span of the work this thread is doing: the request's, inside a handler.
    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.
    static Tracer
    getTracer()
    The installed tracer, or null.
    static Object
    inSpan(String name, Tracing.Work work)
    Runs work inside a new span that is a child of the current one, and is current itself while it runs.
    static void
    install(Tracer installed)
    Installs the tracer every hook reports to, replacing any earlier one.
    static boolean
    isEnabled()
    Whether a tracer is installed.
    static boolean
    isSuppressed()
    Whether setSuppressed(boolean) is in force on this thread.
    static void
    route(String template)
    Names the current server span after the route that matched.
    static void
    setSuppressed(boolean suppressed)
    Turns span creation off, or back on, for the calling thread.
    static Span
    startSpan(String name)
    A new child of the current span that is NOT made current, for work whose start and end are in different places.

    Methods inherited from class Object

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

  • 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(Config).

      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)
      A new child of the current span that is NOT made current, for work whose start and end are in different places. The caller must end it.

    • 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 - "Name: value" strings
      Throws:
      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(boolean) 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.