diff --git a/CHANGELOG.md b/CHANGELOG.md index 01a104a..a351b2b 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/README.md b/README.md index 59df2ee..03a6545 100644 --- a/README.md +++ b/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