com.azure.core.util.tracing

Interface Tracer

public interface Tracer

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

See Also:

TracerProxy

Field Summary

Fields

Modifier and Type	Field and Description
static String	AZ_TRACING_NAMESPACE_KEY Key for Context which indicates that the context contains the Azure resource provider namespace.
static String	DIAGNOSTIC_ID_KEY Key for Context which indicates that the context contains a "Diagnostic Id" for the service call.
static String	ENTITY_PATH_KEY Key for Context which indicates that the context contains an entity path.
static String	HOST_NAME_KEY Key for Context which indicates that the context contains the hostname.
static String	MESSAGE_ENQUEUED_TIME Key for Context which indicates the the time of the last enqueued message in the partition's stream.
static String	PARENT_SPAN_KEY Key for Context which indicates that the context contains parent span data.
static String	SCOPE_KEY Key for Context the scope of code where the given Span is in the current Context.
static String	SPAN_BUILDER_KEY Key for Context which indicates the shared span builder that is in the current Context.
static String	SPAN_CONTEXT_KEY Key for Context which indicates that the context contains a message span context.
static String	USER_SPAN_NAME_KEY 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
void	addLink(Context context) Provides a way to link multiple tracing spans.
void	end(int responseCode, Throwable error, Context context) Completes the current tracing span.
void	end(String statusMessage, Throwable error, Context context) Completes the current tracing span for AMQP calls.
Context	extractContext(String diagnosticId, Context context) Extracts the span's context as Context from upstream.
default Context	getSharedSpanBuilder(String spanName, Context context) Returns a span builder with the provided name in Context.
void	setAttribute(String key, String value, Context context) Adds metadata to the current span.
Context	setSpanName(String spanName, Context context) Sets the name for spans that are created.
Context	start(String methodName, Context context) Creates a new tracing span.
Context	start(String methodName, Context context, ProcessKind processKind) Creates a new tracing span for AMQP calls.

Field Detail

PARENT_SPAN_KEY

static final String PARENT_SPAN_KEY

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 SDK creates its first span, this span key will be used as the parent span.

See Also:

Constant Field Values

USER_SPAN_NAME_KEY

static final String USER_SPAN_NAME_KEY

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.

See Also:

Constant Field Values

ENTITY_PATH_KEY

static final String ENTITY_PATH_KEY

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

See Also:

Constant Field Values

HOST_NAME_KEY

static final String HOST_NAME_KEY

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

See Also:

Constant Field Values

SPAN_CONTEXT_KEY

static final String SPAN_CONTEXT_KEY

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

See Also:

Constant Field Values

DIAGNOSTIC_ID_KEY

static final String DIAGNOSTIC_ID_KEY

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

See Also:

Constant Field Values

SCOPE_KEY

static final String SCOPE_KEY

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

See Also:

Constant Field Values

AZ_TRACING_NAMESPACE_KEY

static final String AZ_TRACING_NAMESPACE_KEY

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

See Also:

Constant Field Values

SPAN_BUILDER_KEY

static final String SPAN_BUILDER_KEY

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

See Also:

Constant Field Values

MESSAGE_ENQUEUED_TIME

static final String MESSAGE_ENQUEUED_TIME

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

See Also:

Constant Field Values

Method Detail

start

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

 // pass the current tracing span context to the calling method
 Context traceContext = new Context(PARENT_SPAN_KEY, "<user-current-span>");
 // start a new tracing span with the given method name and explicit parent span
 Context updatedContext = tracer.start("azure.keyvault.secrets/setsecret", traceContext);
 System.out.printf("Span returned in the context object: %s%n",
     updatedContext.getData(PARENT_SPAN_KEY).get());
 

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 - if methodName or context is null.

start

Context start(String methodName,
              Context context,
              ProcessKind processKind)

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 the context and any downstream start() calls will use the created span as the parent.

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

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

Creates a new tracing span with remote parent and returns that scope when the given when processKind is ProcessKind.PROCESS.

Code samples

Starts a tracing span with provided method name and AMQP operation SEND

 // pass the current tracing span and request metadata to the calling method
 Context sendContext = new Context(PARENT_SPAN_KEY, "<user-current-span>")
     .addData(ENTITY_PATH_KEY, "entity-path").addData(HOST_NAME_KEY, "hostname");
 
 // start a new tracing span with explicit parent, sets the request attributes on the span and sets the span
 // kind to client when process kind SEND
 Context updatedSendContext = tracer.start("azure.eventhubs.send", sendContext, ProcessKind.SEND);
 System.out.printf("Span returned in the context object: %s%n",
     updatedSendContext.getData(PARENT_SPAN_KEY).get());
 

