Class TracingHelper
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
An OpenTracing span log entry field containing a nested exception object.static final io.opentracing.tag.StringTag
An OpenTracing tag indicating the identifier of a protocol adapter instance.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the authentication identifier used by a device.static final io.opentracing.tag.BooleanTag
An OpenTracing tag indicating if a client (device) has been authenticated.static final io.opentracing.tag.BooleanTag
An OpenTracing tag that is used to indicate if the result of an operation has been taken from a local cache.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the (transport protocol specific) identifier of a client connecting to a server.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the identifier used to correlate a response with a request message.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the type of credentials used by a device.static final io.opentracing.tag.IntTag
An OpenTracing tag that contains the number of available credits for a sender link.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the device identifier.static final io.opentracing.tag.IntTag
An OpenTracing tag that contains the time that a device will wait for an upstream message before disconnecting.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the gateway identifier.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the identifier of a (request) message.static final io.opentracing.tag.StringTag
An OpenTracing tag that indicates the container id of a remote peer.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the QoS that a device has used for publishing a message.static final io.opentracing.tag.StringTag
An OpenTracing tag that indicates the remote delivery state of an AMQP 1.0 message transfer.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the version of a resource, for example a record in a database.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains an X.500 Subject DN.static final io.opentracing.tag.StringTag
An OpenTracing tag that contains the tenant identifier.static final io.opentracing.tag.BooleanTag
An OpenTracing tag indicating if a client's connection is secured using TLS. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
adoptSamplingPriorityFromContext
(io.opentracing.SpanContext spanContext, io.opentracing.Tracer.SpanBuilder spanBuilder) Gets a "sampling.priority" baggage item from the given span context (if set) and sets a corresponding tag in the given span builder.static io.opentracing.Tracer.SpanBuilder
buildChildSpan
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName, String component) Creates a span builder that is initialized with the given operation name and a child-of reference to the given span context (if set).static io.opentracing.Tracer.SpanBuilder
buildFollowsFromSpan
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName) Creates a span builder that is initialized with the given operation name and a follows-from reference to the given span context (if set).static io.opentracing.Tracer.SpanBuilder
buildServerChildSpan
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName, String component) Creates a span builder that is initialized with the given operation name and a child-of reference to the given span context (if set).static io.opentracing.Tracer.SpanBuilder
buildSpan
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName, String referenceType) Creates a span builder that is initialized with the given operation name and a reference to the given span context (if set).static io.opentracing.SpanContext
extractSpanContext
(io.opentracing.Tracer tracer, io.vertx.core.json.JsonObject jsonObject) Extracts aSpanContext
from a JSON object.static io.opentracing.SpanContext
extractSpanContext
(io.opentracing.Tracer tracer, io.vertx.core.MultiMap headers) Extracts aSpanContext
from the headers of a vert.x event bus message.static io.opentracing.SpanContext
extractSpanContext
(io.opentracing.Tracer tracer, Supplier<Iterator<Map.Entry<String, String>>> keyValueIteratorSupplier) Extracts aSpanContext
from given key-value pairs.getErrorLogItems
(String message, Throwable error) Creates a set of items to log for a message and an error.static void
injectSpanContext
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, io.vertx.core.eventbus.DeliveryOptions deliveryOptions) Injects aSpanContext
into the headers of vert.xDeliveryOptions
.static void
injectSpanContext
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, io.vertx.core.json.JsonObject jsonObject) Injects aSpanContext
into a JSON object.static void
injectSpanContext
(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, BiConsumer<String, String> keyValueConsumer) Injects aSpanContext
as key-value pairs into a given operation.static void
Marks an OpenTracing span as erroneous and logs a message.static void
Marks an OpenTracing span as erroneous, logs a message and an error.static void
logError
(io.opentracing.Span span, String message, Throwable error, boolean skipUnexpectedErrorCheck) Marks an OpenTracing span as erroneous, logs a message and an error.static void
Marks an OpenTracing span as erroneous and logs an exception.static void
Marks an OpenTracing span as erroneous and logs several items.static void
setDeviceTags
(io.opentracing.Span span, String tenantId, String deviceId) Sets the tags identifying a device.static void
setDeviceTags
(io.opentracing.Span span, String tenantId, String deviceId, String authId) Sets the tags identifying a device.static void
setTraceSamplingPriority
(io.opentracing.Span span, int samplingPriority) Sets a "sampling.priority" tag and baggage item with the given samplingPriority value in the given span.
-
Field Details
-
TAG_ADAPTER_INSTANCE_ID
public static final io.opentracing.tag.StringTag TAG_ADAPTER_INSTANCE_IDAn OpenTracing tag indicating the identifier of a protocol adapter instance. -
TAG_AUTHENTICATED
public static final io.opentracing.tag.BooleanTag TAG_AUTHENTICATEDAn OpenTracing tag indicating if a client (device) has been authenticated. -
TAG_AUTH_ID
public static final io.opentracing.tag.StringTag TAG_AUTH_IDAn OpenTracing tag that contains the authentication identifier used by a device. -
TAG_CACHE_HIT
public static final io.opentracing.tag.BooleanTag TAG_CACHE_HITAn OpenTracing tag that is used to indicate if the result of an operation has been taken from a local cache. -
TAG_CLIENT_ID
public static final io.opentracing.tag.StringTag TAG_CLIENT_IDAn OpenTracing tag that contains the (transport protocol specific) identifier of a client connecting to a server. This could be the MQTT client identifier or the AMQP 1.0 container name. -
TAG_CORRELATION_ID
public static final io.opentracing.tag.StringTag TAG_CORRELATION_IDAn OpenTracing tag that contains the identifier used to correlate a response with a request message. -
TAG_CREDENTIALS_TYPE
public static final io.opentracing.tag.StringTag TAG_CREDENTIALS_TYPEAn OpenTracing tag that contains the type of credentials used by a device. -
TAG_CREDIT
public static final io.opentracing.tag.IntTag TAG_CREDITAn OpenTracing tag that contains the number of available credits for a sender link. -
TAG_DEVICE_ID
public static final io.opentracing.tag.StringTag TAG_DEVICE_IDAn OpenTracing tag that contains the device identifier. -
TAG_DEVICE_TTD
public static final io.opentracing.tag.IntTag TAG_DEVICE_TTDAn OpenTracing tag that contains the time that a device will wait for an upstream message before disconnecting. -
TAG_GATEWAY_ID
public static final io.opentracing.tag.StringTag TAG_GATEWAY_IDAn OpenTracing tag that contains the gateway identifier. -
TAG_MESSAGE_ID
public static final io.opentracing.tag.StringTag TAG_MESSAGE_IDAn OpenTracing tag that contains the identifier of a (request) message. -
TAG_PEER_CONTAINER
public static final io.opentracing.tag.StringTag TAG_PEER_CONTAINERAn OpenTracing tag that indicates the container id of a remote peer. -
TAG_QOS
public static final io.opentracing.tag.StringTag TAG_QOSAn OpenTracing tag that contains the QoS that a device has used for publishing a message. -
TAG_REMOTE_STATE
public static final io.opentracing.tag.StringTag TAG_REMOTE_STATEAn OpenTracing tag that indicates the remote delivery state of an AMQP 1.0 message transfer. -
TAG_RESOURCE_VERSION
public static final io.opentracing.tag.StringTag TAG_RESOURCE_VERSIONAn OpenTracing tag that contains the version of a resource, for example a record in a database. -
TAG_SUBJECT_DN
public static final io.opentracing.tag.StringTag TAG_SUBJECT_DNAn OpenTracing tag that contains an X.500 Subject DN. -
TAG_TENANT_ID
public static final io.opentracing.tag.StringTag TAG_TENANT_IDAn OpenTracing tag that contains the tenant identifier. -
TAG_TLS
public static final io.opentracing.tag.BooleanTag TAG_TLSAn OpenTracing tag indicating if a client's connection is secured using TLS. -
ERROR_CAUSE_OBJECT
An OpenTracing span log entry field containing a nested exception object.- See Also:
-
-
Method Details
-
setDeviceTags
Sets the tags identifying a device.- Parameters:
span
- The span to set the tags on.tenantId
- The tenant that the device belongs to ornull
if unknown.deviceId
- The device identifier ornull
if unknown.
-
setDeviceTags
public static void setDeviceTags(io.opentracing.Span span, String tenantId, String deviceId, String authId) Sets the tags identifying a device.- Parameters:
span
- The span to set the tags on.tenantId
- The tenant that the device belongs to ornull
if unknown.deviceId
- The device identifier ornull
if unknown.authId
- The authentication identifier ornull
if unknown.
-
getErrorLogItems
Creates a set of items to log for a message and an error.- Parameters:
message
- The message.error
- The error.- Returns:
- The items to log.
-
logError
Marks an OpenTracing span as erroneous and logs a message.This method does not finish the span.
- Parameters:
span
- The span to mark.message
- The message to log on the span.- Throws:
NullPointerException
- if message isnull
.
-
logError
Marks an OpenTracing span as erroneous and logs an exception.This method does not finish the span.
If the given error represents an unexpected error (e.g. a
NullPointerException
), a WARN log entry will be created on theLogger
of this class. To suppress this, thelogError(Span, String, Throwable, boolean)
method may be used instead, invoking it withtrue
as value for theskipUnexpectedErrorCheck
parameter.- Parameters:
span
- The span to mark.error
- The exception that has occurred.- Throws:
NullPointerException
- if error isnull
.
-
logError
Marks an OpenTracing span as erroneous, logs a message and an error.This method does not finish the span.
If the given error represents an unexpected error (e.g. a
NullPointerException
), a WARN log entry will be created on theLogger
of this class. To suppress this, thelogError(Span, String, Throwable, boolean)
method may be used instead, invoking it withtrue
as value for theskipUnexpectedErrorCheck
parameter.- Parameters:
span
- The span to mark.message
- The message to log on the span.error
- The error to log on the span.- Throws:
NullPointerException
- if both message and error arenull
.
-
logError
public static void logError(io.opentracing.Span span, String message, Throwable error, boolean skipUnexpectedErrorCheck) Marks an OpenTracing span as erroneous, logs a message and an error.This method does not finish the span.
- Parameters:
span
- The span to mark.message
- The message to log on the span.error
- The error to log on the span.skipUnexpectedErrorCheck
- Whether to skip the check for an unexpected error, meaning no WARN log entry will be created for such an error.- Throws:
NullPointerException
- if both message and error arenull
.
-
logError
Marks an OpenTracing span as erroneous and logs several items.This method does not finish the span.
- Parameters:
span
- The span to mark.items
- The items to log on the span. Note that this method will also log an item usingevent
as key anderror
as the value if the items do not contain such an entry already. A givenevent
item with a different value will be ignored.
-
injectSpanContext
public static void injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, io.vertx.core.json.JsonObject jsonObject) Injects aSpanContext
into a JSON object.The span context will be injected into a new JSON object under key span-context.
- Parameters:
tracer
- The Tracer to use for injecting the context.spanContext
- The context to inject ornull
if no context is available.jsonObject
- The JSON object to inject the context into.- Throws:
NullPointerException
- if tracer or jsonObject isnull
.
-
extractSpanContext
public static io.opentracing.SpanContext extractSpanContext(io.opentracing.Tracer tracer, io.vertx.core.json.JsonObject jsonObject) Extracts aSpanContext
from a JSON object.The span context will be read from a JSON object under key span-context.
- Parameters:
tracer
- The Tracer to use for extracting the context.jsonObject
- The JSON object to extract the context from.- Returns:
- The context or
null
if the given JSON object does not contain a context. - Throws:
NullPointerException
- if any of the parameters arenull
.
-
injectSpanContext
public static void injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, io.vertx.core.eventbus.DeliveryOptions deliveryOptions) Injects aSpanContext
into the headers of vert.xDeliveryOptions
.- Parameters:
tracer
- The Tracer to use for injecting the context.spanContext
- The context to inject ornull
if no context is available.deliveryOptions
- The delivery options to inject the context into.- Throws:
NullPointerException
- if tracer or deliveryOptions isnull
.
-
extractSpanContext
public static io.opentracing.SpanContext extractSpanContext(io.opentracing.Tracer tracer, io.vertx.core.MultiMap headers) Extracts aSpanContext
from the headers of a vert.x event bus message.- Parameters:
tracer
- The Tracer to use for extracting the context.headers
- The headers to extract the context from.- Returns:
- The context or
null
if the given options do not contain a context. - Throws:
NullPointerException
- if any of the parameters arenull
.
-
injectSpanContext
public static void injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, BiConsumer<String, String> keyValueConsumer) Injects aSpanContext
as key-value pairs into a given operation.This provides a generic way to serialize a span context in any kind of textual data. See
extractSpanContext(Tracer, Supplier)
for the corresponding method to deserialize the context from that data.- Parameters:
tracer
- The Tracer to use for injecting the context.spanContext
- The context to inject ornull
if no context is available.keyValueConsumer
- The operation that will receive the key-value pairs representing the context.- Throws:
NullPointerException
- if tracer or keyValueConsumer isnull
.
-
extractSpanContext
public static io.opentracing.SpanContext extractSpanContext(io.opentracing.Tracer tracer, Supplier<Iterator<Map.Entry<String, String>>> keyValueIteratorSupplier) Extracts aSpanContext
from given key-value pairs.This provides a generic way to deserialize a span context from any kind of textual data. See
injectSpanContext(Tracer, SpanContext, BiConsumer)
for the corresponding method to serialize the context in that data.- Parameters:
tracer
- The Tracer to use for extracting the context.keyValueIteratorSupplier
- The supplier that provides an iterator over key-values pairs representing the context.- Returns:
- The context or
null
if the given options do not contain a context. - Throws:
NullPointerException
- if any of the parameters isnull
.
-
buildChildSpan
public static io.opentracing.Tracer.SpanBuilder buildChildSpan(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName, String component) Creates a span builder that is initialized with the given operation name and a child-of reference to the given span context (if set).If the given span context contains a "sampling.priority" baggage item, it is set as a tag in the returned span builder. Additionally, it is configured to ignore the active span.
- Parameters:
tracer
- The Tracer to use.spanContext
- The span context that shall be the parent of the Span being built and that is used to derive the sampling priority from (may be null).operationName
- The operation name to set for the span.component
- The component to set for the span.- Returns:
- The span builder.
- Throws:
NullPointerException
- if tracer or operationName isnull
.
-
buildServerChildSpan
public static io.opentracing.Tracer.SpanBuilder buildServerChildSpan(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName, String component) Creates a span builder that is initialized with the given operation name and a child-of reference to the given span context (if set).If the given span context contains a "sampling.priority" baggage item, it is set as a tag in the returned span builder. Additionally, it is configured to ignore the active span and set kind tag to server.
- Parameters:
tracer
- The Tracer to use.spanContext
- The span context that shall be the parent of the Span being built and that is used to derive the sampling priority from (may be null).operationName
- The operation name to set for the span.component
- The component to set for the span.- Returns:
- The span builder.
- Throws:
NullPointerException
- if tracer or operationName isnull
.
-
buildFollowsFromSpan
public static io.opentracing.Tracer.SpanBuilder buildFollowsFromSpan(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName) Creates a span builder that is initialized with the given operation name and a follows-from reference to the given span context (if set).If the given span context contains a "sampling.priority" baggage item, it is set as a tag in the returned span builder.
- Parameters:
tracer
- The Tracer to use.spanContext
- The span context that the span being build shall have a follows-from reference to and that is used to derive the sampling priority from (may be null).operationName
- The operation name to set for the span.- Returns:
- The span builder.
- Throws:
NullPointerException
- if tracer or operationName isnull
.
-
buildSpan
public static io.opentracing.Tracer.SpanBuilder buildSpan(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, String operationName, String referenceType) Creates a span builder that is initialized with the given operation name and a reference to the given span context (if set).If the given span context contains a "sampling.priority" baggage item, it is set as a tag in the returned span builder.
- Parameters:
tracer
- The Tracer to use.spanContext
- The span context to set as reference and to derive the sampling priority from (may be null).operationName
- The operation name to set for the spanreferenceType
- The type of reference towards the span context.- Returns:
- The span builder.
- Throws:
NullPointerException
- if tracer or operationName or referenceType isnull
.
-
setTraceSamplingPriority
public static void setTraceSamplingPriority(io.opentracing.Span span, int samplingPriority) Sets a "sampling.priority" tag and baggage item with the given samplingPriority value in the given span.- Parameters:
span
- The span to set the tag in.samplingPriority
- The sampling priority to set.- Throws:
NullPointerException
- if the given span is null.
-
adoptSamplingPriorityFromContext
public static void adoptSamplingPriorityFromContext(io.opentracing.SpanContext spanContext, io.opentracing.Tracer.SpanBuilder spanBuilder) Gets a "sampling.priority" baggage item from the given span context (if set) and sets a corresponding tag in the given span builder.- Parameters:
spanContext
- The span context (may be null).spanBuilder
- The span builder to set the tag in.- Throws:
NullPointerException
- if the given spanBuilder is null.
-