XRay

XRay

This library is used to add XRay tracing and analytics to monitor our platform. XRay is an AWS services that provides good insights into how our distibuted system is running.

This system has a few pieces. First you have to turn_it_on by either calling the constructor with turn_it_on=True or setting an environment variable (not implemented yet).

• segments, and optional subsegments are used to identify different parts of the code in a heirarcial way. Keep in mind that these need to be closed.

• Annotations are used to orgainze/search for traces using the XRay console.

• Metadata can be added to provide information about data being used in the trace.

The way XRay is integrated with AWS Lambda is that the Lambda system uses the segment so only subsegments are available. Trying to use begin_segment will throw some very odd errors when being used in a lambda (you have been warned).

The imports on this module are called from within the constructor. The reason for this is that the xray-sdk needs to be loaded last so that it can patch the other SDKs. This also allows us to easily turn the globally turn XRay feature on and off as well as moving all of the logic for on/off out of the caller functions.

Usage in a lambda looks something like this:

from AwAws.Xray.xray import Xray

test_obj = {
    'this': 'is a test',
    'with': ['a', 'list', 'of', 'items'],
    'and': {
        'some': 'nested info'
    }
}

xray = XRay(turn_it_on=True)  # the default is off
kms = KMS()
xray.begin_subsegment('kms')  # creates a subsegment called kms
kms.set_encryption_regions('us-east-2')
kms.set_master_keys('arn:aws:kms:us-east-2:acct_num:key/key_id')
cipher_obj = kms.encrypt_object(test_obj)

xray.put_annotation('object_type', 'object_type_description')  # key/value
xray.put_metadata('cipher_obj', test_obj)  # add some info about the object
decrypted_obj = kms.decrypt_object(cipher_obj)

# Check it
print('ENCRYPTED', cipher_obj)
print('DECRYPTED', decrypted_obj)
assert test_obj == decrypted_obj
print('Yeah! Got it!')

xray.end_subsegment()

class AwAws.XRay.xray.XRay(turn_it_on=False)

begin_segment(segment_name)

creates a new segment

begin_subsegment(sub_segment_name)

Create a new segment - use this in lambda functions

end_segment()

End/close the segment

end_subsegment()

End/close the subsegment

put_annotation(key, value)

Annotations are used for sorting/indexing traces

put_metadata(key, data)

Metadata is any data that should be saved with the trace