`downstreamXRayEnabled` / `traced` property behavior doesn't seem to align with X-Ray documentation
- Dominant language
- JavaScript
- Stars
- 280
- Forks
- 157
- PR merge metrics
- No merged PRs in 30d
Description
Hello, I'm confused about the behavior of the `downstreamXRayEnabled` parameter to `captureHTTPsGlobal`. The documentation and behavior seem aligned that when `true`, a top-level `traced: true` property is created on the subsegment.
However, the [AWS X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html) documentation only documents `traced` as a property of the `http.request` object of subsegments. Whereas the SDK seems to [explicitly move it](https://github.com/aws/aws-xray-sdk-node/blob/f9c25f4b30e06bd0d7abddb8b279cc5db1944dcc/packages/core/lib/segments/attributes/subsegment.js#L229-L230) from there to the top-level of the subsegment.
Can you please clarify the difference between that documentation and the behavior here?
Also, in practice, I can't observe a meaningful difference between `downstreamXRayEnabled: false` (or omitted) and `downstreamXRayEnabled: true`. In the `true` case I can see a top-level `traced: true` property on the subsegments in the raw trace data, but I can't observce a difference in the trace as displayed in the console either for a request to an instrumented service or a non instrumented external service (a subsegment that winds up with `inferred: true`).
It's also not clear what the segment documents documentation means by:
> [...] X-Ray considers the trace to be broken [...]
Contributor guide
Research direction
Start with packages/core/lib/segments/attributes/subsegment.js at the linked lines, then compare its traced-property handling with the AWS X-Ray segment documents. Reproduce captureHTTPsGlobal behavior with downstreamXRayEnabled omitted, false, and true, including instrumented and external requests, and document the distinction and expected console or raw-trace result.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, javascript, node.js
- Domain
- observability-sre
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100