Tracer Interface

Reference

Package:: com.azure.core.util.tracing

Maven Artifact:: com.azure:azure-core:1.48.0

public interface Tracer

Contract that all tracers must implement to be pluggable into the SDK.

Field Summary

Modifier and Type	Field and Description
static final String	AZ_TRACING_NAMESPACE_KEY Deprecated Pass Azure Resource Provider Namespace to Tracer factory method createTracer(String libraryName, String libraryVersion, String azNamespace, TracingOptions options) Key for Context which indicates that the context contains the Azure resource provider namespace.
static final String	DIAGNOSTIC_ID_KEY Deprecated use extractContext(Function<String,String> headerGetter) and injectContext(BiConsumer<String,String> headerSetter, Context context) for context propagation. Key for Context which indicates that the context contains a "Diagnostic Id" for the service call.
static final String	DISABLE_TRACING_KEY Key for Context which disables tracing for the request associated with the current context.
static final String	ENTITY_PATH_KEY Key for Context which indicates that the context contains an entity path.
static final String	HOST_NAME_KEY Key for Context which indicates that the context contains the hostname.
static final String	MESSAGE_ENQUEUED_TIME Deprecated Use addLink(TracingLink link) and pass enqueued time as an attribute on link. Key for Context which indicates the time of the last enqueued message in the partition's stream.
static final String	PARENT_SPAN_KEY Deprecated Deprecated in favor of PARENT_TRACE_CONTEXT_KEY, use it to propagate full io.opentelemetry.Context Key for Context which indicates that the context contains parent span data.
static final String	PARENT_TRACE_CONTEXT_KEY Context key to store trace context.
static final String	SCOPE_KEY Deprecated use makeSpanCurrent(Context context) instead. Key for Context the scope of code where the given Span is in the current Context.
static final String	SPAN_BUILDER_KEY Deprecated use addLink(TracingLink link) instead Key for Context which indicates the shared span builder that is in the current Context.
static final String	SPAN_CONTEXT_KEY Key for Context which indicates that the context contains a message span context.
static final String	USER_SPAN_NAME_KEY Deprecated please pass span name to Tracer.start methods. Key for Context which indicates that the context contains the name for the user spans that are created.

Method Summary

Modifier and Type	Method and Description
default void	addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp) Deprecated Use addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context) Adds an event to the current span with the provided `timestamp` and `attributes`.
default void	addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context) Adds an event to the span present in the `Context` with the provided `timestamp` and `attributes`.
default void	addLink(Context context) Deprecated use addLink(TracingLink link) )} Provides a way to link multiple tracing spans.
default void	end(int responseCode, Throwable error, Context context) Deprecated set specific attribute e.g. http_status_code explicitly and use end(String errorMessage, Throwable throwable, Context context). Completes the current tracing span.
abstract void	end(String errorMessage, Throwable throwable, Context context) Completes span on the context.
default Context	extractContext(String diagnosticId, Context context) Deprecated use extractContext(Function<String,String> headerGetter) Extracts the span's context as Context from upstream.
default Context	extractContext(Function<String,String> headerGetter) Extracts the span's context as Context from upstream.
default Context	getSharedSpanBuilder(String spanName, Context context) Deprecated use addLink(TracingLink link) instead Returns a span builder with the provided name in Context.
default void	injectContext(BiConsumer<String,String> headerSetter, Context context) Injects tracing context.
default boolean	isEnabled() Checks if tracer is enabled.
default boolean	isRecording(Context span) Checks if span is sampled in.
default AutoCloseable	makeSpanCurrent(Context context) Makes span current.
default void	setAttribute(String key, Object value, Context context) Sets an attribute on span.
abstract void	setAttribute(String key, String value, Context context) Adds metadata to the current span.
default void	setAttribute(String key, long value, Context context) Sets long attribute.
default Context	setSpanName(String spanName, Context context) Deprecated not needed. Sets the name for spans that are created.
abstract Context	start(String methodName, Context context) Creates a new tracing span.
default Context	start(String spanName, Context context, ProcessKind processKind) Deprecated use start(String methodName, StartSpanOptions options, Context context) instead. Creates a new tracing span for AMQP calls.
default Context	start(String methodName, StartSpanOptions options, Context context) Creates a new tracing span.

Field Details

AZ_TRACING_NAMESPACE_KEY

@Deprecated
public static final String AZ_TRACING_NAMESPACE_KEY

Deprecated

Pass Azure Resource Provider Namespace to Tracer factory method createTracer(String libraryName, String libraryVersion, String azNamespace, TracingOptions options)

Key for Context which indicates that the context contains the Azure resource provider namespace.

DIAGNOSTIC_ID_KEY

@Deprecated
public static final String DIAGNOSTIC_ID_KEY

Deprecated

use extractContext(Function<String,String> headerGetter) and injectContext(BiConsumer<String,String> headerSetter, Context context) for context propagation.

Key for Context which indicates that the context contains a "Diagnostic Id" for the service call.

DISABLE_TRACING_KEY

public static final String DISABLE_TRACING_KEY

Key for Context which disables tracing for the request associated with the current context.

ENTITY_PATH_KEY

public static final String ENTITY_PATH_KEY

Key for Context which indicates that the context contains an entity path.

HOST_NAME_KEY

public static final String HOST_NAME_KEY

Key for Context which indicates that the context contains the hostname.

MESSAGE_ENQUEUED_TIME

@Deprecated
public static final String MESSAGE_ENQUEUED_TIME

Deprecated

Use addLink(TracingLink link) and pass enqueued time as an attribute on link.

