Package org.zalando.opentracing.sqs

Class SQSTracing

java.lang.Object
org.zalando.opentracing.sqs.SQSTracing
public final class SQSTracing
extends java.lang.Object
Utility for injecting OpenTracing-based tracing information into SQS messages, as well as extracting it again from SQS messages. This information is injected as a single SQS message attribute called "span_context", and encoded as a simple JSON structure.

Note that SQS message attributes have a limit of (currently) 256 KB, so huge span contexts won't work properly. However, in practice, span contexts should be kept as small as possible anyway.

This utility works with both the AWS SDK and the AWS SDK 2.0.

  • Constructor Summary

    Constructors
    Constructor Description
    SQSTracing​(io.opentracing.Tracer tracer)
    Initializes this utility for a given tracer implementation.
    SQSTracing​(io.opentracing.Tracer tracer, java.lang.String attributeKey)
    Initializes this utility for a given tracer implementation.

  • Method Summary

    Modifier and Type Method Description
    io.opentracing.Span createActiveQueueingSpan​(java.lang.String queueUrl, java.lang.String spanName)
    Create and activate an OpenTracing span for a message about to be published into a queue.
    io.opentracing.Span createQueueingSpan​(java.lang.String queueUrl, java.lang.String spanName, boolean activate)
    Create an OpenTracing span for a message about to be published into a queue.
    java.util.Map<java.lang.String,​io.opentracing.SpanContext> extractFrom​(com.amazonaws.services.sqs.model.ReceiveMessageResult result)
    Extracts all span contexts from the given batch of retrieved SQS messages (AWS SDK 1.0).
    java.util.Map<java.lang.String,​io.opentracing.SpanContext> extractFrom​(software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse response)
    Extracts all span contexts from the given batch of retrieved SQS messages (AWS SDK 2.0).
    com.amazonaws.services.sqs.model.SendMessageBatchRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageBatchRequest request)
    Injects the currently active span context into the whole batch of messages to send over SQS (AWS SDK 1.0).
    com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry injectInto​(com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry request, io.opentracing.SpanContext spanContext)
    Injects the given span context into the entry of a batch of messages to send over SQS (AWS SDK 1.0).
    com.amazonaws.services.sqs.model.SendMessageBatchRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageBatchRequest request, io.opentracing.SpanContext spanContext)
    Injects the given span context into the whole batch of messages to send over SQS (AWS SDK 1.0).
    com.amazonaws.services.sqs.model.SendMessageRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageRequest request)
    Injects the currently active span context into a single-message SQS send request (AWS SDK 1.0).
    com.amazonaws.services.sqs.model.SendMessageRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageRequest request, io.opentracing.SpanContext spanContext)
    Injects the given span context into a single-message SQS send request (AWS SDK 1.0).
    software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest request)
    Injects the currently active span context into a whole batch of messages to send over SQS (AWS SDK 2.0).
    software.amazon.awssdk.services.sqs.model.SendMessageBatchRequestEntry injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageBatchRequestEntry request, io.opentracing.SpanContext spanContext)
    Injects the given span context into the entry of a batch of messages to send over SQS (AWS SDK 2.0).
    software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest request, io.opentracing.SpanContext spanContext)
    Injects the given span context into a whole batch of messages to send over SQS (AWS SDK 2.0).
    software.amazon.awssdk.services.sqs.model.SendMessageRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageRequest request)
    Injects the currently active span context into a single-message SQS send request (AWS SDK 2.0).
    software.amazon.awssdk.services.sqs.model.SendMessageRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageRequest request, io.opentracing.SpanContext spanContext)
    Injects the given span context into a single-message SQS send request (AWS SDK 2.0).

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • SQSTracing

      public SQSTracing​(io.opentracing.Tracer tracer)
      Initializes this utility for a given tracer implementation. This is a lightweight operation, so you don't have to keep the instance around everywhere.

      This constructor will use SPAN_CONTEXT_ATTRIBUTE_KEY as the message attribute key.

      Parameters:
      tracer - The vendor-specific tracer implementation to use.

    • SQSTracing

      public SQSTracing​(io.opentracing.Tracer tracer, java.lang.String attributeKey)
      Initializes this utility for a given tracer implementation. This is a lightweight operation, so you don't have to keep the instance around everywhere.
      Parameters:
      tracer - The vendor-specific tracer implementation to use.
      attributeKey - The name to use for the message attribute key to use for storing the span context. If you customise this, make sure to keep it consistent across projects.

  • Method Details

    • injectInto

      public com.amazonaws.services.sqs.model.SendMessageRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageRequest request)
      Injects the currently active span context into a single-message SQS send request (AWS SDK 1.0). Does not do anything if there is no currently active span.

      See the class description for more details.

      Attention: This modifies the original request (and only returns it for convenience), as the AWS SDK does not provide easy request copying.

      Parameters:
      request - The original request to injectInto the span context into. This request will get modified by this method.
      Returns:
      The original request, with the span context injected into it.

    • injectInto

      public com.amazonaws.services.sqs.model.SendMessageRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageRequest request, io.opentracing.SpanContext spanContext)
      Injects the given span context into a single-message SQS send request (AWS SDK 1.0). Does not do anything if the given span context is null.

      See the class description for more details.

      Attention: This modifies the original request (and only returns it for convenience), as the AWS SDK does not provide easy request copying.

      Parameters:
      request - The original request to injectInto the span context into. This request will get modified by this method.
      spanContext - The span context to injectInto. If null, this method will do nothing.
      Returns:
      The original request, with the span context injected into it.

    • injectInto

      public com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry injectInto​(com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry request, io.opentracing.SpanContext spanContext)
      Injects the given span context into the entry of a batch of messages to send over SQS (AWS SDK 1.0). Does not do anything if the given span context is null.

      See the class description for more details.

      Attention: This modifies the original request entry (and only returns it for convenience), as the AWS SDK does not provide easy request entry copying.

      This lets you injectInto different span contexts into each individual message entry for a whole batch of messages. If you want to injectInto the same span context into all the message entries of your batch, you can use the injectInto(com.amazonaws.services.sqs.model.SendMessageBatchRequest) method instead.

      Parameters:
      request - The original request entry to injectInto the span context into. This entry will get modified by this method.
      spanContext - The span context to injectInto. If null, this method will do nothing.
      Returns:
      The original request entry, with the span context injected into it.

    • injectInto

      public com.amazonaws.services.sqs.model.SendMessageBatchRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageBatchRequest request)
      Injects the currently active span context into the whole batch of messages to send over SQS (AWS SDK 1.0). Does not do anything if there is no currently active span.

      See the class description for more details.

      Attention: This modifies the original request entry (and only returns it for convenience), as the AWS SDK does not provide easy request entry copying.

      This lets you injectInto the same span context into all messages for a whole batch of messages. If you want to injectInto different span contexts for each individual message of your batch, you can use the injectInto(com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry, SpanContext) method instead.

      Parameters:
      request - The original request entry to injectInto the span context into. This entry will get modified by this method.
      Returns:
      The original request entry, with the span context injected into it.

    • injectInto

      public com.amazonaws.services.sqs.model.SendMessageBatchRequest injectInto​(com.amazonaws.services.sqs.model.SendMessageBatchRequest request, io.opentracing.SpanContext spanContext)
      Injects the given span context into the whole batch of messages to send over SQS (AWS SDK 1.0). Does not do anything if the given span context is null.

      See the class description for more details.

      Attention: This modifies the original request entry (and only returns it for convenience), as the AWS SDK does not provide easy request entry copying.

      This lets you injectInto the same span context into all messages for a whole batch of messages. If you want to injectInto different span contexts for each individual message of your batch, you can use the injectInto(com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry, SpanContext) method instead.

      Parameters:
      request - The original request entry to injectInto the span context into. This entry will get modified by this method.
      spanContext - The span context to injectInto. If null, this method will do nothing.
      Returns:
      The original request entry, with the span context injected into it.

    • injectInto

      public software.amazon.awssdk.services.sqs.model.SendMessageRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageRequest request)
      Injects the currently active span context into a single-message SQS send request (AWS SDK 2.0). Returns the given request unchanged if there is no currently active span.

      See the class description for more details.

      In the spirit of AWS SDK 2.0, this does not modify the original request, but instead returns a new request that is derived from the original one, with the added span context attribute injected.

      Parameters:
      request - The original request to injectInto the span context into.
      Returns:
      A request that is the same as the original one, but with the span context injected into it.

    • injectInto

      public software.amazon.awssdk.services.sqs.model.SendMessageRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageRequest request, io.opentracing.SpanContext spanContext)
      Injects the given span context into a single-message SQS send request (AWS SDK 2.0). Returns the given request unchanged if the given span context is null.

      See the class description for more details.

      In the spirit of AWS SDK 2.0, this does not modify the original request, but instead returns a new request that is derived from the original one, with the added span context attribute injected.

      Parameters:
      request - The original request to injectInto the span context into.
      spanContext - The span context to injectInto. If null, this method will do nothing.
      Returns:
      A request that is the same as the original one, but with the span context injected into it.

    • injectInto

      public software.amazon.awssdk.services.sqs.model.SendMessageBatchRequestEntry injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageBatchRequestEntry request, io.opentracing.SpanContext spanContext)
      Injects the given span context into the entry of a batch of messages to send over SQS (AWS SDK 2.0). Returns the given request unchanged if the given span context is null.

      See the class description for more details.

      In the spirit of AWS SDK 2.0, this does not modify the original entry, but instead returns a new entry that is derived from the original one, with the added span context attribute injected.

      This lets you injectInto different span contexts into each individual message entry for a whole batch of messages. If you want to injectInto the same span context into all the message entries of your batch, you can use the injectInto(SendMessageBatchRequest) method instead.

      Parameters:
      request - The original entry to injectInto the span context into.
      spanContext - The span context to injectInto. If null, this method will do nothing.
      Returns:
      An entry that is the same as the original one, but with the span context injected into it.

    • injectInto

      public software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest request)
      Injects the currently active span context into a whole batch of messages to send over SQS (AWS SDK 2.0). Returns the given request unchanged if there is no currently active span.

      See the class description for more details.

      In the spirit of AWS SDK 2.0, this does not modify the original request, but instead returns a new request that is derived from the original one, with the added span context attribute injected.

      This lets you injectInto the same span context into all messages for a whole batch of messages. If you want to injectInto different span contexts for each individual message of your batch, you can use the injectInto(SendMessageBatchRequestEntry, SpanContext) method instead.

      Parameters:
      request - The original request to injectInto the span context into.
      Returns:
      A request that is the same as the original one, but with the span context injected into it.

    • injectInto

      public software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest injectInto​(software.amazon.awssdk.services.sqs.model.SendMessageBatchRequest request, io.opentracing.SpanContext spanContext)
      Injects the given span context into a whole batch of messages to send over SQS (AWS SDK 2.0). Returns the given request unchanged if the given span context is null.

      See the class description for more details.

      In the spirit of AWS SDK 2.0, this does not modify the original request, but instead returns a new request that is derived from the original one, with the added span context attribute injected.

      This lets you injectInto the same span context into all messages for a whole batch of messages. If you want to injectInto different span contexts for each individual message of your batch, you can use the injectInto(SendMessageBatchRequestEntry, SpanContext) method instead.

      Parameters:
      request - The original request to injectInto the span context into.
      spanContext - The span context to injectInto. If null, this method will just return the given request.
      Returns:
      A request that is the same as the original one, but with the span context injected into it.

    • extractFrom

      public java.util.Map<java.lang.String,​io.opentracing.SpanContext> extractFrom​(com.amazonaws.services.sqs.model.ReceiveMessageResult result)
      Extracts all span contexts from the given batch of retrieved SQS messages (AWS SDK 1.0).
      Parameters:
      result - The received batch of SQS messages.
      Returns:
      A map of message ids span contexts. For each message id, if a span context was found for the respective message, then that span context is contained in this map, and referenced by the message id. Message ids for messages without span context are not contained in the map.

    • extractFrom

      public java.util.Map<java.lang.String,​io.opentracing.SpanContext> extractFrom​(software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse response)
      Extracts all span contexts from the given batch of retrieved SQS messages (AWS SDK 2.0).
      Parameters:
      response - The received batch of SQS messages.
      Returns:
      A map of message ids span contexts. For each message id, if a span context was found for the respective message, then that span context is contained in this map, and referenced by the message id. Message ids for messages without span context are not contained in the map.

    • createActiveQueueingSpan

      public io.opentracing.Span createActiveQueueingSpan​(java.lang.String queueUrl, java.lang.String spanName)
      Create and activate an OpenTracing span for a message about to be published into a queue.

      This little helper will take care of setting the span kind tag to "producer", and the message bus destination tag to the queue url.

      If there is an active span when the method gets called, it will also get added to the newly created span as a "follows from" reference.

      Parameters:
      queueUrl - The queue url this span should refer to.
      spanName - The name the span should have.
      Returns:
      The created and activated span.

    • createQueueingSpan

      public io.opentracing.Span createQueueingSpan​(java.lang.String queueUrl, java.lang.String spanName, boolean activate)
      Create an OpenTracing span for a message about to be published into a queue.

      This little helper will take care of setting the span kind tag to "producer", and the message bus destination tag to the queue url.

      If there is an active span when the method gets called, it will also get added to the newly created span as a "follows from" reference.

      Parameters:
      queueUrl - The queue url this span should refer to.
      spanName - The name the span should have.
      activate - Set to true if you want to activate the span, or to false if you want to leave it inactive.
      Returns:
      The created span.