Interface Tracer
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Deprecated.static final String
Deprecated.useextractContext(Function)
andinjectContext(BiConsumer, Context)
for context propagation.static final String
Key forContext
which disables tracing for the request associated with the current context.static final String
Key forContext
which indicates that the context contains an entity path.static final String
Key forContext
which indicates that the context contains the hostname.static final String
Deprecated.UseStartSpanOptions.addLink(TracingLink)
and pass enqueued time as an attribute on link.static final String
Deprecated.Deprecated in favor of PARENT_TRACE_CONTEXT_KEY, use it to propagate full io.opentelemetry.Contextstatic final String
Context
key to store trace context.static final String
Deprecated.usemakeSpanCurrent(Context)
instead.static final String
Deprecated.useStartSpanOptions.addLink(TracingLink)
insteadstatic final String
Key forContext
which indicates that the context contains a message span context.static final String
Deprecated.please pass span name to Tracer.start methods. -
Method Summary
Modifier and TypeMethodDescriptiondefault void
Deprecated.default void
Adds an event to the span present in theContext
with the providedtimestamp
andattributes
.default void
Deprecated.default void
Deprecated.set specific attribute e.g.void
Completes the current tracing span for AMQP calls.default Context
extractContext
(String diagnosticId, Context context) Deprecated.default Context
extractContext
(Function<String, String> headerGetter) Extracts the span's context asContext
from upstream.default Context
getSharedSpanBuilder
(String spanName, Context context) Deprecated.useStartSpanOptions.addLink(TracingLink)
insteaddefault void
injectContext
(BiConsumer<String, String> headerSetter, Context context) Injects tracing context.default boolean
Checks if tracer is enabled.default AutoCloseable
makeSpanCurrent
(Context context) Makes span current.default void
setAttribute
(String key, long value, Context context) Sets long attribute.void
setAttribute
(String key, String value, Context context) Adds metadata to the current span.default Context
setSpanName
(String spanName, Context context) Deprecated.not needed.Creates a new tracing span.default Context
start
(String spanName, Context context, ProcessKind processKind) Deprecated.usestart(String, StartSpanOptions, Context)
instead.default Context
start
(String methodName, StartSpanOptions options, Context context) Creates a new tracing span.
-
Field Details
-
PARENT_SPAN_KEY
Deprecated.Deprecated in favor of PARENT_TRACE_CONTEXT_KEY, use it to propagate full io.opentelemetry.ContextKey forContext
which indicates that the context contains parent span data. This span will be used as the parent span for all spans the SDK creates.If no span data is listed when the span is created it will default to using this span key as the parent span.
- See Also:
-
PARENT_TRACE_CONTEXT_KEY
Context
key to store trace context. This context will be used as a parent context for new spans and propagated in outgoing HTTP calls.- See Also:
-
USER_SPAN_NAME_KEY
Deprecated.please pass span name to Tracer.start methods.Key forContext
which indicates that the context contains the name for the user spans that are created.If no span name is listed when the span is created it will default to using the calling method's name.
- See Also:
-
ENTITY_PATH_KEY
Key forContext
which indicates that the context contains an entity path.- See Also:
-
HOST_NAME_KEY
Key forContext
which indicates that the context contains the hostname.- See Also:
-
SPAN_CONTEXT_KEY
Key forContext
which indicates that the context contains a message span context.- See Also:
-
DIAGNOSTIC_ID_KEY
Deprecated.useextractContext(Function)
andinjectContext(BiConsumer, Context)
for context propagation.Key forContext
which indicates that the context contains a "Diagnostic Id" for the service call.- See Also:
-
SCOPE_KEY
Deprecated.usemakeSpanCurrent(Context)
instead.Key forContext
the scope of code where the given Span is in the current Context.- See Also:
-
AZ_TRACING_NAMESPACE_KEY
Deprecated.Pass Azure Resource Provider Namespace to Tracer factory methodTracerProvider.createTracer(String, String, String, TracingOptions)
Key forContext
which indicates that the context contains the Azure resource provider namespace.- See Also:
-
SPAN_BUILDER_KEY
Deprecated.useStartSpanOptions.addLink(TracingLink)
insteadKey forContext
which indicates the shared span builder that is in the current Context.- See Also:
-
MESSAGE_ENQUEUED_TIME
Deprecated.UseStartSpanOptions.addLink(TracingLink)
and pass enqueued time as an attribute on link.Key forContext
which indicates the time of the last enqueued message in the partition's stream.- See Also:
-
DISABLE_TRACING_KEY
Key forContext
which disables tracing for the request associated with the current context.- See Also:
-
-
Method Details
-
start
Creates a new tracing span.The
context
will be checked for information about a parent span. If a parent span is found, the new span will be added as a child. Otherwise, the parent span will be created and added to thecontext
and any downstreamstart()
calls will use the created span as the parent.Code samples
Starts a tracing span with provided method name and explicit parent span
// start a new tracing span with given name and parent context implicitly propagated // in io.opentelemetry.context.Context.current() Throwable throwable = null; Context span = tracer.start("keyvault.setsecret", Context.NONE); try { doWork(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(null, throwable, span); }
- Parameters:
methodName
- Name of the method triggering the span creation.context
- Additional metadata that is passed through the call stack.- Returns:
- The updated
Context
object containing the returned span. - Throws:
NullPointerException
- ifmethodName
orcontext
isnull
.
-
start
Creates a new tracing span.The
context
will be checked for information about a parent span. If a parent span is found, the new span will be added as a child. Otherwise, the parent span will be created and added to thecontext
and any downstreamstart()
calls will use the created span as the parent.Code samples
Starts a tracing span with provided method name and explicit parent span
// start a new CLIENT tracing span with the given start options and explicit parent context StartSpanOptions options = new StartSpanOptions(SpanKind.CLIENT) .setAttribute("key", "value"); Context spanFromOptions = tracer.start("keyvault.setsecret", options, Context.NONE); try { doWork(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(null, throwable, spanFromOptions); }
- Parameters:
methodName
- Name of the method triggering the span creation.options
- span creation options.context
- Additional metadata that is passed through the call stack.- Returns:
- The updated
Context
object containing the returned span. - Throws:
NullPointerException
- ifoptions
orcontext
isnull
.
-
start
Deprecated.usestart(String, StartSpanOptions, Context)
instead.Creates a new tracing span for AMQP calls.The
context
will be checked for information about a parent span. If a parent span is found, the new span will be added as a child. Otherwise, the parent span will be created and added to thecontext
and any downstreamstart()
calls will use the created span as the parent.Sets additional request attributes on the created span when
processKind
isProcessKind.SEND
.Returns the diagnostic Id and span context of the returned span when
processKind
isProcessKind.MESSAGE
.Creates a new tracing span with remote parent and returns that scope when the given when
processKind
isProcessKind.PROCESS
.Code samples
Starts a tracing span with provided method name and AMQP operation SEND
- Parameters:
spanName
- Name of the method triggering the span creation.context
- Additional metadata that is passed through the call stack.processKind
- AMQP operation kind.- Returns:
- The updated
Context
object containing the returned span. - Throws:
NullPointerException
- ifmethodName
orcontext
orprocessKind
isnull
.
-
end
Deprecated.set specific attribute e.g. http_status_code explicitly and useend(String, Throwable, Context)
.Completes the current tracing span.Code samples
Completes the tracing span present in the context, with the corresponding OpenTelemetry status for the given response status code
- Parameters:
responseCode
- Response status code if the span is in an HTTP call context.error
-Throwable
that happened during the span ornull
if no exception occurred.context
- Additional metadata that is passed through the call stack.- Throws:
NullPointerException
- ifcontext
isnull
.
-
end
Completes the current tracing span for AMQP calls.Code samples
Completes the tracing span with unset status
Context messageSpan = tracer.start("ServiceBus.message", new StartSpanOptions(SpanKind.PRODUCER), Context.NONE); tracer.end(null, null, messageSpan);
Completes the tracing span with provided error message
Context span = tracer.start("ServiceBus.send", new StartSpanOptions(SpanKind.CLIENT), Context.NONE); tracer.end("amqp:not-found", null, span);
Completes the tracing span with provided exception
Context sendSpan = tracer.start("ServiceBus.send", new StartSpanOptions(SpanKind.CLIENT), Context.NONE); try (AutoCloseable scope = tracer.makeSpanCurrent(sendSpan)) { doWork(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(null, throwable, sendSpan); }
- Parameters:
errorMessage
- The error message that occurred during the call, ornull
if no error occurred.throwable
-Throwable
that happened during the span ornull
if no exception occurred.context
- Additional metadata that is passed through the call stack.- Throws:
NullPointerException
- ifcontext
isnull
.
-
setAttribute
Adds metadata to the current span. If no span information is found in the context, then no metadata is added.span = tracer.start("EventHubs.process", Context.NONE); tracer.setAttribute("bar", "baz", span);
- Parameters:
key
- Name of the metadata.value
- Value of the metadata.context
- Additional metadata that is passed through the call stack.- Throws:
NullPointerException
- ifkey
orvalue
orcontext
isnull
.
-
setAttribute
Sets long attribute.Context span = tracer.start("EventHubs.process", Context.NONE); tracer.setAttribute("foo", 42, span);
- Parameters:
key
- attribute namevalue
- atteribute valuecontext
- tracing context
-
setSpanName
Deprecated.not needed.Sets the name for spans that are created.Code samples
Retrieve the span name of the returned span
- Parameters:
spanName
- Name to give the next span.context
- Additional metadata that is passed through the call stack.- Returns:
- The updated
Context
object containing the name of the returned span. - Throws:
NullPointerException
- ifspanName
orcontext
isnull
.
-
addLink
Deprecated.Provides a way to link multiple tracing spans. Used in batching operations to relate multiple requests under a single batch.Code samples
Link multiple spans using their span context information
- Parameters:
context
- Additional metadata that is passed through the call stack.- Throws:
NullPointerException
- ifcontext
isnull
.
-
extractContext
Deprecated.Extracts the span's context asContext
from upstream.Code samples
Extracts the corresponding span context information from a valid diagnostic id
- Parameters:
diagnosticId
- Unique identifier for the trace information of the span.context
- Additional metadata that is passed through the call stack.- Returns:
- The updated
Context
object containing the span context. - Throws:
NullPointerException
- ifdiagnosticId
orcontext
isnull
.
-
extractContext
Extracts the span's context asContext
from upstream.Code samples
Extracts the corresponding span context information from a valid diagnostic id
Context parentContext = tracer.extractContext(name -> { Object value = messageProperties.get(name); return value instanceof String ? (String) value : null; }); StartSpanOptions remoteParentOptions = new StartSpanOptions(SpanKind.CONSUMER) .setRemoteParent(parentContext); Context spanWithRemoteParent = tracer.start("EventHubs.process", remoteParentOptions, Context.NONE); try (AutoCloseable scope = tracer.makeSpanCurrent(spanWithRemoteParent)) { doWork(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(null, throwable, spanWithRemoteParent); }
- Parameters:
headerGetter
- Unique identifier for the trace information of the span and todo.- Returns:
- The updated
Context
object containing the span context. - Throws:
NullPointerException
- ifdiagnosticId
orcontext
isnull
.
-
injectContext
Injects tracing context.Context httpSpan = tracer.start("HTTP GET", new StartSpanOptions(SpanKind.CLIENT), methodSpan); tracer.injectContext((headerName, headerValue) -> request.setHeader(headerName, headerValue), httpSpan); try (AutoCloseable scope = tracer.makeSpanCurrent(httpSpan)) { HttpResponse response = getResponse(request); httpResponseCode = response.getStatusCode(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(httpResponseCode, throwable, httpSpan); }
- Parameters:
headerSetter
- callback to set context with.context
- trace context instance
-
addEvent
@Deprecated default void addEvent(String name, Map<String, Object> attributes, OffsetDateTime timestamp) Deprecated.Adds an event to the current span with the providedtimestamp
andattributes
.This API does not provide any normalization if provided timestamps are out of range of the current span timeline
Supported attribute values include String, double, boolean, long, String [], double [], long []. Any other Object value type and null values will be silently ignored.
- Parameters:
name
- the name of the event.attributes
- the additional attributes to be set for the event.timestamp
- The instant, in UTC, at which the event will be associated to the span.- Throws:
NullPointerException
- ifeventName
isnull
.
-
addEvent
default void addEvent(String name, Map<String, Object> attributes, OffsetDateTime timestamp, Context context) Adds an event to the span present in theContext
with the providedtimestamp
andattributes
.This API does not provide any normalization if provided timestamps are out of range of the current span timeline
Supported attribute values include String, double, boolean, long, String [], double [], long []. Any other Object value type and null values will be silently ignored.
Context span = tracer.start("Cosmos.getItem", Context.NONE); tracer.addEvent("trying another endpoint", Collections.singletonMap("endpoint", "westus3"), OffsetDateTime.now(), span);
- Parameters:
name
- the name of the event.attributes
- the additional attributes to be set for the event.timestamp
- The instant, in UTC, at which the event will be associated to the span.context
- the call metadata containing information of the span to which the event should be associated with.- Throws:
NullPointerException
- ifeventName
isnull
.
-
makeSpanCurrent
Makes span current. Implementations may put it on ThreadLocal. Make sure to always use try-with-resource statement with makeSpanCurrent- Parameters:
context
- Context with span.Context span = tracer.start("EventHubs.process", new StartSpanOptions(SpanKind.CONSUMER), Context.NONE); try (AutoCloseable scope = tracer.makeSpanCurrent(span)) { doWork(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(null, throwable, span); }
- Returns:
- Closeable that should be closed in the same thread with try-with-resource statement.
-
isEnabled
default boolean isEnabled()Checks if tracer is enabled.if (!tracer.isEnabled()) { doWork(); } else { Context span = tracer.start("span", Context.NONE); try { doWork(); } catch (Throwable ex) { throwable = ex; } finally { tracer.end(null, throwable, span); } }
- Returns:
- true if tracer is enabled, false otherwise.
-
TracerProvider.createTracer(String, String, String, TracingOptions)