aws / aws/aws-xray-sdk-node

`downstreamXRayEnabled` / `traced` property behavior doesn't seem to align with X-Ray documentation

Open
#493 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.