Package com.amazonaws.xray

Class AWSXRayRecorder

  • public class AWSXRayRecorder
extends java.lang.Object

    • Constructor Detail

      • AWSXRayRecorder

        public AWSXRayRecorder()

    • Method Detail

      • 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.
        Use beginNoOpSegment().
        Sets the current segment to a new instance of DummySegment.
        Returns:
        the newly created DummySegment.

      • 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

      • beginSubsegmentWithoutSampling

        public Subsegment beginSubsegmentWithoutSampling​(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. The subsegment will not be sampled regardless of the SamplingStrategy.
        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.
        use setTraceEntity(Entity entity) instead
        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.