Feature request: Add Event Handler Tracer Middleware

[svozza]

Use case

We should have a way of getting traces from HTTP routes in event handler so that the customer does not have to manually instrument their routes.

Solution/User Experience

We could create a middleware that behaves similarly to the Middy tracer middlware we currently have. A sample implementation could look like this:

export const tracerMiddleware = (tracer: Tracer, options?: {captureResponse?: boolean}): Middleware => {
    const {captureResponse = true} = options ?? {};
    
    return async ({ reqCtx, next }) => {
        const url = new URL(reqCtx.req.url);
        const subsegment = tracer.getSegment()?.addNewSubsegment(url.pathname);
        subsegment && tracer.setSegment(subsegment);
        tracer.annotateColdStart();
        tracer.addServiceNameAnnotation();
        try {
            await next();
        } catch(err) {
            tracer.addErrorAsMetadata(err as Error);
            subsegment?.close();
            subsegment && tracer.setSegment(subsegment.parent);
            throw err;
        }
        if(captureResponse && reqCtx.res.headers.get('Content-Type') === 'application/json') {
            const responseBody = await reqCtx.res.clone().json() ?? {};
            tracer.addResponseAsMetadata(responseBody);
        }
        subsegment?.close();
        subsegment && tracer.setSegment(subsegment.parent);
    }
}

Open questions:

1. Should the middleware take multiple tracer instances like our Middy one does?
2. Should the logic around capturing responses be more complex, i.e., should we disallow it when we are in streaming mode? This would require us to add data to reqCtx to indicate when we are in HTTP streaming mode.

Alternative solutions

We could tell users to use the Middy tracer middleware.

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[arnabrahman]

Hi, i am interested. After going through the code i can try answering your questions:

1. Keep it to one Tracer instance only. The middy tracer described in the doc only takes one tracer instance, here. Not sure which one you are talking about. Also i can't think of a valid use case where i would like to trace the same operation to multiple X-Ray services or configurations. If we need a separate trace, it can be done on the route level

app.get('/payments', 
  tracerMiddleware(paymentTracer),   // Specific route traced by payment tracer
  paymentHandler
);

app.get('/audit', 
  tracerMiddleware(auditTracer),     // Different route traced by audit tracer
  auditHandler
);

2. It's better to keep the streaming part out of it. Some complexities related to this

• Stream is consumed once, so we have to buffer it if we want to capture it for tracing. Buffering also defeats the purpose of streaming
• If we close the segment after the middleware completes, this will create incomplete/misleading timing information, as the actual stream still flows after the middleware completes.

Even if we want to capture tracing for streaming, maybe keep the body capture out of it.

Personally i would prefer not to add another dependency (middy), just to have this tracing. So, better to have a simpler solution

And your code suggestion is solid, i will add some improvements:

• We should add the is tracing-enabled check.
• For segment naming, using ${method} ${pathname} (e.g., "GET /users") instead of just pathname makes it easier to distinguish routes with different methods
• addResponseAsMetadata method needs a method name, the metadata will print undefined response. We can provide ${method} ${pathname} here

[dreamorosi]

Hi @arnabrahman, nice seeing you again and happy new year 👋

Well done with the analysis, I agree with your suggestions. I have assigned the issue to you, we can continue iterating in the PR review phase, and as usual - we're here if you have additional questions.

[powertools-for-aws-oss-automation]

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.