Is it possible to output traces locally

[kaykhan]

I am in the middle of a project and i am attempting to add custom traces to a ORM (Prisma) we are using. Ive deployed this change and tested it live but i can't see this trace.

Unfortunately due to the nature of this stack i can't easily make a loop to make change and redeploy to test these changes.

Is there some way i can output the trace data locally to a .json file?

prisma.service.ts

export const PrismaService = new PrismaClient({
    log: EnvironmentConfig.ENVIRONMENT !== "production" ? ["query", "info", "warn", "error"] : [],
}).$extends({
    query: {
        async $allOperations({ model, operation, args, query }) {
            const parentSubsegment = Tracer.getSegment();
            let subsegment;
            if (parentSubsegment) {
                subsegment = parentSubsegment.addNewSubsegment("### SQL Query");
                Tracer.setSegment(subsegment);
            }

            Tracer.putMetadata("model", model);
            Tracer.putMetadata("operation", operation);
            Tracer.putMetadata("args", args);
            const start = performance.now();
            const result = await query(args);
            const end = performance.now();
            const time = end - start;
            Tracer.putMetadata("time", time);

            if (parentSubsegment && subsegment) {
                subsegment.close();
                Tracer.setSegment(parentSubsegment);
            }

            return result;
        },
    },
});

[dreamorosi]

Hi @kaykhan, thanks for opening this discussion.

Generally speaking, you should be able to instruct the underlying X-Ray SDK to emit logs by using the tracer.provider.setLogger() constructor as described in our docs here. The page I linked shows how to use our Powertools Logger, but you can also use the regular console.log by passing an object with this shape:

var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

Once you set a logger, the X-Ray SDK will emit a number of logs, including one emitted here that logs a segment right before it's sent.

With that said, when running outside of Lambda, the Tracer utility disables itself, which means segments are not emitted. This is described at the top of our documentation (see last point of Key features). This limitation can be traced back to the fact that the X-Ray SDK expects a number of things to be present in the environment to be able to work, namely a parent segment and an X-Ray daemon to send segments to. Both of these things are provided by the Lambda service behind the scenes, which makes it hard to reproduce locally.

If you are trying to assert the content/shape of a segment I would recommend to approach the problem from a different angle and write a test instead.

Below a simplified example of how you'd go about testing the content of a segment.

import { Tracer } from "@aws-lambda-powertools/tracer";

const tracer = new Tracer();

describe("Tracer tests", () => {
  test("default log level is 12 (INFO) when none is passed", async () => {
    // Prepare
    const subsegment = tracer.getSegment()?.addNewSubsegment("mySubsegment");

    // Act
    subsegment?.addAnnotation("someKey", "someValue");
    subsegment?.addMetadata("someMetadata", { foo: "bar" }, "my-namespace");

    // Assess

    // Serialize the subsegment to a string, then parse it to a JSON object
    // this way we get only the items that would actually be sent to X-Ray
    // rather than the entire Subsegment object
    const finalSubsegment = JSON.parse(subsegment?.toString() || "{}");
    expect(finalSubsegment.annotations.someKey).toBe("someValue");
    expect(finalSubsegment.metadata).toStrictEqual({
      "my-namespace": {
        someMetadata: {
          foo: "bar",
        },
      },
    });
  });
});

for reference, the shape of the finalSubsegment object from the example above is the following:

{
  "id": "1d0b92c8a653ed4d",
  "name": "mySubsegment",
  "start_time": 1707322506.735,
  "in_progress": true,
  "notTraced": false,
  "annotations": {
    "someKey": "someValue"
  },
  "metadata": {
    "my-namespace": {
      "someMetadata": {
        "foo": "bar"
      }
    }
  }
}

Note that with the subsegment?.toString() method you're getting the content of the segment even if the tracer is disable or it's not being sent, so if you don't like the suggestion above you could just work with that in your code.

Also, a couple of as an unrelated notes:

Segments in X-Ray already have a notion of start_time and end_time. The first one is the timestamp of when the segment was created, the second one gets populated when you call segment.close(). With these two X-Ray is able to determine the duration (and length in the visualisation) of the segment, so depending on what you're trying to achieve with the time key in the metadata, it might be redundant.

Additionally, X-Ray segments have a hard size limit of 64kb. I don't know what's the content of the model, operation, and args in your code but you might want to keep in mind the limitation when adding things. If a segment is too big it will be discarded and you'll lose it.

[kaykhan]

appreciate the reply, thank you