feat(tracer): add isTraceSampled method

[icholy]

Description of your changes

This change adds a new isTraceSampled method to Tracer. It lets users find out if the current trace is sampled or not. This information may be included in structured logs along with the Trace ID.

How to verify this change

Set the Sampled=1 flag in the _X_AMZN_TRACE_ID environment variable and assert that isTraceSampled returns true.
Example: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=557abcec3ee5a047;Sampled=1

Related issues, RFCs

Issue number: #1378

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding changes to the examples
• My changes generate no new warnings
• The code coverage hasn't decreased
• I have added tests that prove my change is effective and works
• New and existing unit tests pass locally and in Github Actions
• Any dependent changes have been merged and published
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[dreamorosi]

Hi @icholy thank you for taking the time to open this PR!

Please allow us some time to go through the changes and review the PR.

[icholy]

@dreamorosi seems like you have a very specific implementation in mind. I think it would be easier for both of us if you just added your commits on top of mine.

[dreamorosi]

Hey, sorry, my bad.

Should have left a comment instead of getting into the suggestions.

I'll delete the suggestion, and please allow me to elaborate why I made them.

At the moment, based on the discussion we had some time ago in the linked issue and also the existing implementation, we are relying on the order of the fields inside the environment variable.

In the past few weeks, especially after #1356, I think it'd be best to be more defensive when parsing the content of this environment variable and make sure we are not relying on the order of the fields or on the fact that some delimiter are present. Hence my suggestions.

My proposal would be to have the getXrayTraceData method return an object that has two fields root and sampled, both of undefined | string type.

In the body of the method, we could make a couple of additional checks while parsing:

• Check that xRayTraceEnv has a value & that expected delimiter (;) is present, if not, return undefined.
• Find the field that starts with Root=, if found: keep the value after =, if not consider it undefined
• Find the field that starts with Sample=, if found: keep the value after =, if not consider it undefined
• Return { root, sampled }

This way, the methods consuming the trace data can be more streamlined.

[icholy]

Your logic makes sense, but personally I think you're giving getXrayTraceData too much responsibility. It should only understand parsing the key/value syntax. IE: getXrayTraceData(): Record<string, string> | undefined .

So parsing Root=1-5759e988-bd862e3fe1be46a994272793;Parent=557abcec3ee5a047;Sampled=1 would result in an object like this:

{
  Root: "1-5759e988-bd862e3fe1be46a994272793",
  Parent: "557abcec3ee5a047",
  Sampled: "1"
}

For backwards compatibility, it would place the whole string in the Root key if it doesn't contain key/value pairs.

Then the getXrayTraceId and getXrayTraceSampled contain logic for interpreting the parsed data. So getXrayTraceData deals with syntax, and getXrayTraceId & getXrayTraceSampled deal with semantics.

[dreamorosi]

You're right, and thanks for hearing me out.

Let's go with your proposal, after this I'm looking forward to merge it right away.

[icholy]

@dreamorosi ready for another review round.

[dreamorosi]

I think there's one line/code branch not being covered by the tests

[dreamorosi]

Thank you for contributing the feature and for addressing the comments during the review!