Class AWSXRayRecorder

java.lang.Object
com.amazonaws.xray.AWSXRayRecorder

public class AWSXRayRecorder
extends java.lang.Object
  • Constructor Details

  • Method Details

    • sendSegment

      public boolean sendSegment​(Segment segment)
      Sends a segment to the emitter if the segment is marked as sampled.
      Parameters:
      segment - the segment to send
      Returns:
      true if the segment was emitted succesfully.
    • sendSubsegment

      public boolean sendSubsegment​(Subsegment subsegment)
      Sends a subsegment to the emitter if the subsegment's parent segment is marked as sampled.
      Parameters:
      subsegment - the subsegment to send
      Returns:
      true if the subsegment was emitted succesfully.
    • createSegment

      public <R> @Nullable R createSegment​(java.lang.String name, java.util.function.Function<Segment,​@Nullable R> function)
      Begins a segment, passes it to the supplied function, and ends the segment before returning the supplied function's result. Intercepts exceptions, adds them to the segment, and re-throws them.
      Type Parameters:
      R - the type of the value returned by function
      Parameters:
      name - the name to use for the created segment
      function - the function to invoke
      Returns:
      the value returned by the supplied function
    • createSegment

      public void createSegment​(java.lang.String name, java.util.function.Consumer<Segment> consumer)
      Begins a segment and passes it to the supplied consumer, and ends the segment before returning the consumer's result. Intercepts exceptions, adds them to the segment, and re-throws them.
      Parameters:
      name - the name to use for the created segment
      consumer - the function to invoke
    • createSegment

      public <R> @Nullable R createSegment​(java.lang.String name, java.util.function.Supplier<R> supplier)
      Begins a segment, invokes the provided supplier, and ends the segment before returning the supplier's result. Intercepts exceptions, adds them to the segment, and re-throws them.
      Type Parameters:
      R - the type of the value returned by supplier
      Parameters:
      name - the name to use for the created segment
      supplier - the supplier to invoke
      Returns:
      the value returned by the provided supplier
    • createSegment

      public void createSegment​(java.lang.String name, java.lang.Runnable runnable)
      Begins a segment, runs the provided runnable, and ends the segment before returning the supplier's result. Intercepts exceptions, adds them to the segment, and re-throws them.
      Parameters:
      name - the name to use for the created segment
      runnable - the runnable to run
    • createSubsegment

      public <R> @Nullable R createSubsegment​(java.lang.String name, java.util.function.Function<Subsegment,​@Nullable R> function)
      Begins a subsegment, passes it to the supplied function, and ends the subsegment before returning the supplied function's result. Intercepts exceptions, adds them to the subsegment, and re-throws them.
      Type Parameters:
      R - the type of the value returned by function
      Parameters:
      name - the name to use for the created subsegment
      function - the function to invoke
      Returns:
      the value returned by the supplied function
    • createSubsegment

      public void createSubsegment​(java.lang.String name, java.util.function.Consumer<Subsegment> consumer)
      Begins a subsegment and passes it to the supplied consumer, and ends the subsegment before returning the consumer's result. Intercepts exceptions, adds them to the subsegment, and re-throws them.
      Parameters:
      name - the name to use for the created subsegment
      consumer - the function to invoke
    • createSubsegment

      public <R> @Nullable R createSubsegment​(java.lang.String name, java.util.function.Supplier<R> supplier)
      Begins a subsegment, passes it to the provided supplier, and ends the subsegment before returning the supplier's result. Intercepts exceptions, adds them to the subsegment, and re-throws them.
      Type Parameters:
      R - the type of the value returned by function
      Parameters:
      name - the name to use for the created subsegment
      supplier - the supplier to invoke
      Returns:
      the value returned by the provided supplier
    • createSubsegment

      public void createSubsegment​(java.lang.String name, java.lang.Runnable runnable)
      Begins a subsegment, runs the provided runnable, and ends the subsegment once complete. Intercepts exceptions, adds them to the subsegment, and re-throws them.
      Parameters:
      name - the name to use for the created subsegment
      runnable - the runnable to run
    • beginSegment

      public Segment beginSegment​(java.lang.String name)
    • beginSegmentWithSampling

      public Segment beginSegmentWithSampling​(java.lang.String name)
      Begins a new segment after applying the configured sampling strategy. This method only uses the segment name and origin (if defined) to compute a sampling decision.
      Parameters:
      name - the segment name, to be used for the sampling decision
      Returns:
      Returns a proper segment if a sampled decision is made, and a no-op segment otherwise.
    • beginSegment

      public Segment beginSegment​(java.lang.String name, TraceID traceId, @Nullable java.lang.String parentId)
    • beginNoOpSegment

      public Segment beginNoOpSegment()
      Sets the current Segment to a no-op which will not record any information or be emitted. An invalid TraceID will be propagated downstream.
    • beginNoOpSegment

      public Segment beginNoOpSegment​(TraceID traceID)
      Sets the current Segment to a no-op which will not record any information or be emitted. The provided TraceID will be propagated downstream.
    • beginDummySegment

      @Deprecated public Segment beginDummySegment()
      Deprecated.
      Sets the current segment to a new instance of DummySegment.
      Returns:
      the newly created DummySegment.
    • beginDummySegment

      @Deprecated public Segment beginDummySegment​(java.lang.String name, TraceID traceId)
      Deprecated.
    • beginDummySegment

      @Deprecated public Segment beginDummySegment​(TraceID traceId)
      Deprecated.
    • endSegment

      public void endSegment()
      Ends a segment.
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and no segment is currently in progress
    • endSubsegment

      public void endSubsegment​(@Nullable Subsegment subsegment)
      Ends the provided subsegment. This method doesn't touch context storage and should be used when ending custom subsegments in asynchronous methods or other threads.
      Parameters:
      subsegment - the subsegment to close.
    • beginSubsegment

      public Subsegment beginSubsegment​(java.lang.String name)
      Begins a subsegment.
      Parameters:
      name - the name to use for the created subsegment
      Returns:
      the newly created subsegment, or null if contextMissingStrategy suppresses and no segment is currently in progress
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and no segment is currently in progress
    • endSubsegment

      public void endSubsegment()
      Ends a subsegment.
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and no segment is currently in progress
      SubsegmentNotFoundException - if contextMissingStrategy throws exceptions and no subsegment is currently in progress
    • getCurrentSegment

      public @Nullable Segment getCurrentSegment()
      Returns:
      the current segment, or null if contextMissingStrategy suppresses exceptions and there is no segment in progress
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and there is no segment in progress
    • getCurrentSegmentOptional

      public java.util.Optional<Segment> getCurrentSegmentOptional()
      Returns:
      the current segment, or Optional.empty() if there is no segment
    • getCurrentSubsegment

      public @Nullable Subsegment getCurrentSubsegment()
      Returns:
      the current subsegment, or null if contextMissingStrategy suppresses exceptions and the segment context cannot be found or the segment has no subsegments in progress
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and the segment context cannot be found
      SubsegmentNotFoundException - if contextMissingStrategy throws exceptions and the current segment has no subsegments in progress
    • getCurrentSubsegmentOptional

      public java.util.Optional<Subsegment> getCurrentSubsegmentOptional()
      Returns:
      the current subsegment, or Optional.empty() if there is no subsegment
    • injectThreadLocal

      @Deprecated public void injectThreadLocal​(Entity entity)
      Deprecated.
      Injects the provided Entity into the current thread's thread local context.
      Parameters:
      entity - the Segment or Subsegment to inject into the current thread
    • getThreadLocal

      @Deprecated public @Nullable Entity getThreadLocal()
      Deprecated.
      use getTraceEntity() instead
      Returns:
      the Entity object currently stored in the thread's ThreadLocalStorage
    • clearThreadLocal

      @Deprecated public void clearThreadLocal()
      Deprecated.
      use clearTraceEntity() instead
    • setTraceEntity

      @Deprecated public void setTraceEntity​(@Nullable Entity entity)
      Deprecated.
      Use Entity.run(Runnable) or methods in SegmentContextExecutors instead of directly setting the trace entity so it can be restored correctly.
      Sets the trace entity value using the implementation provided by the SegmentContext resolved from the segmentContextResolverChain.
      Parameters:
      entity - the trace entity to set
    • getTraceEntity

      public @Nullable Entity getTraceEntity()
      Gets the current trace entity value using the implementation provided by the SegmentContext resolved from the segmentContextResolverChain.
      Returns:
      the current trace entity
    • clearTraceEntity

      public void clearTraceEntity()
      Clears the current trace entity value using the implementation provided by the SegmentContext resolved from the segmentContextResolverChain.
    • putRuntimeContext

      public void putRuntimeContext​(java.lang.String key, java.lang.Object value)
    • addAllLogReferences

      public void addAllLogReferences​(java.util.Set<AWSLogReference> logReferences)
    • getSamplingStrategy

      public SamplingStrategy getSamplingStrategy()
      Returns:
      the samplingStrategy
    • setSamplingStrategy

      public void setSamplingStrategy​(SamplingStrategy samplingStrategy)
      Parameters:
      samplingStrategy - the samplingStrategy to set
    • getStreamingStrategy

      public StreamingStrategy getStreamingStrategy()
      Returns:
      the streamingStrategy
    • setStreamingStrategy

      public void setStreamingStrategy​(StreamingStrategy streamingStrategy)
      Parameters:
      streamingStrategy - the streamingStrategy to set
    • getPrioritizationStrategy

      public PrioritizationStrategy getPrioritizationStrategy()
      Returns:
      the prioritizationStrategy
    • setPrioritizationStrategy

      public void setPrioritizationStrategy​(PrioritizationStrategy prioritizationStrategy)
      Parameters:
      prioritizationStrategy - the prioritizationStrategy to set
    • getThrowableSerializationStrategy

      public ThrowableSerializationStrategy getThrowableSerializationStrategy()
      Returns:
      the throwableSerializationStrategy
    • setThrowableSerializationStrategy

      public void setThrowableSerializationStrategy​(ThrowableSerializationStrategy throwableSerializationStrategy)
      Parameters:
      throwableSerializationStrategy - the throwableSerializationStrategy to set
    • getContextMissingStrategy

      public ContextMissingStrategy getContextMissingStrategy()
      Returns:
      the contextMissingStrategy
    • setContextMissingStrategy

      public void setContextMissingStrategy​(ContextMissingStrategy contextMissingStrategy)
      Parameters:
      contextMissingStrategy - the contextMissingStrategy to set
    • getSegmentContextResolverChain

      public SegmentContextResolverChain getSegmentContextResolverChain()
      Returns:
      the segmentContextResolverChain
    • setSegmentContextResolverChain

      public void setSegmentContextResolverChain​(SegmentContextResolverChain segmentContextResolverChain)
      Parameters:
      segmentContextResolverChain - the segmentContextResolverChain to set
    • getEmitter

      public Emitter getEmitter()
      Returns:
      the emitter
    • setEmitter

      public void setEmitter​(Emitter emitter)
      Parameters:
      emitter - the emitter to set
    • getSegmentListeners

      public java.util.ArrayList<SegmentListener> getSegmentListeners()
      Returns the list of SegmentListeners attached to the recorder
      Returns:
      the SegmentListeners
    • addSegmentListener

      public void addSegmentListener​(SegmentListener segmentListener)
      Adds a single SegmentListener to the recorder
      Parameters:
      segmentListener - a SegmentListener to add
    • addAllSegmentListeners

      public void addAllSegmentListeners​(java.util.Collection<SegmentListener> segmentListeners)
      Adds a Collection of SegmentListeners to the recorder
      Parameters:
      segmentListeners - a Collection of SegmentListeners to add
    • getAwsRuntimeContext

      public java.util.Map<java.lang.String,​java.lang.Object> getAwsRuntimeContext()
      Returns:
      the awsRuntimeContext
    • getServiceRuntimeContext

      public java.util.Map<java.lang.String,​java.lang.Object> getServiceRuntimeContext()
      Returns:
      the serviceRuntimeContext
    • getOrigin

      public @Nullable java.lang.String getOrigin()
      Returns:
      the origin
    • setOrigin

      public void setOrigin​(java.lang.String origin)
      Parameters:
      origin - the origin to set
    • useFastIdGenerator

      public final void useFastIdGenerator()
      Configures this AWSXRayRecorder to use a fast but cryptographically insecure random number generator for generating random IDs. This option should be preferred if your application does not rely on AWS X-Ray Trace IDs being generated from a cryptographically secure random number generator.
      See Also:
      useSecureIdGenerator()
    • useSecureIdGenerator

      public final void useSecureIdGenerator()
      Configures this AWSXRayRecorder to use a cryptographically secure random generator for generating random IDs. Unless your application in some way relies on AWS X-Ray trace IDs being generated from a cryptographically secure random number source, you should prefer to use the fast ID generator.
      See Also:
      useFastIdGenerator()
    • getIdGenerator

      public final IdGenerator getIdGenerator()
      Gets this AWSXRayRecorder instance's ID generator. This method is intended for internal use only.
      Returns:
      the configured ID generator
    • forceSamplingOfCurrentSegment

      public boolean forceSamplingOfCurrentSegment()
      Checks whether the current SamplingStrategy supports forced sampling. Use with caution, since segments sampled in this manner will not count towards your sampling statistic counts.
      Returns:
      true if forced sampling is supported and the current segment was changed from not sampled to sampled.
    • currentEntityId

      public @Nullable java.lang.String currentEntityId()
      Returns:
      the ID of the Segment or Subsegment currently in progress, or null if contextMissingStrategy suppresses exceptions and no segment or subsegment is currently in progress
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and no segment or subsegment is currently in progress
    • currentTraceId

      public @Nullable TraceID currentTraceId()
      Returns:
      the trace ID of the Segment currently in progress, or null if contextMissingStrategy suppresses exceptions and no segment or subsegment is currently in progress
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and no segment or subsegment is currently in progress
    • currentFormattedId

      public @Nullable java.lang.String currentFormattedId()
      Returns:
      the trace ID of the Segment currently in progress and the ID of the Segment or Subsegment in progress, joined with @, or null if contextMissingStrategy suppresses exceptions and no segment or subsegment is currently in progress
      Throws:
      SegmentNotFoundException - if contextMissingStrategy throws exceptions and no segment or subsegment is currently in progress
    • setForcedTraceIdGeneration

      public void setForcedTraceIdGeneration​(boolean alwaysCreateTraceId)
      Configures this AWSXRayRecorder to add valid TraceId in all segments even NoOp ones that usually have a fixed value.