X-Ray cannot be enabled on API Gateway event source

[lorchda]

Description

Given:

• A AWS::Serverless::Function
• An API Event Source

then it is no possible to enable X-Ray tracing on the API Event Source.

Steps to reproduce

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  Wild Rydes Asynchronous Messaging Workshop - Lab 2
  
# More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
Globals:
  Function:
    Timeout: 10
    Runtime: python3.9
    Tags:
      project: wild-rydes
      workshop: asynchronous-messaging-workshop
      author: aws

Resources:
  SubmitRideCompletionFunction:
    Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
    Properties:
      CodeUri: unicorn-management-service/
      Handler: app.lambda_handler
      Tracing: Active
      Events:
        WildRydes:
          Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
          Properties:
            Path: /submit-ride-completion
            Method: post

Full source code: https://github.com/aws-samples/asynchronous-messaging-workshop/blob/master/code/lab-2/template.yaml

Observed result

With Tracing: Active set on the AWS::Serverless::Function, the Lambda function has X-Ray tracing enabled.

But the generated API Gateway does not have X-Ray tracing enabled. It is not possible to enable X-Ray tracing on the API Gateway event source, as there is no corresponding parameter for it available.

Expected result

Suggestions:

1. Provide a Tracing parameter to allow enabling X-Ray for the API Gateway event source
2. Given that I have enabled tracing on the Lambda function, SAM could infer that I also want it enabled on my event sources and could auto-enable X-Ray tracing on the API Gateway.

Additional environment details

1. OS: macOS Monterey 12.6.3
2. If using the SAM CLI, sam --version: SAM CLI, version 1.53.0
3. AWS region: eu-central-1

[lorchda]

We found out that X-Ray tracing needs to be enabled on the respective stage. The corresponding code would look like the one below.

However, this overrides the automatically created stages Prod and Stage, so might not be the ideal solution.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  Wild Rydes Asynchronous Messaging Workshop - Lab 2
  
# More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
Globals:
  Function:
    Timeout: 10
    Runtime: python3.9
    Tags:
      project: wild-rydes
      workshop: asynchronous-messaging-workshop
      author: aws

Resources:
  SubmitRideCompletionFunction:
    Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
    Properties:
      CodeUri: unicorn-management-service/
      Handler: app.lambda_handler
      Environment:
        Variables:
          TABLE_NAME: !Ref RidesTable
          TOPIC_ARN: !Ref RideCompletionTopic
      Policies:
        - DynamoDBCrudPolicy: # https://github.com/awslabs/serverless-application-model/blob/develop/samtranslator/policy_templates_data/policy_templates.json
            TableName: !Ref RidesTable
        - SNSPublishMessagePolicy: # https://github.com/awslabs/serverless-application-model/blob/develop/samtranslator/policy_templates_data/policy_templates.json
            TopicName: !GetAtt RideCompletionTopic.TopicName
      Tracing: Active
      Events:
        WildRydes:
          Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
          Properties:
            Path: /submit-ride-completion
            Method: post
            RestApiId: !Ref SubmitRideCompletionApi

  SubmitRideCompletionApi:
    Type: AWS::Serverless::Api
    Properties:
      TracingEnabled: true
      StageName: Prod

[ssenchenko]

To the first part of your question:
The idea behind Api Source Event is to connect a Function and an Endpoint which triggers that Function. Though all Api Source Events defined in the same template file without RestApiId are merged into a single REST Api, it's not a recommended way to manage an Api. Tracing is an attribute of API stage, and that's why should be set on API resource, as you've discovered.

To the second part of your question:
The way Stage works with AWS::Serverless::Api resource is described here. Generally, if you need a lot of flexibility, you can use original CloudFormation resources, including Stage. The purpose of Serverless resources is to simplify CloudFormation abstractions sacrificing some flexibility, which is not necessary in many cases.

[lorchda]

Hi @ssenchenko

Got it, that makes sense. Would it be possible to highlight it in the documentation on how to enable X-Ray for the Api event source? It did not seem very obvious to me at first.

On a related note, how would I enable X-Ray for all of the other event sources that support tracing (SQS, SNS etc.)? There does not seem to be a corresponding Tracing flag available for those items in https://github.com/aws/serverless-application-model/blob/master/versions/2016-10-31.md#event-source-types respectively https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-function-eventsource.html

I understand I could go the CloudFormation route and manually define those resources, but I would not be able to use the event source short-hand notation from SAM?

