Package org.eclipse.hono.tracing

Class 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 io.opentracing.tag.StringTag TAG_AUTH_ID
      An OpenTracing tag that contains the authentication identifier used by a device.
      static io.opentracing.tag.BooleanTag TAG_AUTHENTICATED
      An OpenTracing tag indicating if a client (device) has been authenticated.
      static 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 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 io.opentracing.tag.StringTag TAG_CORRELATION_ID
      An OpenTracing tag that contains the identifier used to correlate a response with a request message.
      static io.opentracing.tag.StringTag TAG_CREDENTIALS_TYPE
      An OpenTracing tag that contains the type of credentials used by a device.
      static io.opentracing.tag.IntTag TAG_CREDIT
      An OpenTracing tag that contains the number of available credits for a sender link.
      static io.opentracing.tag.StringTag TAG_DEVICE_ID
      An OpenTracing tag that contains the device identifier.
      static io.opentracing.tag.StringTag TAG_GATEWAY_ID
      An OpenTracing tag that contains the gateway identifier.
      static io.opentracing.tag.StringTag TAG_MESSAGE_ID
      An OpenTracing tag that contains the identifier of a (request) message.
      static io.opentracing.tag.StringTag TAG_PEER_CONTAINER
      An OpenTracing tag that indicates the container id of a remote peer.
      static io.opentracing.tag.StringTag TAG_QOS
      An OpenTracing tag that contains the QoS that a device has used for publishing a message.
      static io.opentracing.tag.StringTag TAG_REMOTE_STATE
      An OpenTracing tag that indicates the remote delivery state of an AMQP 1.0 message transfer.
      static io.opentracing.tag.StringTag TAG_TENANT_ID
      An OpenTracing tag that contains the tenant identifier.
      static io.opentracing.tag.BooleanTag TAG_TLS
      An OpenTracing tag indicating if a client's connection is secured using TLS.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      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 io.opentracing.SpanContext extractSpanContext​(io.opentracing.Tracer tracer, org.apache.qpid.proton.message.Message message)
      Extracts a SpanContext from an AMQP Message.
      static Map<String,​Object> getErrorLogItems​(Throwable error)
      Creates a set of items to log for 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 injectSpanContext​(io.opentracing.Tracer tracer, io.opentracing.SpanContext spanContext, org.apache.qpid.proton.message.Message message)
      Injects a SpanContext into an AMQP Message.
      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, 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 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 Detail

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

    • Method Detail

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

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

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

      • getErrorLogItems

        public static Map<String,​Object> getErrorLogItems​(Throwable error)
        Creates a set of items to log for an error.
        Parameters:
        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,
                            String message,
                            Throwable error)
        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.
        Throws:
        NullPointerException - if 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,
                                     org.apache.qpid.proton.message.Message message)
        Injects a SpanContext into an AMQP Message.

        The span context will be written to the message annotations of the given message.

        Parameters:
        tracer - The Tracer to use for injecting the context.
        spanContext - The context to inject or null if no context is available.
        message - The AMQP Message object to inject the context into.
        Throws:
        NullPointerException - if tracer or message is null.

      • extractSpanContext

        public static io.opentracing.SpanContext extractSpanContext​(io.opentracing.Tracer tracer,
                                                            org.apache.qpid.proton.message.Message message)
        Extracts a SpanContext from an AMQP Message.

        The span context will be read from the message annotations of the given message.

        Parameters:
        tracer - The Tracer to use for extracting the context.
        message - The AMQP Message to extract the context from.
        Returns:
        The context or null if the given Message 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.