Can someone provide a working example of using aws-sdk-xray for tracing?

[mblarsen]

Examples are available for many services and operations, check out the examples folder in GitHub.

As far as I can tell there are no xray examples in the examples folder.

For context I'm trying to build a Axum X-Ray middleware to be able to trace incoming request.

This is what I've done so far.

Set up client:

    let xray_config = aws_config::from_env()
        .app_name(AppName::new("tfff-api").expect("AppName should be valid"))
        .load()
        .await;
    let xray_client = aws_sdk_xray::Client::new(&xray_config);

and according to the docs I should use builders to create documents and then finally call the relevant method on the client like so:

            // Send the Segment to AWS X-Ray
            let _ = self.xray_client
                .put_trace_segments()
                .trace_segment_documents(...)  // something that implements Into<String>
                .send()
                .await
                .unwrap();

However, what I fail to understand is what builders are required to use in between. My best bet is a combination of types::builders and operation::put_trace_segments::builders.

Some types that seems relevant:

• types::builders::HttpBuilder: capture information about http requests
• types::builders::SegmentBuilder: however, it seems very limiting in what data you can add to it. E.g. no start- and end-time. It takes documents which are something that turns into String. What is this used for?
• types::builders::TraceBuilder: this builder creates a Trace and you can set a duration along with Segments, but not start- and end-time here either
• types::builders::TraceSummaryBuilder: This builder seems to capable of registering many aspects, e.g. the Http type can be included here, and annotations can be added as well.

Also I fail to understand how to create a root and sub segments. The type descriptions are also a bit confusing to me. Segment description is worded in away that is mainly used for reading from the api:

A segment from a trace that has been ingested by the X-Ray service. The segment can be compiled from documents uploaded with PutTraceSegments, or an inferred segment for a downstream service, generated from a subsegment sent by the service that called it.

This leads me to think that I don't use Segment when tracing.

            let http = HttpBuilder::default().http_url(http_url).http_method(http_method).build();
            let segment = SegmentBuilder::default().id(generate_segment_id()).build();
            let trace = TraceBuilder::default().id(generate_trace_id()).segments(segment).build();
            let trace_summary = TraceSummaryBuilder::default().http(http).id(generate_trace_id());

Fail to see the point of Trace and Segment and also the point of setting duration, when it could be calculated by start and end time? Is it because you don't always have an end time so duration would be now - start?

Disclaimer, I may lack some basic tracing knowledge.

[Velfi]

@DavidSouther Did you ever come up with an example for this? I feel like you did but I don't recall.

[DavidSouther]

Not using aws_sdk_xray, it was using a tracing library for actix (and I didn't ever get it working). We can take the feature request at https://github.com/awsdocs/aws-doc-sdk-examples/issues/new?assignees=octocat&labels=type/enhancement&projects=&template=enhancement.yaml&title=%5BEnhancement%5D:+%3CDESCRIPTIVE+TITLE+HERE%3E but XRay isn't on our roadmap at this time.

[mblarsen]

I can create a request for sure, but any kind of guidance to how it should work then I can probably figure it out.

I would be happy to create an example PR afterwards.

[DavidSouther]

You've probably seen these, but to get us on the same page here-

From the xray glossary It looks like we're focusing on Segments and Traces.

The developer guide has a couple examples of segments for PutTraceSegments. Those are JSON-formatted strings.

From here I think we should read the API docs which says "yo give us some documents". These are the segment documents we saw in Sending Data. So we want to create that document in JSON.

Let's move over to the Rust specifics. The most important thing to keep in mind is that everything is generated dynamically from the published modules from the service. Nothing in the service-specific XRay SDK is designed by hand. It's a small note, but at the top of aws_sdk_xray::types, it says "Data structures used by operation inputs/outputs." (I think the "Outputs" side is going to be very important here.) Let's look at Segment, and its references in github. It's not used by anyone. That is, no XRay SDK operations take a Segment for their inputs. The only place a Segment shows up is in a Trace, and the only place a Trace shows up is in the BatchGetTracesOutput.

This is an unfortunately common train of exploration in the generated SDKs. The exposed types from the model are 1:1 for the service' output, and many services in AWS specify their shapes as "A string" when they expect that string to be some document. Without a published model for what goes in that document, you the developer are left with creating that string yourself.

So, do not try to use the Builders that are exposed for the operation outputs in this SDK. You will need to create the string yourself. Hand craft it, write your own Trace & Segment types with their own serialization logic, whatever - the xray service hasn't provided enough information in their model to generated code to build an accurate Trace or Segment. There is documentation on what is allowed in a Segment in the API docs. Other languages have handwritten code. But, the CLI is in the same place as Rust and needs the hand-rolled document. AIUI, the Rust SDK team does not have capacity to provide custom functionality to any SDKs at this time.

---

OK that's all very disheartening, but there is good news! There's a vibrant rust opentelemetry project, and they have an exporter for AWS & XRay. And, of course, there's an axum middleware for open telemetry.

So I'm sorry we can't give you a happier story around using the XRay SDK to directly write to AWS, but hopefully the opentelemetry projects can obviate your need for this particular tool & issue.

[mblarsen]

Thank you for the detailed reply @DavidSouther 🥇