Filter invalid characters from annotation key names; raise warning if…

… found (aws#22)

* Filter invalid characters from annotation key names; raise a warning if any are found

* Adjust wording in docs, as per RFC2119.

* Remove string concatenation when checking validity of annotation key names and drop annotation if invalid

* Update changelog for this PR

* Add test to ensure annotations with invalid characters in their key are dropped

CHANGELOG.rst

@@ -2,6 +2,10 @@
 CHANGELOG
 =========
 
+Unreleased
+==========
+* bugfix: Fixed an issue that caused annotation keys with invalid characters to be silently ignored.
+
 0.95
 ====
 * **Breaking**: AWS API parameter whitelist json file is moved to path `aws_xray_sdk/ext/resources/aws_para_whitelist.json` in `PR6 <https://github.com/aws/aws-xray-sdk-python/pull/6>`_.

aws_xray_sdk/core/models/entity.py

@@ -16,6 +16,7 @@
 
 # List of valid characters found at http://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html
 _valid_name_characters = string.ascii_letters + string.digits + '_.:/%&#=+\-@ '
+_valid_annotation_key_characters = string.ascii_letters + string.digits + '_'
 
 
 class Entity(object):
@@ -140,6 +141,10 @@ def put_annotation(self, key, value):
             log.warning("ignoring unsupported annotation value type %s.", type(value))
             return
 
+        if any(character not in _valid_annotation_key_characters for character in key):
+            log.warning("ignoring annnotation with unsupported characters in key: '%s'.", key)
+            return
+
         self.annotations[key] = value
 
     def put_metadata(self, key, value, namespace='default'):

docs/basic.rst

@@ -51,7 +51,8 @@ You can add annotations and metadata to an active segment/subsegment.
 Annotations are simple key-value pairs that are indexed for use with
 `filter expressions <http://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html>`_.
 Use annotations to record data that you want to use to group traces in the console,
-or when calling the GetTraceSummaries API.
+or when calling the GetTraceSummaries API. Annotation keys should only use ASCII letters, numbers, and
+the underscore(_) character.
 
 Metadata are key-value pairs with values of any type, including objects and lists, but that are not indexed.
 Use metadata to record data you want to store in the trace but don't need to use for searching traces.

tests/test_trace_entities.py

@@ -52,7 +52,8 @@ def test_put_annotation():
         'key2': 'value2',
     }
     # invalid annotation key-value pair should be dropped
-    segment.put_annotation('invalid', invalid)
+    segment.put_annotation('invalid_value', invalid)
+    segment.put_annotation('invalid-key', invalid)
     segment.put_annotation('number', 1)
 
     subsegment = Subsegment('sub', 'local', segment)
@@ -61,7 +62,8 @@ def test_put_annotation():
 
     doc = entity_to_dict(segment)
     assert doc['annotations']['number'] == 1
-    assert 'invalid' not in doc['annotations']
+    assert 'invalid-value' not in doc['annotations']
+    assert 'invalid-key' not in doc['annotations']
 
     sub_doc = doc['subsegments'][0]
     assert not sub_doc['annotations']['bool']