Package org.keycloak.tracing

Interface TracingProvider

All Superinterfaces:

Provider

All Known Implementing Classes:

NoopTracingProvider

public interface TracingProvider
extends Provider

Method Summary

Modifier and Type	Method	Description
void	endSpan()	Marks the end of the current Span execution.
void	error(Throwable exception)	Records information about the Throwable to the Span, and set Span status to StatusCode.ERROR
io.opentelemetry.api.trace.Span	getCurrentSpan()	Returns the Span from the current Context, falling back to a default, no-op Span if there is no span in the current context.
default io.opentelemetry.api.trace.Tracer	getTracer(String name)	Gets or creates a named Tracer instance.
io.opentelemetry.api.trace.Tracer	getTracer(String name, String scopeVersion)	Gets or creates a named Tracer instance.
io.opentelemetry.api.trace.Span	startSpan(io.opentelemetry.api.trace.SpanBuilder builder)	Same as startSpan(String, String), but the Span is created from your own SpanBuilder instance.
default io.opentelemetry.api.trace.Span	startSpan(Class<?> tracerClass, String spanSuffix)	Same as startSpan(String, String), but you can start a Span that defines specific format for span name.
io.opentelemetry.api.trace.Span	startSpan(String tracerName, String spanName)	Gets or creates a tracer instance, and starts a new Span.
default void	trace(Class<?> tracerClass, String spanSuffix, Consumer<io.opentelemetry.api.trace.Span> execution)	Wrapper for code block execution which is traced and no need to manage the span lifecycle on our own.
default <T> T	trace(Class<?> tracerClass, String spanSuffix, Function<io.opentelemetry.api.trace.Span,T> execution)	Wrapper for code block execution that returns a value, is traced and no need to manage the span lifecycle on our own.
void	trace(String tracerName, String spanName, Consumer<io.opentelemetry.api.trace.Span> execution)	Wrapper for code block execution which is traced and no need to manage the span lifecycle on our own.
<T> T	trace(String tracerName, String spanName, Function<io.opentelemetry.api.trace.Span,T> execution)	Wrapper for code block execution which is traced and no need to manage the span lifecycle on our own.
boolean	validateAllSpansEnded()	Validates whether all started Span instances were ended.

Methods inherited from interface org.keycloak.provider.Provider

close

Method Details

getCurrentSpan

io.opentelemetry.api.trace.Span getCurrentSpan()

Returns the Span from the current Context, falling back to a default, no-op Span if there is no span in the current context.

startSpan

io.opentelemetry.api.trace.Span startSpan(String tracerName,
 String spanName)

Gets or creates a tracer instance, and starts a new Span.

Span.end() must be manually called to end this Span, or use trace(String, String, Consumer) that handles it all

Example of usage:

 class MyClass {
   private final TracingProvider tracing;

   MyClass(KeycloakSession session) {
     tracing = session.getProvider(TracingProvider.class);
   }

   void doWork() {
     tracing.startSpan("MyTracerName", "mySpanName");
     try {
       doSomeWork();
     } finally {
       // To make sure we end the span even in case of an exception.
       tracing.endSpan();  // Manually end the span.
     }
   }
 }
 

Parameters:

tracerName - name of Tracer that is obtained

spanName - name of Span that is used

Returns:

the newly created Span.

startSpan

default io.opentelemetry.api.trace.Span startSpan(Class<?> tracerClass,
 String spanSuffix)

Same as startSpan(String, String), but you can start a Span that defines specific format for span name. The final Span name consists of Class.getSimpleName(), and spanSuffix.

Note: The preferred trace approach is to use trace() methods, such as trace(Class, String, Consumer).

that controls the overall span lifecycle.

Example of usage:

tracing.startSpan(MyClass.name, "span")

The result Span name will be "MyClass.span"

Parameters:

tracerClass - class that is used for getting tracer instance and its name used as prefix for Span

spanSuffix - suffix that is appended to the final Span name

Returns:

the newly created Span.

startSpan

io.opentelemetry.api.trace.Span startSpan(io.opentelemetry.api.trace.SpanBuilder builder)

