Module Contents

class AWSXRayRecorder


A global AWS X-Ray recorder that will begin/end segments/subsegments and send them to the X-Ray daemon. This recorder is initialized during loading time so you can use:

from aws_xray_sdk.core import xray_recorder

in your module to access it


Proxy method to Streaming module’s streaming_threshold property.

configure(self, sampling=None, plugins=None, context_missing=None, sampling_rules=None, daemon_address=None, service=None, context=None, emitter=None, streaming=None, dynamic_naming=None, streaming_threshold=None, max_trace_back=None, sampler=None, stream_sql=True)

Configure global X-Ray recorder.

Configure needs to run before patching thrid party libraries to avoid creating dangling subsegment. :param bool sampling: If sampling is enabled, every time the recorder

creates a segment it decides whether to send this segment to the X-Ray daemon. This setting is not used if the recorder is running in AWS Lambda. The recorder always respect the incoming sampling decisions regardless of this setting.
  • sampling_rules – Pass a set of local custom sampling rules. Can be an absolute path of the sampling rule config json file or a dictionary that defines those rules. This will also be the fallback rules in case of centralized sampling opted-in while the cetralized sampling rules are not available.
  • sampler – The sampler used to make sampling decisions. The SDK provides two built-in samplers. One is centralized rules based and the other is local rules based. The former is the default.
  • plugins (tuple) – plugins that add extra metadata to each segment. Currently available plugins are EC2Plugin, ECS plugin and ElasticBeanstalkPlugin. If you want to disable all previously enabled plugins, pass an empty tuple ().
  • context_missing (str) – recorder behavior when it tries to mutate a segment or add a subsegment but there is no active segment. RUNTIME_ERROR means the recorder will raise an exception. LOG_ERROR means the recorder will only log the error and do nothing.
  • daemon_address (str) – The X-Ray daemon address where the recorder sends data to.
  • service (str) – default segment name if creating a segment without providing a name.
  • context – You can pass your own implementation of context storage for active segment/subsegment by overriding the default Context class.
  • emitter – The emitter that sends a segment/subsegment to the X-Ray daemon. You can override UDPEmitter class.
  • dynamic_naming – a string that defines a pattern that host names should match. Alternatively you can pass a module which overrides DefaultDynamicNaming module.
  • streaming – The streaming module to stream out trace documents when they grow too large. You can override DefaultStreaming class to have your own implementation of the streaming process.
  • streaming_threshold – If breaks within a single segment it will start streaming out children subsegments. By default it is the maximum number of subsegments within a segment.
  • max_trace_back (int) – The maxinum number of stack traces recorded by auto-capture. Lower this if a single document becomes too large.
  • stream_sql (bool) – Whether SQL query texts should be streamed.

Environment variables AWS_XRAY_DAEMON_ADDRESS, AWS_XRAY_CONTEXT_MISSING and AWS_XRAY_TRACING_NAME respectively overrides arguments daemon_address, context_missing and service.

in_segment(self, name=None, **segment_kwargs)

Return a segment context manger.

  • name (str) – the name of the segment
  • segment_kwargs (dict) – remaining arguments passed directly to begin_segment
in_subsegment(self, name=None, **subsegment_kwargs)

Return a subsegment context manger.

  • name (str) – the name of the subsegment
  • subsegment_kwargs (dict) – remaining arguments passed directly to begin_subsegment
begin_segment(self, name=None, traceid=None, parent_id=None, sampling=None)

Begin a segment on the current thread and return it. The recorder only keeps one segment at a time. Create the second one without closing existing one will overwrite it.

  • name (str) – the name of the segment
  • traceid (str) – trace id of the segment
  • sampling (int) – 0 means not sampled, 1 means sampled
end_segment(self, end_time=None)

End the current segment and send it to X-Ray daemon if it is ready to send. Ready means segment and all its subsegments are closed.

Parameters:end_time (float) – segment compeletion in unix epoch in seconds.

Return the currently active segment. In a multithreading environment, this will make sure the segment returned is the one created by the same thread.

begin_subsegment(self, name, namespace='local')

Begin a new subsegment. If there is open subsegment, the newly created subsegment will be the child of latest opened subsegment. If not, it will be the child of the current open segment.

  • name (str) – the name of the subsegment.
  • namespace (str) – currently can only be ‘local’, ‘remote’, ‘aws’.

Return the latest opened subsegment. In a multithreading environment, this will make sure the subsegment returned is one created by the same thread.

end_subsegment(self, end_time=None)

End the current active subsegment. If this is the last one open under its parent segment, the entire segment will be sent.

Parameters:end_time (float) – subsegment compeletion in unix epoch in seconds.
put_annotation(self, key, value)

Annotate current active trace entity with a key-value pair. Annotations will be indexed for later search query.

  • key (str) – annotation key
  • value (object) – annotation value. Any type other than string/number/bool will be dropped
put_metadata(self, key, value, namespace='default')

Add metadata to the current active trace entity. Metadata is not indexed but can be later retrieved by BatchGetTraces API.

  • namespace (str) – optional. Default namespace is default. It must be a string and prefix AWS. is reserved.
  • key (str) – metadata key under specified namespace
  • value (object) – any object that can be serialized into JSON string

Check if the current trace entity is sampled or not. Return False if no active entity found.


A pass through method to context.get_trace_entity().

set_trace_entity(self, trace_entity)

A pass through method to context.set_trace_entity().


A pass through method to context.clear_trace_entities().


Stream all closed subsegments to the daemon and remove reference to the parent segment. No-op for a not sampled segment.

capture(self, name=None)

A decorator that records enclosed function in a subsegment. It only works with synchronous functions.

params str name: The name of the subsegment. If not specified the function name will be used.

record_subsegment(self, wrapped, instance, args, kwargs, name, namespace, meta_processor)
_populate_runtime_context(self, segment, sampling_decision)

Send the current segment to X-Ray daemon if it is present and sampled, then clean up context storage. The emitter will handle failures.

_stream_subsegment_out(self, subsegment)
_load_sampling_rules(self, sampling_rules)
_is_subsegment(self, entity)