public interface Tracer
TracerProxy
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 |
DISABLE_TRACING_KEY
Key for
Context which disables tracing for the request associated with the current context. |
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 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. |
Modifier and Type | Method and Description |
---|---|
default void |
addEvent(String name,
Map<String,Object> attributes,
OffsetDateTime timestamp)
Deprecated.
|
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 . |
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 . |
default AutoCloseable |
makeSpanCurrent(Context context)
Makes span current.
|
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.
|
default Context |
start(String methodName,
StartSpanOptions options,
Context context)
Creates a new tracing span.
|
static final String PARENT_SPAN_KEY
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.
static final String USER_SPAN_NAME_KEY
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.
static final String ENTITY_PATH_KEY
Context
which indicates that the context contains an entity path.static final String HOST_NAME_KEY
Context
which indicates that the context contains the hostname.static final String SPAN_CONTEXT_KEY
Context
which indicates that the context contains a message span context.static final String DIAGNOSTIC_ID_KEY
Context
which indicates that the context contains a "Diagnostic Id" for the service call.static final String SCOPE_KEY
Context
the scope of code where the given Span is in the current Context.static final String AZ_TRACING_NAMESPACE_KEY
Context
which indicates that the context contains the Azure resource provider namespace.static final String SPAN_BUILDER_KEY
Context
which indicates the shared span builder that is in the current Context.static final String MESSAGE_ENQUEUED_TIME
Context
which indicates the time of the last enqueued message in the partition's stream.static final String DISABLE_TRACING_KEY
Context
which disables tracing for the request associated with the current context.Context start(String methodName, Context context)
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());
methodName
- Name of the method triggering the span creation.context
- Additional metadata that is passed through the call stack.Context
object containing the returned span.NullPointerException
- if methodName
or context
is null
.default Context start(String methodName, StartSpanOptions options, Context context)
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 CLIENT tracing span with the given start options and explicit parent span StartSpanOptions options = new StartSpanOptions(SpanKind.CLIENT) .setAttribute("key", "value"); Context updatedClientSpanContext = tracer.start("azure.keyvault.secrets/setsecret", options, traceContext); System.out.printf("Span returned in the context object: %s%n", updatedClientSpanContext.getData(PARENT_SPAN_KEY).get());
methodName
- Name of the method triggering the span creation.options
- span creation options.context
- Additional metadata that is passed through the call stack.Context
object containing the returned span.NullPointerException
- if options
or context
is null
.Context start(String methodName, Context context, ProcessKind processKind)
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());
methodName
- Name of the method triggering the span creation.context
- Additional metadata that is passed through the call stack.processKind
- AMQP operation kind.Context
object containing the returned span.NullPointerException
- if methodName
or context
or processKind
is null
.void end(int responseCode, Throwable error, Context context)
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);
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.NullPointerException
- if context
is null
.void end(String statusMessage, Throwable error, Context context)
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);
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.NullPointerException
- if context
is null
.void setAttribute(String key, String value, Context context)
key
- Name of the metadata.value
- Value of the metadata.context
- Additional metadata that is passed through the call stack.NullPointerException
- if key
or value
or context
is null
.Context setSpanName(String spanName, Context context)
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());
spanName
- Name to give the next span.context
- Additional metadata that is passed through the call stack.Context
object containing the name of the returned span.NullPointerException
- if spanName
or context
is null
.void addLink(Context context)
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);
context
- Additional metadata that is passed through the call stack.NullPointerException
- if context
is null
.Context extractContext(String diagnosticId, Context context)
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());
diagnosticId
- Unique identifier for the trace information of the span.context
- Additional metadata that is passed through the call stack.Context
object containing the span context.NullPointerException
- if diagnosticId
or context
is null
.default Context getSharedSpanBuilder(String spanName, Context context)
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());
spanName
- Name to give the span for the created builder.context
- Additional metadata that is passed through the call stack.Context
object containing the span builder.NullPointerException
- if context
or spanName
is null
.@Deprecated default void addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp)
Tracer.addEvent(String, Map, OffsetDateTime, Context)
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.
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.NullPointerException
- if eventName
is null
.default void addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context)
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.
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.NullPointerException
- if eventName
is null
.default AutoCloseable makeSpanCurrent(Context context)
context
- Context with span.
Code samples
Starts a tracing span, makes it current and ends it
// Starts a span, makes it current and then stops it. Context traceContext = tracer.start("EventHub.process", Context.NONE); // Make sure to always use try-with-resource statement with makeSpanCurrent try (AutoCloseable ignored = tracer.makeSpanCurrent(traceContext)) { System.out.println("doing some work..."); } catch (Throwable throwable) { tracer.end("Failure", throwable, traceContext); } finally { tracer.end("OK", null, traceContext); }
Copyright © 2021 Microsoft Corporation. All rights reserved.