Same as startSpan(String, String), but the Span is created from your own SpanBuilder instance.

Note: The preferred trace approach is to use trace() methods, such as trace(Class, String, Consumer) that controls the overall span lifecycle.

Example of usage:

tracing.startSpan(tracer.spanBuilder("mySpan"))

Parameters:

builder - the custom SpanBuilder

Returns:

the newly created Span.

endSpan

void endSpan()

Marks the end of the current Span execution.

Note: The preferred trace approach is to use trace() methods, such as trace(Class, String, Consumer) that controls the overall span lifecycle. In that case you should not use this method with trace() methods.

error

void error(Throwable exception)

Records information about the Throwable to the Span, and set Span status to StatusCode.ERROR

Parameters:

exception - the Throwable to record.

trace

void trace(String tracerName,
 String spanName,
 Consumer<io.opentelemetry.api.trace.Span> execution)

Wrapper for code block execution which is traced and no need to manage the span lifecycle on our own.

Example of usage:

 class MyClass {
   private final TracingProvider tracing;

   MyClass(KeycloakSession session) {
     tracing = session.getProvider(TracingProvider.class);
   }

   void doWork() {
     tracing.trace("MyTracerName", "mySpanName", span -> {
         doSomeWork();
     });
   }
 }
 

Parameters:

tracerName - name of Tracer

spanName - name of Span

execution - code that is executed and traced

trace

default void trace(Class<?> tracerClass,
 String spanSuffix,
 Consumer<io.opentelemetry.api.trace.Span> execution)

Wrapper for code block execution which is traced and no need to manage the span lifecycle on our own. Same as trace(String, String, Consumer), but should be more usable.

Example of usage:

   void doWork() {
     // creates span name 'MyClass.mySpanName'
     tracing.trace(MyClass.name, "mySpanName", span -> {
         doSomeWork();
     });
   }
 

Parameters:

tracerClass - class that is used for getting tracer instance and its name used as prefix for Span

spanSuffix - suffix that is appended to the final Span name

execution - code that is executed and traced

trace

<T> T trace(String tracerName,
 String spanName,
 Function<io.opentelemetry.api.trace.Span,T> execution)

Wrapper for code block execution which is traced and no need to manage the span lifecycle on our own.

Example of usage:

 class MyClass {
   private final TracingProvider tracing;

   MyClass(KeycloakSession session) {
     tracing = session.getProvider(TracingProvider.class);
   }

   String doWork() {
     return tracing.trace("MyTracerName", "mySpanName", span -> {
         return returnSomeString();
     });
   }
 }
 

Parameters:

tracerName - name of Tracer

spanName - name of Span

execution - code that is executed and traced that returns a value

trace

default <T> T trace(Class<?> tracerClass,
 String spanSuffix,
 Function<io.opentelemetry.api.trace.Span,T> execution)

Wrapper for code block execution that returns a value, is traced and no need to manage the span lifecycle on our own. Same as trace(String, String, Function), but should be more usable.

Example of usage:

   String doWork() {
     // creates span name 'MyClass.mySpanName'
     return tracing.trace(MyClass.name, "mySpanName", span -> {
         return returnSomeString();
     });
   }
 

Parameters:

tracerClass - class that is used for getting tracer instance and its name used as prefix for Span

spanSuffix - suffix that is appended to the final Span name

execution - code that is executed and traced

getTracer

io.opentelemetry.api.trace.Tracer getTracer(String name,
 String scopeVersion)

Gets or creates a named Tracer instance.

Parameters:

name - name of the tracer

scopeVersion - version of the instrumentation scope.

getTracer

default io.opentelemetry.api.trace.Tracer getTracer(String name)

Gets or creates a named Tracer instance. Default scope version is Keycloak version (f.e. 26.0.5)

Parameters:

name - name of the tracer

validateAllSpansEnded

boolean validateAllSpansEnded()

Validates whether all started Span instances were ended.

As part of the validation, some notification about not ended Spans should be shown.

Returns:

true if all Spans ended