Key for Context which indicates the time of the last enqueued message in the partition's stream.

PARENT_SPAN_KEY

@Deprecated
public static final String PARENT_SPAN_KEY

Deprecated

Deprecated in favor of PARENT_TRACE_CONTEXT_KEY, use it to propagate full io.opentelemetry.Context

Key for Context 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.

PARENT_TRACE_CONTEXT_KEY

public static final String 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.

SCOPE_KEY

@Deprecated
public static final String SCOPE_KEY

Deprecated

use makeSpanCurrent(Context context) instead.

Key for Context the scope of code where the given Span is in the current Context.

SPAN_BUILDER_KEY

@Deprecated
public static final String SPAN_BUILDER_KEY

Deprecated

use addLink(TracingLink link) instead

Key for Context which indicates the shared span builder that is in the current Context.

SPAN_CONTEXT_KEY

public static final String SPAN_CONTEXT_KEY

Key for Context which indicates that the context contains a message span context.

USER_SPAN_NAME_KEY

@Deprecated
public static final String USER_SPAN_NAME_KEY

Deprecated

please pass span name to Tracer.start methods.

Key for Context 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.

Method Details

addEvent

@Deprecated
public default void addEvent(String name, Map attributes, OffsetDateTime timestamp)

Deprecated

Use addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context)

Adds an event to the current span with the provided timestamp and attributes.

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.

addEvent

public default void addEvent(String name, Map attributes, OffsetDateTime timestamp, Context context)

Adds an event to the span present in the Context with the provided timestamp and attributes.

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.

addLink

@Deprecated
public default void addLink(Context context)

Deprecated

use addLink(TracingLink link) )}

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.

end

@Deprecated
public default void end(int responseCode, Throwable error, Context context)

Deprecated

set specific attribute e.g. http_status_code explicitly and use end(String errorMessage, Throwable throwable, Context 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 or null if no exception occurred.

context - Additional metadata that is passed through the call stack.

end

public abstract void end(String errorMessage, Throwable throwable, Context context)

Completes span on the context.

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, or null if no error. occurred. Any other non-null string indicates an error with description provided in errorMessage.

throwable - Throwable that happened during the span or null if no exception occurred.

context - Additional metadata that is passed through the call stack.

extractContext

@Deprecated
public default Context extractContext(String diagnosticId, Context context)

Deprecated

use extractContext(Function<String,String> headerGetter)

Extracts the span's context as Context 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.

extractContext

public default Context extractContext(Function headerGetter)

Extracts the span's context as Context 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.

getSharedSpanBuilder

@Deprecated
public default Context getSharedSpanBuilder(String spanName, Context context)

Deprecated

use addLink(TracingLink link) instead

Returns a span builder with the provided name in Context.

Code samples

Returns a builder with the provided span name.

Parameters:

spanName - Name to give the span for the created builder.

context - Additional metadata that is passed through the call stack.

Returns:

The updated Context object containing the span builder.

injectContext

public default void injectContext(BiConsumer headerSetter, Context context)

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

isEnabled

public 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.

isRecording

public default boolean isRecording(Context span)

Checks if span is sampled in.

Parameters:

span - Span to check.

Returns:

true if span is recording, false otherwise.

makeSpanCurrent

public default AutoCloseable makeSpanCurrent(Context context)

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.

setAttribute

public default void setAttribute(String key, Object value, Context context)

Sets an attribute on span. Adding duplicate attributes, update, or removal is discouraged, since underlying implementations behavior can vary.

Parameters:

key - attribute key.

value - attribute value. Note that underlying tracer implementations limit supported value types. OpenTelemetry implementation supports following types:

String
int
double
boolean
long

context - context containing span to which attribute is added.

setAttribute

public abstract void setAttribute(String key, String value, Context context)

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.

setAttribute

public default void setAttribute(String key, long value, Context context)

Sets long attribute.

Context span = tracer.start("EventHubs.process", Context.NONE);
 tracer.setAttribute("foo", 42, span);

Parameters:

key - attribute name

value - atteribute value

context - tracing context

setSpanName

@Deprecated
public default Context setSpanName(String spanName, Context context)

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.

start

public abstract Context start(String methodName, Context context)

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 the context and any downstream start() 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.

start

@Deprecated
public default Context start(String spanName, Context context, ProcessKind processKind)

Deprecated

use start(String methodName, StartSpanOptions options, Context context) instead.

Creates a new tracing span for AMQP calls.

Sets additional request attributes on the created span when processKind is SEND.

Returns the diagnostic Id and span context of the returned span when processKind is MESSAGE.

Creates a new tracing span with remote parent and returns that scope when the given when processKind is 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.

start

public default Context start(String methodName, StartSpanOptions options, Context context)

Creates a new tracing span.

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.

Tracer Interface

Field Summary

Method Summary

Field Details

AZ_TRACING_NAMESPACE_KEY

DIAGNOSTIC_ID_KEY

DISABLE_TRACING_KEY

ENTITY_PATH_KEY

HOST_NAME_KEY

MESSAGE_ENQUEUED_TIME

PARENT_SPAN_KEY

PARENT_TRACE_CONTEXT_KEY

SCOPE_KEY

SPAN_BUILDER_KEY

SPAN_CONTEXT_KEY

USER_SPAN_NAME_KEY

Method Details

addEvent

addEvent

addLink

end

end

extractContext

extractContext

getSharedSpanBuilder

injectContext

isEnabled

isRecording

makeSpanCurrent

setAttribute

setAttribute

setAttribute

setSpanName

start

start

start

Applies to

Geri Bildirim

Ek kaynaklar