#17: Documentation for set_xray_log_group

CHANGELOG.md

@@ -13,6 +13,8 @@ Changed:
 * `@xray_task_async()` can be used to decorate methods and classmethods.
 * `@xray_task_async()` can set the path component of the synthetic URL.
 
+Added:
+* `set_xray_log_group()` process-level configuration function (non-async).
 
 ## v1.0.0 (2020-08-05)
 

README.md

@@ -53,6 +53,29 @@ using the `@xray_task_async()` decorator, like so:
     schedule_recurring_task(cleanup_stale_tokens)
 
 
+### Process-Level Configuration
+You can link your X-Ray traces to your CloudWatch Logs log records, which
+enhances the integration with AWS CLoudWatch ServiceLens. Take the following
+steps:
+
+1.  Put the X-Ray trace ID into every log message. There is no convention for
+    how to do this (it just has to appear verbatim in the log message
+    somewhere), but if you are using structured logging then the convention is
+    to use a field called `traceId`. Here's an example
+
+        trace_id = xray_recorder.get_trace_entity().trace_id
+        logging.getLogger("example").info("Hello World!", extra={"traceId": trace_id})
+
+1.  Explicitly set the name of the CloudWatch Logs log group associated with
+    your process. There is no general way to detect the Log Group from inside
+    the process, hence it requires manual configuration.
+
+        set_xray_log_group("/example/service-name")
+
+Note that this feature relies on undocumented functionality, and is
+[not yet](https://github.com/aws/aws-xray-sdk-python/issues/188)
+supported by the official Python SDK.
+
 ## Licence
 This project uses the Apache 2.0 licence, to make it compatible with
 [aws_xray_sdk](https://github.com/aws/aws-xray-sdk-python), the