[ssenchenko]

How would you rephrase the documentation or what would you add to make it clearer and intuitive? Your feedback is more important than whatever our team can add because you've had a problem with that part of the docs.

As for SQS, SNS etc. the philosophy is the same as for Api. Event source merely connects function and an event in an intuitive way. Event source can generate an underlying resource or its part ie Api or SQS subscription for SNS event, but its configuration will be minimal. Sometimes, it's exactly what people need, for example while prototyping or for those who has just started with serverless and infrastructure as code. When full configuration is necessary, reference to an event source resource is the way to go. The way you did it for Api. For SQS for example Queue ARN is a required attribute anyway. For SNS Topic ARN is required and it's possible to pass Queue ARN for Subscription.

[lorchda]

Hi @ssenchenko

I understand the value of event sources and that they provide a short-hand notation to conveniently create underlying resources with minimal configuration. What might be counter-intuitive is that many of the SAM resources like AWS::Serverless::Api and AWS::Serverless::Function do offer a TracingEnabled flag, but event sources do not, at least not directly.

What might add value is to capture the conversation here and add it to the documentation. The following would be my proposal:

• Add a section to the page https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-function-eventsource.html

Enabling tracing with AWS X-Ray

Event sources provide a convenient method to connect the function to an event in an intuitive way. Enabling AWS X-Ray tracing for the Api event source requires obtaining a reference to the underlying resource as described in the respective page, so that tracing can enabled on it. To enable AWS X-Ray tracing for other resource types that are defined outside of the scope of the event source (e.g. an Amazon SNS topic), please refer to the respective standard CloudFormation definitions and parameters.

• Add a section to the page https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-function-api.html

Enabling tracing with AWS X-Ray

AWS X-Ray tracing needs to be enabled on the respective API stage. To obtain a reference to the stage, use the RestApiId parameter on the Api event source type.

YAML

TraceableFunction:
  Type: AWS::Serverless::Function
  Properties:
    Events:
      ApiEvent:
        Type: Api
        Properties:
          Path: /path
          Method: get
          RestApiId: !Ref TraceableFunctionApi

TraceableFunctionApi:
  Type: AWS::Serverless::Api
  Properties:
    TracingEnabled: true
    StageName: Prod

None of the other event source types seem to be concerned when it comes to enabling AWS X-Ray active tracing. For example, the SNS event source just provides a shorthand notation for an SNS subscription. The AWS::SNS::Topic resource itself is declared as plain CloudFormation outside of the SAM context.

[lorchda]

From a developer perspective, this is what might be considered as inconsistent:

• There is a TracingEnabled flag for the AWS::Serverless::Api resource type
• There is no TracingEnabled flag for the corresponding Api event source

When using AWS::Serverless::Api, then tracing has to be enabled on the Api itself. When using the Api event source on the other hand, then tracing has to be enabled on the underlying stage.

There is a corresponding TracingEnabled flag in the globals section for the Api resource. But it only seem to apply to dedicated AWS::Serverless::Api definitions, and not Api event sources.

In the example below, tracing is NOT enabled on the API gateway:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  Wild Rydes Asynchronous Messaging Workshop - Lab 2
  
# More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
Globals:
  Function:
    Timeout: 10
    Runtime: python3.9
    Tags:
      project: wild-rydes
      workshop: asynchronous-messaging-workshop
      author: aws
  Api:
    TracingEnabled: true # <-- does NOT apply to event source "Api". Applies only for dedicated AWS::Serverless::Api definitions

Resources:
  SubmitRideCompletionFunction:
    Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
    Properties:
      CodeUri: unicorn-management-service/
      Handler: app.lambda_handler
      Environment:
        Variables:
          TABLE_NAME: !Ref RidesTable
          TOPIC_ARN: !Ref RideCompletionTopic
      Policies:
        - DynamoDBCrudPolicy: # https://github.com/awslabs/serverless-application-model/blob/develop/samtranslator/policy_templates_data/policy_templates.json
            TableName: !Ref RidesTable
        - SNSPublishMessagePolicy: # https://github.com/awslabs/serverless-application-model/blob/develop/samtranslator/policy_templates_data/policy_templates.json
            TopicName: !GetAtt RideCompletionTopic.TopicName
      Tracing: Active
      Events:
        WildRydes:
          Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
          Properties:
            Path: /submit-ride-completion
            Method: post