Package org.eclipse.hono.tracing

Class TracingHelper

java.lang.Object
org.eclipse.hono.tracing.TracingHelper
public final class TracingHelper extends Object
A helper class providing utility methods for interacting with the OpenTracing API.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ERROR_CAUSE_OBJECT
    An OpenTracing span log entry field containing a nested exception object.
    static final io.opentracing.tag.StringTag
    TAG_ADAPTER_INSTANCE_ID
    An OpenTracing tag indicating the identifier of a protocol adapter instance.
    static final io.opentracing.tag.StringTag
    TAG_AUTH_ID
    An OpenTracing tag that contains the authentication identifier used by a device.
    static final io.opentracing.tag.BooleanTag
    TAG_AUTHENTICATED
    An OpenTracing tag indicating if a client (device) has been authenticated.
    static final io.opentracing.tag.BooleanTag
    TAG_CACHE_HIT
    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
    TAG_CLIENT_ID
    An OpenTracing tag that contains the (transport protocol specific) identifier of a client connecting to a server.
    static final io.opentracing.tag.StringTag
    TAG_CORRELATION_ID
    An OpenTracing tag that contains the identifier used to correlate a response with a request message.
    static final io.opentracing.tag.StringTag
    TAG_CREDENTIALS_TYPE
    An OpenTracing tag that contains the type of credentials used by a device.
    static final io.opentracing.tag.IntTag
    TAG_CREDIT
    An OpenTracing tag that contains the number of available credits for a sender link.
    static final io.opentracing.tag.StringTag
    TAG_DEVICE_ID
    An OpenTracing tag that contains the device identifier.
    static final io.opentracing.tag.IntTag
    TAG_DEVICE_TTD
    An OpenTracing tag that contains the time that a device will wait for an upstream message before disconnecting.
    static final io.opentracing.tag.StringTag
    TAG_GATEWAY_ID
    An OpenTracing tag that contains the gateway identifier.
    static final io.opentracing.tag.StringTag
    TAG_MESSAGE_ID
    An OpenTracing tag that contains the identifier of a (request) message.
    static final io.opentracing.tag.StringTag
    TAG_PEER_CONTAINER
    An OpenTracing tag that indicates the container id of a remote peer.
    static final io.opentracing.tag.StringTag
    TAG_QOS
    An OpenTracing tag that contains the QoS that a device has used for publishing a message.
    static final io.opentracing.tag.StringTag
    TAG_REMOTE_STATE
    An OpenTracing tag that indicates the remote delivery state of an AMQP 1.0 message transfer.
    static final io.opentracing.tag.StringTag
    TAG_RESOURCE_VERSION
    An OpenTracing tag that contains the version of a resource, for example a record in a database.
    static final io.opentracing.tag.StringTag
    TAG_SUBJECT_DN
    An OpenTracing tag that contains an X.500 Subject DN.
    static final io.opentracing.tag.StringTag
    TAG_TENANT_ID
    An OpenTracing tag that contains the tenant identifier.
    static final io.opentracing.tag.BooleanTag
    TAG_TLS
    An OpenTracing tag indicating if a client's connection is secured using TLS.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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 a SpanContext from a JSON object.
    static io.opentracing.SpanContext
    extractSpanContext(io.opentracing.Tracer tracer, io.vertx.core.MultiMap headers)
    Extracts a SpanContext 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 a SpanContext from given key-value pairs.
    static Map<String,Object>
    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 a SpanContext into the headers of vert.x DeliveryOptions.
    static void
    injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, io.vertx.core.json.JsonObject jsonObject)
    Injects a SpanContext into a JSON object.
    static void
    injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, BiConsumer<String,String> keyValueConsumer)
    Injects a SpanContext as key-value pairs into a given operation.
    static void
    logError(io.opentracing.Span span, String message)
    Marks an OpenTracing span as erroneous and logs a message.
    static void
    logError(io.opentracing.Span span, String message, Throwable error)
    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
    logError(io.opentracing.Span span, Throwable error)
    Marks an OpenTracing span as erroneous and logs an exception.
    static void
    logError(io.opentracing.Span span, Map<String,?> items)
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • TAG_ADAPTER_INSTANCE_ID

      public static final io.opentracing.tag.StringTag TAG_ADAPTER_INSTANCE_ID
      An OpenTracing tag indicating the identifier of a protocol adapter instance.

    • TAG_AUTHENTICATED

      public static final io.opentracing.tag.BooleanTag TAG_AUTHENTICATED
      An OpenTracing tag indicating if a client (device) has been authenticated.

    • TAG_AUTH_ID

      public static final io.opentracing.tag.StringTag TAG_AUTH_ID
      An OpenTracing tag that contains the authentication identifier used by a device.

    • TAG_CACHE_HIT

      public static final io.opentracing.tag.BooleanTag TAG_CACHE_HIT
      An 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_ID
      An 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_ID
      An 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_TYPE
      An OpenTracing tag that contains the type of credentials used by a device.

    • TAG_CREDIT

      public static final io.opentracing.tag.IntTag TAG_CREDIT
      An 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_ID
      An OpenTracing tag that contains the device identifier.

    • TAG_DEVICE_TTD

      public static final io.opentracing.tag.IntTag TAG_DEVICE_TTD
      An 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_ID
      An OpenTracing tag that contains the gateway identifier.

    • TAG_MESSAGE_ID

      public static final io.opentracing.tag.StringTag TAG_MESSAGE_ID
      An OpenTracing tag that contains the identifier of a (request) message.

    • TAG_PEER_CONTAINER

      public static final io.opentracing.tag.StringTag TAG_PEER_CONTAINER
      An OpenTracing tag that indicates the container id of a remote peer.

    • TAG_QOS

      public static final io.opentracing.tag.StringTag TAG_QOS
      An 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_STATE
      An 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_VERSION
      An 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_DN
      An OpenTracing tag that contains an X.500 Subject DN.

    • TAG_TENANT_ID

      public static final io.opentracing.tag.StringTag TAG_TENANT_ID
      An OpenTracing tag that contains the tenant identifier.

    • TAG_TLS

      public static final io.opentracing.tag.BooleanTag TAG_TLS
      An OpenTracing tag indicating if a client's connection is secured using TLS.

    • ERROR_CAUSE_OBJECT

      public static final String ERROR_CAUSE_OBJECT
      An OpenTracing span log entry field containing a nested exception object.
      See Also:

  • Method Details

    • setDeviceTags

      public static void setDeviceTags(io.opentracing.Span span, String tenantId, String deviceId)
      Sets the tags identifying a device.
      Parameters:
      span - The span to set the tags on.
      tenantId - The tenant that the device belongs to or null if unknown.
      deviceId - The device identifier or null 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 or null if unknown.
      deviceId - The device identifier or null if unknown.
      authId - The authentication identifier or null if unknown.

    • getErrorLogItems

      public static Map<String,Object> getErrorLogItems(String message, Throwable error)
      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

      public static void logError(io.opentracing.Span span, String message)
      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 is null.

    • logError

      public static void logError(io.opentracing.Span span, Throwable error)
      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 the Logger of this class. To suppress this, the logError(Span, String, Throwable, boolean) method may be used instead, invoking it with true as value for the skipUnexpectedErrorCheck parameter.

      Parameters:
      span - The span to mark.
      error - The exception that has occurred.
      Throws:
      NullPointerException - if error is null.

    • logError

      public static void logError(io.opentracing.Span span, String message, Throwable error)
      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 the Logger of this class. To suppress this, the logError(Span, String, Throwable, boolean) method may be used instead, invoking it with true as value for the skipUnexpectedErrorCheck 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 are null.

    • 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 are null.

    • logError

      public static void logError(io.opentracing.Span span, Map<String,?> items)
      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 using event as key and error as the value if the items do not contain such an entry already. A given event 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 a SpanContext 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 or null if no context is available.
      jsonObject - The JSON object to inject the context into.
      Throws:
      NullPointerException - if tracer or jsonObject is null.

    • extractSpanContext

      public static io.opentracing.SpanContext extractSpanContext(io.opentracing.Tracer tracer, io.vertx.core.json.JsonObject jsonObject)
      Extracts a SpanContext 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 are null.

    • injectSpanContext

      public static void injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, io.vertx.core.eventbus.DeliveryOptions deliveryOptions)
      Injects a SpanContext into the headers of vert.x DeliveryOptions.
      Parameters:
      tracer - The Tracer to use for injecting the context.
      spanContext - The context to inject or null if no context is available.
      deliveryOptions - The delivery options to inject the context into.
      Throws:
      NullPointerException - if tracer or deliveryOptions is null.

    • extractSpanContext

      public static io.opentracing.SpanContext extractSpanContext(io.opentracing.Tracer tracer, io.vertx.core.MultiMap headers)
      Extracts a SpanContext 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 are null.

    • injectSpanContext

      public static void injectSpanContext(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, BiConsumer<String,String> keyValueConsumer)
      Injects a SpanContext 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 or null if no context is available.
      keyValueConsumer - The operation that will receive the key-value pairs representing the context.
      Throws:
      NullPointerException - if tracer or keyValueConsumer is null.

    • extractSpanContext

      public static io.opentracing.SpanContext extractSpanContext(io.opentracing.Tracer tracer, Supplier<Iterator<Map.Entry<String,String>>> keyValueIteratorSupplier)
      Extracts a SpanContext 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 is null.

    • 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 is null.

    • 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 is null.

    • 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 is null.

    • 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 span
      referenceType - The type of reference towards the span context.
      Returns:
      The span builder.
      Throws:
      NullPointerException - if tracer or operationName or referenceType is null.

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