Aws-xray-sdk-node: Docs are confusing when using lambda without express

[kbradl16]

Hello, I am having a hard time figuring out xray for my lambda module, I do not create any subsegments and am using only the captureHTTPsGlobal to get request information and tracing, currently struggle buss'n through adding annotations and enabling xray for local development and testing.

Another issue i'm seeing is in xray I do not see any urls or methods displayed on the UI view but they do appear in the metadata.

Do I need to create a subsegment? If so do I need to close each subsegment? Are there any best practices for using the captureHTTPsGlobal or gotchas?

Another query or point of confusion I have is that I already have a separate unique v4uuid for my codebase that I use for logging and saving my data. I was hoping to be able to tie that in with xray and be able to view all parts of my system by the same v4uuid I already generate. Whats the best way to include this (annotation?). I was hoping it'd be as simple as giving the segment or subsegments that id when I create them (or by having the same parent id). Is there a common/global way to use my uuid or do I have to add it to every subsegment? How can I add it to the global http capture?

The docs state: "Currently, only Express applications are supported for automatic capturing. See the aws-xray-sdk-express package for additional information." - https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core. Is that accurate anymore?

It would be great to have some generic examples for lambdas without express. A lot of the docs seem to only reference express but there is a separate express module and readme. It'd be great if all the express examples were moved there. The docs also seem to be missing information on lambdas in general and how they initialize a root segment by default and they should only be used with Automatic mode.

Should there be an lambda package? With examples and docs? or should it be in core? (I'd love to give this a start but I'll need to request permission from my company first, does this resonate at all or am I completely offbase here?)

Thank you in advance!

[willarmiros]

Hi @kbradl16,
Please see these docs for a quick run through of using the X-Ray SDK for Node in a Lambda function and these docs about captureHTTPsGlobal. We currently have a backlog item to add a more detailed sample Lambda app to that first link that includes captureHTTPsGlobal among other things.

To add some additional context, captureHTTPsGlobal will automatically generate a subsegment for all requests that you make with the captured protocol (http, https, or both). This also works for requests made via 3rd party libraries since they ultimately use one of those libraries under the hood.

You are right that the documentation for the repo is misplaced right now. We currently do support Lambda, and only the core package is needed to instrument a Lambda function. This repo was created before X-Ray's integration with Lambda was released, and the docs don't reflect that well. I'll make a note to update them on GitHub when we also update them on https://docs.aws.amazon.com.

An annotation would be the best way to associate such an ID with (sub)segments. Unfortunately in Lambda, a segment is automatically generated for you, but it is implemented as an immutable facade segment. It is immutable because the true segment representing Lambda requests is made by the Lambda service and not available to application code. Only subsegments can be modified, e.g. with addAnnotation.

There's no way to currently to perform some action for all segments/subsegments, though we've added that functionality to the Java SDK and are working on bringing it to the other SDKs. In the meantime, you'll have to retrieve the subsegment manually, e.g. with:

const subs = AWSXRay.getSegment().subsegments;

if (subs && subs.length > 0) {
  let sub = subs[subs.length-1];
  sub.addAnnotation('myKey', 'myVal');
}

[kbradl16]

I can work on getting a sample lambda app example together and moving the docs around if you can give some general guidance on where it should live?!

[willarmiros]

If you'd like to make a sample Lambda app, that'd be great! We want to expand upon the sample app on this page to include:

1. An HTTP request (e.g. to https://amazon.com) captured using captureHTTPsGlobal
2. An AWS SDK request (e.g. s3.listBuckets()) captured using captureAWS (this is currently the only thing included in the sample app)
3. A SQL query (using mysql or postgres) captured using their respective
4. A function (async or regular depending on your handler) captured using captureFunc or captureAsyncFunc. The captured function can perform one or more of the above tasks if you'd like.
5. A screenshot of the resulting trace map similar to the one on the page right now.

As for the repo's documentation, it'll be a little more involved refactoring so I'll stick to that one.

[willarmiros]

Hi @kbradl16,

279 added documentation regarding usage in Lambda, and more directly pointed to the official AWS Documentation. Do you still plan on contributing a sample app? If so, it could be open sourced as a contribution to our new sample app repository. Currently it only has an express sample app, but I'd be open to adding your Lambda sample app in a separate directory if you made a PR in that repo.

[kbradl16]

Hi, @willarmiros I do still plan on contributing a sample app unless someone gets to it before me (I’ve just had a newborn born this month so I’m not actively doing any development at the moment) I’ll add it to the sample repo

[willarmiros]

Incredible, and congratulations! No worries, I'll leave you to it :)