Feature request: correlation ID's propagation

[saragerion]

Description of the feature request

Problem statement
The use of correlation ID's can be extremely helpful for debugging purposes and help developers understanding the lifecycle of user transactions as they are being handled by different microservices within a platform.
It would be good to help developers understand how they can use correlation ID's effectively and following the best practices, potentially allowing them to bring their own custom correlation ID's, and most importantly propagate correlation ID's through the different utilities to external dependencies of a service. This can be achieved through the implementation of a new dedicated utilities, new features within all utilities, adding examples and/or documentation.

For the scope of this Issue, we can identify 2 types of correlation ID's:

1. Unique transaction ID that are set by AWS (for example X-Ray Trace Id, AWS Request Id)
2. User-defined correlation ID's that can be stored and passed along between microservices:

• SNS - Message attributes https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/tests/resources/events/aws/sns-notification.json#L18
• CloudFront - Request headers https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/tests/resources/events/aws/cloudfront-modify-querystring.json#L13
• API Gateway - Headers https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/tests/resources/events/aws/apigateway-aws-proxy.json#L21
• Others...

Summary of the feature
All utilities would be able to fetch out of the box correlation ID's coming from each different AWS service (Lambda Trigger), and propagate them to logs, metrics, traces, ....
Note that this feature and functionality should not necessarily be enabled by default, but it should be possible to enable it and turn it on if developers need it.
It should be also possible to define your own custom correlation ID's and be able to propagate them and use them in different utilities accordingly.

Implement this logic in all utilities. Research is needed to understand the best implementation strategy, how to not do code repetition.

Code examples

TBC. Happy to receive suggestions on this one.

Benefits for you and the wider AWS community
As discussed in a past meeting with @gsingh1 @loujaybee and @simontabor, the functionality of fetching and propagating correlation ID's, including custom user-defined ones, can be useful and especially relevant for developers who operate at scale and within big organisations, where you have a high number of teams responsible for microservices communicating to each other.

Describe alternatives you've considered

None that comes into mind apart from writing the code by yourself.

Additional context
See here a brief definition of a correlation ID.

Related issues, RFCs

Not at the moment.

[dreamorosi]

In the case of tracing, should this ID in the name of the segment or as an annotation of the segment?

[saragerion]

Thanks for asking @dreamorosi, I envision it/them as an annotation(s) of the segment

[bahrmichael]

My thoughts on the problem statement:

how they can use correlation ID's effectively and following the best practices

I don't think I'm familiar with the best practices yet. Will collect more info on the way. If you know any good links, please link them in this issue :)

potentially allowing them to bring their own custom correlation ID's

This sounds like we can start with an MVP where we generate our own correlation ID, and then expand to allow a custom ID.

achieved through the implementation of a new dedicated utilities

This sounds like we would have a package like powertools/correlation. When reading this issue I first though about some relation to the logger utility, as that's where I'd expect the correlation ID to be printed so that customers can use them. But tracing also makes sense, when you want to follow the path of a request. Metrics as well as you want to know if a particular request caused e.g. latency spikes. Looks like I'm back to agreeing that this requires a cross-utility approach.

[bahrmichael]

Updated the comment above, as it accidentally showed my comment as part of the quote.

[bahrmichael]

For metrics I think outputting the correlation ID into metadata makes sense.

For logs I'd follow the correlation example in additional-keys.ts.

[saragerion]

See here: https://github.com/getndazn/dazn-lambda-powertools#did-you-consider-monkey-patching-the-clients-instead
https://github.com/getndazn/chaos-squirrel/blob/master/packages/attack-http-requests/src/index.ts#L25

[bahrmichael]

In our sync Lou raised the idea of monkey patching:

• https://github.com/getndazn/dazn-lambda-powertools#did-you-consider-monkey-patching-the-clients-instead
• https://github.com/getndazn/chaos-squirrel/blob/master/packages/attack-http-requests/src/index.ts#L25