Starts a tracing span with provided method name and AMQP operation MESSAGE

 String diagnosticIdKey = "diagnostic-id";
 // start a new tracing span with explicit parent, sets the diagnostic Id (traceparent headers) on the current
 // context when process kind MESSAGE
 Context updatedReceiveContext = tracer.start("azure.eventhubs.receive", traceContext,
     ProcessKind.MESSAGE);
 System.out.printf("Diagnostic Id: %s%n", updatedReceiveContext.getData(diagnosticIdKey).get().toString());
 

Starts a tracing span with provided method name and AMQP operation PROCESS

 String spanImplContext = "span-context";
 // start a new tracing span with remote parent and uses the span in the current context to return a scope
 // when process kind PROCESS
 Context processContext = new Context(PARENT_SPAN_KEY, "<user-current-span>")
     .addData(spanImplContext, "<user-current-span-context>");
 Context updatedProcessContext = tracer.start("azure.eventhubs.process", processContext,
     ProcessKind.PROCESS);
 System.out.printf("Scope: %s%n", updatedProcessContext.getData("scope").get());
 

Parameters:

methodName - 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 - if methodName or context or processKind is null.

end

void end(int responseCode,
         Throwable error,
         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

 // context containing the current tracing span to end
 String openTelemetrySpanKey = "openTelemetry-span";
 Context traceContext = new Context(PARENT_SPAN_KEY, "<user-current-span>");
 
 // completes the tracing span with the passed response status code
 tracer.end(200, null, traceContext);
 

Parameters:

responseCode - Response status code if the span is in a 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.

Throws:

NullPointerException - if context is null.

end

void end(String statusMessage,
         Throwable error,
         Context context)

Completes the current tracing span for AMQP calls.

Code samples

Completes the tracing span with the corresponding OpenTelemetry status for the given status message

 // context containing the current tracing span to end
 // completes the tracing span with the passed status message
 tracer.end("success", null, traceContext);
 

Parameters:

statusMessage - The error or success message that occurred during the call, or null if no error occurred.

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

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

Throws:

NullPointerException - if context is null.

setAttribute

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.

Parameters:

key - Name of the metadata.

value - Value of the metadata.

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

Throws:

NullPointerException - if key or value or context is null.

setSpanName

Context setSpanName(String spanName,
                    Context context)

Sets the name for spans that are created.

Code samples

Retrieve the span name of the returned span

 // Sets the span name of the returned span on the context object, with key PARENT_SPAN_KEY
 String openTelemetrySpanKey = "openTelemetry-span";
 Context context = tracer.setSpanName("test-span-method", Context.NONE);
 System.out.printf("Span name: %s%n", context.getData(PARENT_SPAN_KEY).get().toString());
 

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 - if spanName or context is null.

addLink

void addLink(Context context)

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

 // use the parent context containing the current tracing span to start a child span
 Context parentContext = new Context(PARENT_SPAN_KEY, "<user-current-span>");
 // use the returned span context information of the current tracing span to link
 Context spanContext = tracer.start("test.method", parentContext, ProcessKind.MESSAGE);
 
 // Adds a link between multiple span's using the span context information of the Span
 // For each event processed, add a link with the created spanContext
 tracer.addLink(spanContext);
 

Parameters:

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

Throws:

NullPointerException - if context is null.

extractContext

Context extractContext(String diagnosticId,
                       Context context)

Extracts the span's context as Context from upstream.

Code samples

Extracts the corresponding span context information from a valid diagnostic id

 // Extracts the span context information from the passed diagnostic Id that can be used for linking spans.
 String spanImplContext = "span-context";
 Context spanContext = tracer.extractContext("valid-diagnostic-id", Context.NONE);
 System.out.printf("Span context of the current tracing span: %s%n", spanContext.getData(spanImplContext).get());
 

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 - if diagnosticId or context is null.

getSharedSpanBuilder

default Context getSharedSpanBuilder(String spanName,
                                     Context context)

Returns a span builder with the provided name in Context.

Code samples

Returns a builder with the provided span name.

 // Returns a span builder with the provided name
 String methodName = "message-span";
 Context spanContext = tracer.getSharedSpanBuilder(methodName, Context.NONE);
 System.out.printf("Span context of the current tracing span: %s%n", spanContext.getData(SPAN_BUILDER_KEY).get());
 

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.

Throws:

NullPointerException - if context or spanName is null.