DEV Community: Lorenzo Hidalgo Gadea

Mastering DynamoDB: Batch Operations Explained

Lorenzo Hidalgo Gadea — Wed, 16 Oct 2024 12:46:48 +0000

TL;DR; This article covers the usage of DynamoDB BatchWrite and BatchGet operations, and how implementing them can help you improve the efficiency by reducing the amount of requests needed in your workload.

Introduction

Have you ever developed any type of workload that interacts with DynamoDB?

If so, you probably have encountered the requirement of retrieving or inserting multiple specific records, be it from a single or various DynamoDB tables.

This article aims to provide you with it by providing all the required resources and knowledge to implement the usage of DynamoDB batch operations and, as a bonus point, increase the efficiency of your current workloads.

What are Batch Operations?

Introduction

When talking about batch operations or batch processing we refer to the action of aggregating a set of instructions in a single request for them to be executed all at once. In terms of interacting with DynamoDB, we could see it as sending a single request that would allow us to retrieve or insert multiple records at once.

Common Bad practices

Continuing with the sample situation mentioned in the introduction, you may face the requirement of having to retrieve or store multiple records at once.

For that scenario, most junior developers might rely on looping over a set of keys and sending the GetItem requests in sequence or a mid-level developer might propose to parallelize all those requests using for example a Promise.all, but both approaches are flawed and wont scale well.

On one side, the for-loop will even be detected by some linters (with rules like no-await-in-loop) as this implementation would increase the execution time exponentially.

On the other side, the Promise.all approach will be a tad more efficient by parallelizing the requests, but with high workloads, developers would end up facing issues like the maximum connection limit reached error.

Recommended Implementation

Now that we have gone over some bad practices in implementing it and that you have probably thought of a few projects that could be improved, well dive into how we can take the most advantage of it.

DynamoDB offers two different types of operations BatchGetItem and BatchWrtieItem which we will take a look into as part of this article.

There is also BatchExecuteStatement for those using PartiQL, but we will leave that one for a future article to cover PartiQL in detail.

BatchGetItem

This operation type will allow us to aggregate up to the equivalent of 100 GetItem requests in a single request.

Meaning that with this operation we could retrieve up to 100 records or 16 MB from a single or multiple table at once.

BatchWriteItem

💡PutRequests will overwrite any existing records with the provided keys.

This operation, even if it only contains write as part of its name, will allow us to aggregate up to 25 PutItem and DeleteItem operations in a single request.

Similar to the previous option, well still be limited by the 16 MB maximum, but we would theoretically be able to replace 25 sequential or parallel requests with a single one.

Pagination for Batch operations

Pagination is only valid for the 16 MB limit if the requests dont follow the 100 record read or the 25 record write limit DynamoDB will throw a ValidationException instead.

Similar to the Scan and Query operations, using any of the above Batch*Item operations can incur in the scenario where the 16 MB maximum is reached and some type of pagination is required.

For Batch* operations this comes in the form of the UnprocessedKeys attribute that can be part of the response.

Developers are expected to check for this attribute in the response and, if desired, implement its usage as a recursive function to process them automatically.

Full examples for Retrieving, Inserting, and Deleting records using BatchOperations with a recursive implementation to automatically handle the UnprocessedKeys can be found here.

Real-world Use Cases

Now that we are aware of all options and limitations regarding how we can process records in batch in DynamoDB, lets see some scenarios that will showcase some real-life improvements.

Scenario 1: Retrieving Data from Multi-table Design Architecture

For this first scenario, lets imagine we are looking to improve the performance of a REST API that, given an array of productId, will return us the list of desired product details with their respective stock and exact warehouse location. The data is stored in multiple tables, one for each data model (products, stock tracking, and warehouse product location).

Before

The initial implementation was developed by having a for-loop to go over all the provided productIds and sequentially retrieve all the required data from the different tables.

After

From that initial implementation, you should be able to detect two distinct flaws:

no-await-in-loop - There is a loop with asynchronous operations inside, which is usually a bad practice, as all operations for a given operation will need to be completed before the next one can start.
Sequential await getItem requests - This is also a bad practice, as the three operations are independent from each other and wed ideally not want for them to be blocked by each other.

A better approach would look something like this:

Input Validation - Set a limit of maximum items to be requested to avoid requiring parallel BatchGetItem requests.

For example - max. 100 items per BatchGetItem request and every product requires 3 GetItem requests means that a single BatchGetItem request can retrieve up to 33 product details.
Build Payloads - a helper function will be needed to programmatically build the required payload for the BatchGetItem operations taking into consideration the different tables that need to be accessed for each product ID.
Recursive BatchGetItem - a helper function that recursively calls itself to ensure that all UnprocessedKeys are retried.
Response parsing - a helper function that transforms the BatchGetItem response to the given schema that the consumers are expecting for this API

Applying all these changes should significantly increase the efficiency and performance of the API.

Scenario 2: Inserting Data in a Single-table Design Architecture

The second scenario would imply a DynamoDB single table design architecture where we have a single table to store all the information needed for a Dashboard to analyze racehorses historical data. Records such as basic horse information, performance statistics, and race results are stored in the same table.

Before

Similar to the first scenario, we can see that the initial implementation is based on a set of sequential PutItem requests.

After

From that initial implementation, you should be able to detect two distinct flaws:

no-await-in-loop - There is a loop with asynchronous operations inside, which is usually a bad practice, as all operations for a given operation will need to be completed before the next one can start.
Sequential await putItem requests - This is also a bad practice, as the three operations are independent from each other and wed ideally not want for them to be blocked by each other.

A better approach would look something like this:

Build Payloads - a helper function will be needed to programmatically build the required payload for the BatchGetItem operations taking into consideration the different tables that need to be accessed for each product ID.
Recursive BatchWriteItem - a helper function that recursively calls itself to ensure that all UnprocessedKeys are retried.

Applying all these changes should significantly reduce the required time to upload all information.

Conclusion

Utilizing batch operations in DynamoDB is a powerful strategy to optimize your database interactions. By aggregating multiple requests into a single operation, you can improve performance, reduce latency, and manage resources more effectively. Whether you're dealing with multi-table architectures or single-table designs, batch operations offer a scalable solution to handle large volumes of data efficiently. As you continue to work with DynamoDB, consider integrating batch operations into your workflows to maximize the potential of your applications.

Recap of key points

BatchGetItem can retrieve up to 100 records or 16 MB of data in a single request.
BatchWriteItem can be used to insert or delete up to 25 records or 16 MB of data in a single request.
Using Batch* operations can help you reduce the execution time considerably by aggregating requests that were currently being done in sequence.

Additional resources and references

Enhance Your AppSync API Development: Easy Steps to Auto-Generate Postman Collections

Lorenzo Hidalgo Gadea — Fri, 15 Mar 2024 11:32:01 +0000

TL;DR;

This article covers how developers can take advantage of the serverless-gql-generator plugin for Serverless Framework to automatically generate new Postman Collections or Raw Requests for an AppSync API.

Introduction

A few weeks ago, I announced the release of a new Serverless Framework Plugin that I had been working on called serverless-gql-generator.

The idea for this plugin came from the difficulties faced during one of my projects where it was too time-consuming for developers to keep the sample requests and Postman Collection for every new schema update. This pain point was further intensified when we started to develop multiple interdependent AppSync APIs simultaneously, requiring multiple Postman Collections to be updated and shared across teams.

In this article, we will cover how to integrate the Serverless Framework plugin into your development flow and CICD pipelines.

Main Plugin Features

As of writing this article, the current version 1.2.1 of the plugin has the following features:

Automatic GraphQL Request Generation - The plugin will generate new requests on demand or during deployment, ensuring they are always up to date with the latest schema version.
Automatic URL & API Key Retrieval - The URL and API Key will be automatically populated with the latest AppSync configuration.
Choose between Inline or using variable file input - Developers can configure the plugin to generate requests with Inline input or with a separate file for variable input.
Exports requests to independent Files and Postman Collections - Depending on the use case, developers can configure the plugin to export the generated requests to independent .graphql files, a Postman Collect or both.
Upload the generated files to S3 - As the icing on the cake, this plugin also automates the upload of the generated files to the configured S3 bucket.

Prerequisites

In order to be able to implement this plugin into your workflow you will at least need:

Node JS installation
AWS Account to deploy the API
A project that uses the Serverless Framework to deploy an AppSync API - examples will be shown using this repository
Postman, GraphBolt or any other tool to send requests and test the generated requests

Installation Process

Installing and adding the plugin to your project is fairly straightforward to accomplish by following two simple steps.

Install the plugin using NPM

Use the following command to install the plugin and save it as a devDependency in your project:

npm install -D serverless-gql-generator

Add the Plugin to your project

Add the plugin under the plugins list in your serverless.yml file

service: my-app

plugins:
  - serverless-gql-generator

Using the plugin

After adding the plugin to the plugins list, it will start generating the Postman Collections every time the service is deployed.

The experience can be improved further by configuring the plugin to match your needs better and by using the CLI commands to enable the request generation without the need to redeploy your service.

Overriding the default behaviour

The plugin's default behaviour is to generate (and save locally under the ./output/ folder) a Postman Collection.

This behaviour can be configured by overriding the defaults and adding any of the configuration attributes:

service: my-app

plugins:
  - serverless-gql-generator

gql-generator:
  schema:
    path: ./schema.graphql # Overrides default schema path 
    encoding: utf-8
    assumeValidSDL: true
  output:
    directory: ./output # Output directory
    s3: # Enables Upload to AWS S3
      bucketName: gql-output-bucket # Mandatory Bucket name
      folderPath: s3folder/path # Override Folder Path inside s3, defaults to `${service}/${stage}`
      skipLocalSaving: false # if the files should also be saved locally or not
    useVariables: true # use variables or have the input inline
    maxDepth: 10 # max depth for schema recursion
    rawRequests: false # set to true to generate raw requests
    postman:
      collectionName: test-name # Overrides colection name, defaults to `${service}-${stage}`
      url: https://test.com/graphql # Overrides url for postman collection
      apiKey: abc-123 # Overrides default API Key if any

Default Schema options

The plugin expects the schema to be in the root folder of the project and be called ./schema.graphql, Developers can update the configuration under gql-generator.schema in order to update the path or encoding of their schema.

gql-generator:
  schema:
    path: ./schema.graphql 
    encoding: utf-8
    assumeValidSDL: true

Default Request Generation Options

Overriding the configuration on how the requests are being generated can be done by updating the following attributes under gql-generator.output.

gql-generator:
  output:
    directory: ./output
    useVariables: true
    maxDepth: 10
    rawRequests: false

output.directory - path to the directory where the generated files should be stored at
output.useVariables - flag to decide if the generated requests should have inline input or dedicated variable files
output.maxDepth - maximum allowed depth for the generated requests, used to avoid infinite recursions in the requests
output.rawRequests - flag to indicate if the raw requests (.graphql files) should also be stored. This flag has to be set to true if output.postman is set to false

Default Postman Collection Configuration

The plugin will, by default, generate a Postman Collection that will be called based on ${service}-${stage} and fetch the URL and API Key from the deployed API.

gql-generator:
  output:
    postman:
      collectionName: test-name
      url: https://test.com/graphql
      apiKey: abc-123

# OR

gql-generator:
  output:
    postman: false

Developers can override this configuration by updating the following attributes:

output.postman - can be set to false to avoid the Postman Collection being generated, for that scenario output.rawRequests will be required to be true
output.postman.collectionName - used to override the name to be used for the generated collection
output.postman.url - used to override the API endpoint, especially useful if the API has a custom domain configured or you want to use the path to the CDN or Proxy
output.postman.apiKey - used to override the API KEY to be used to authenticate the requests

Uploading files to S3

⚠
Developers or CI/CD pipelines will require credentials with write access to the desired bucket.

The output is only saved locally by default on the machine that generates the files, but there is the option to upload the files to S3 at the same time, making it even easier to share the results with other developers or teams.

gql-generator:
  output:
    s3:
      bucketName: gql-output-bucket
      folderPath: s3folder/path
      skipLocalSaving: false

In order to enable the export to S3 features, developers will need to update the following configuration under gql-generator.output.s3:

output.s3.bucketName - mandatory field, has to contain the name of an existing bucket
output.s3.folderPath - used to override the folder path in S3 where the files will be stored, by default it will create the following folder structure to store the files ${service}/${stage}
output.s3.skipLocalSaving - flag to indicate if the files should be stored locally or only uploaded to S3

CLI commands

Developers might want to trigger the request generation without wanting to redeploy the API again, the plugin exposes some CLI commands to allow for that scenario.

Schema Validation

When creating or updating a Schema developers might want to validate that it's formatted appropriately.

The plugin exposes the following command to allow developers to validate the provided schema:

serverless gql-generator validate-schema

Once the above line has been executed on the terminal, it will prompt any possible issues or confirm that the schema is valid and ready to be used.

Requests generation

By default, the plugin generates all requests on every deployment, but there could be a scenario where one would like to generate them without deploying the API again.

Developers might use the following command to trigger the Request generation:

serverless gql-generator generate

Once executed, the plugin will generate all requests based on the configuration.

This command can be especially useful to confirm that the plugin is configured as expected or to generate the requests again in case the output folder has been added to .gitignore.

CI/CD integration

This plugin is easily integrated into one's CI/CD pipeline as it will be triggered automatically during the deployment process.

To access the generated files, developers might choose between:

Workflow Artifacts - Configuring the pipeline to export the artifacts generated during the process would be equivalent to generating the files locally, but the developers would need to download them from the workflow execution.

This approach is preferred for example for feature branches, where the output might change multiple times during the development.
S3 Export - Output files will be uploaded automatically to S3 for easier access and sharing.

This is the preferred approach for stable or shared branches, such as dev or main.

Conclusions

Adding the serverless-gql-generator plugin to your stack can help you and your team save time by automating the process of generating and sharing GraphQL requests.

I would love to hear about your experience using the plugin. Please use GitHub Issues to report any issues while using the plugin or requesting new features.

Unlocking the Power of DynamoDB Condition Expressions

Lorenzo Hidalgo Gadea — Tue, 30 Jan 2024 09:41:00 +0000

TL;DR;

This article explores DynamoDB condition expressions, highlighting their potential to enhance database operations. They help prevent accidental data overwriting and facilitate conditional updates. The article also details how to handle errors efficiently when condition checks fail, thus reducing the need for additional requests. By leveraging these expressions, developers can create more efficient and robust applications.

Introduction

Are you tired of your PutItem operations overwriting existing items?

Or your UpdateItem inserting a new object if the provided keys don't exist?

Are you still reading an object before updating it to ensure its current state?

If you replied to any of the above questions with a yes, the title triggered your inner refactoring freak or you're just keen to learn new approaches, then this article is for you. In this article we will discover and learn how to take the most advantage of (what I think) is a somewhat unknown feature: DynamoDB Condition Expressions.

DynamoDB Expressions

When working with DynamoDB developers use expressions to state what actions or conditions they want DynamoDB to process.

There are different types of expressions that developers can use:

Projection Expressions - Similar to the SELECT statement in SQL, this type of expression is used to select what attributes you want DynamoDB to return when reading objects. By default, DynamoDB returns all attributes (same as using SELECT *).
Update Expressions - Similar to the UPDATE statement in SQL, this expression is used in the UpdateItem requests to specify what changes you want to apply to the desired object. Developers can ADD, SET, REMOVE or DELETE attributes.
Condition Expressions - This article's star of the show; could be compared to the WHERE clause of a SQL statement. This expression type will allow developers, as the name implies, to ensure a condition is met before the data is manipulated.

Using Condition Expressions

Developers can use condition expressions in any DynamoDB operation that manipulates data, such as PutItem or UpdateItem, and using such expressions opens the door to a whole new set of business logic and fail-safes that can be implemented without adding any additional requests to DynamoDB.

Avoid overriding existing objects

DynamoDB will, by default, override any existing data if an PutItem operation is triggered with existing keys.

There are scenarios where one would like to store a new object but only if it doesn't exist, for example, if we want to do some kind of idempotency check or if we want to avoid overriding existing data.

To do that, one could approach the issue by doing a Get/Query and only triggering the Put if the item doesn't exist, but using condition expressions allows us to do everything in a single request:

  const command = new PutCommand({
    ...,
    ConditionExpression: "attribute_not_exists(#id)",
    ExpressionAttributeNames: {
      "#id": "PK",
    },
  });
  await client.send(command);

In the above example snippet we're doing a PutItem request and adding the condition expression of attribute_not_exists(#id), this will indicate DynamoDB to only store the provided object if the current primary key (PK) is not in use.

By doing it, DynamoDB won't override any existing data and will also throw an error if the condition is not met (an object already exists).

Full example here.

Update only existing items

Similar to the insert, DynamoDBs behaviour on UpdateItem can also be a tad counter-intuitive, as it will execute and UPSERT operations and not an UPDATE.

For some scenarios it won't be an issue to always execute UPSERT operations by default, but in general one will want the UPDATE operation to fail if the record doesn't exist to avoid creating new records with only partial data that will probably trigger errors downstream.

Implementing that change is very easy, as one just needs to add a simple condition expression as follows.

    const command = new UpdateCommand({
      ...,
      ConditionExpression: "attribute_exists(#id)",
      ExpressionAttributeNames: {
        "#id": "PK",
      },
    });
    await docClient.send(command);

In the above example snippet we're doing a UpdateItem request and adding the condition expression of attribute_exists(#id), this will indicate DynamoDB to only update the desired object if the current primary key (PK) exists.

With this condition, if DynamoDB can't find an update with the provided keys, the current primary key (PK) will not exist and the condition would fail, meaning that the UpdateItem request will throw an error.

Full example here.

Conditional Updates

But the magic of Condition Expressions doesn't stop on avoiding unexpected behaviours from DynamoDB, they open a whole new range of possibilities.

For example, let's imagine a scenario where, during the login flow, you want to check if the account is frozen or not (user should not be able to log in) and if the account is active, update a field storing the timestamp and device information of the current login.

For this scenario, one could first query the data to check the account status and if the check is successfull send another request to update the object with the desired login information. This approach is technically correct and would probably work for most requirements, but it opens the following concerns:

Number of Requests - The most common scenario will be that the account is not frozen and the login should succeed, meaning that for almost all logins two requests will be sent to DynamoDB.
Data Consistency - This approach would be unable to handle or control any change on the data between both requests, meaning that, if the account is being deactivated at the same time, the login could succeed when it should have failed.

With the use of the Condition Expression we can move that business logic to be execute on DynamoDBs side.

🤯
Did you know that you can edit nested attributes directly? You just need to use the .(dot) or [x] notation when referencing it! Check the docs

    const command = new UpdateCommand({
      ...,
      ConditionExpression: "attribute_exists(#id) AND #obj.#key = :expected",
      ExpressionAttributeNames: {
        "#id": "PK",
        "#obj": "accountInformation",
        "#key": "isFrozen",
      },
      ExpressionAttributeValues: {
        ":expected": false,
      },
    });
    await docClient.send(command);

In this example snippet we're adding the condition expression of attribute_exists(#id) AND #obj.#key = :expected, this will indicate DynamoDB to only update the desired object if the current primary key (PK) exists and if the nested attribute accountInformation.isFrozen is set to false.

With this condition, we move the business logic to check the account status to be executed by DynamoDB directly, meaning that the object will only be updated if the condition is met. This way we only need to consider that the login should only fail if the UpdateItem request has failed.

Full example here.

Handling Conditional Check Failures

Now we know how to implement the condition expressions but we are missing what to do when the condition fails.

What if the expression contains multiple conditions and we want to have a custom error message depending on wich condition failed, should we trigger a new request to query the object?

The answer is no, and this is probably one of the hidden features that will help you the most. At this point, you are probably aware of the ReturnValues option to configure what information you would like DynamoDB to return, but did you know there is also ReturnValuesOnConditionCheckFailure?

It works similarly as the ReturnValues option, but with only two available options:

NONE - the default, the thrown error won't have any information regarding the current object attributes and values.
ALL_OLD - setting this option will request DynamoDB to throw an error that contains the old (current) object information in the response.

  try {
    const command = new UpdateCommand({
      ...,
      ReturnValuesOnConditionCheckFailure: "ALL_OLD",
    });

    const response = await docClient.send(command);
    return response;
  } catch (error) {
    if (!(error instanceof ConditionalCheckFailedException)) throw error;
    const oldRecord = unmarshall(error.Item);
    // Apply any logic to check why the update failed
  }

The above snippet showcases how one could approach the error handling for conditional expressions with three simple steps:

Set ReturnValuesOnConditionCheckFailure: "ALL_OLD" to ensure you receive the object information if the condition fails.
Ensure you only catch the expected exception types by re-throwing any error that is not an instance of ConditionalCheckFailedException.
Retrieve and unmarshall the record data from the returned error with unmarshall(error.Item). The Item value will be the marshalled object that we tried to update, it's important to unmarshall it or ensure we access it's properties respecting the marshalling.

After those steps have been implemented, one can add any additional desired business logic to check why the operation failed and handle the error appropriately based on which of the conditions failed.

Full example here.

Conclusions

In conclusion, DynamoDB condition expressions provide a powerful tool that can greatly enhance the efficiency and reliability of your database operations. They allow developers to implement complex business logic directly within their database operations, reducing the number of requests and mitigating risks of data inconsistency.

This feature can help prevent unintended data overwriting, ensure updates only apply to existing items, and enable conditional updates based on specific criteria. With the ability to return current object data when condition checks fail, developers can handle errors more effectively without making additional requests.

By fully utilizing this feature, you can unlock the true potential of DynamoDB and create more robust and efficient applications.

AWS AppSync Subscriptions: Detaching Prolonged Operations

Lorenzo Hidalgo Gadea — Tue, 05 Dec 2023 08:47:16 +0000

TL;DR: This article discusses how to use AppSync Subscriptions to decouple long-running tasks from front-end requests in a serverless chat application. It provides a step-by-step guide to implement this solution, including an architecture overview, decoupling and processing steps, prerequisites, GraphQL schema, AppSync API configuration, DataSources and Resolvers, and Lambda function setup. The sample code and complete implementation can be found in the provided GitHub repository.

Introduction

When building APIs, developers often face the issue of long-running tasks timing out requests from the Front End or difficulty decoupling those longer tasks from the actual FE requests while informing it of the execution status.

In this article, and as part of the Serverless Holiday Hackathon, we will review how developers can take advantage of AppSync Subscriptions to decuple long-running tasks from the actual FE request.

Architecture Overview

The Hackathon challenges participants to build holiday-themed chat applications that use Generative AI.

While building such an application, developers will probably face the possible difficulties:

Requests to Badrock or any other LLM API could entice long-running requests to generate longer responses, these could take longer than 30 seconds and timeout the requests
Not knowing how to take advantage of streamed responses, which would provide the final user with a more interactive experience.

With this example, we will cover how to resolve both scenarios in two simple steps, while still leaving room for improvement and personalization.

Step 1: Decoupling

As the first step, we will need to decouple the front-end request from the actual processing. To do so, we can configure a JS Resolver to send the message to be processed to a SQS queue.

The flow would look like this:

The user sends a request to AppSync.
The JS Resolver creates a unique identifier for the received prompt and adds the message to the SQS Queue.
AppSync returns the unique identifiers to the User.

The User will need the response for the following step.

Step 2: Process and Notify

The second step will handle the prompt processing and notifying the user by sending a dummy mutation request that will trigger a subscription.

The flow for this step would be composed of the following steps:

The user subscribes via AppSync to updates on the streamedResponse mutation using the provided identifiers in the previous response.
The SQS Queue will trigger the Lambda for each message added to the same Queue by the above-explained mutation.
The Lambda Function will send a streamedResponse mutation request for all updates that we want to notify the user with.
Each request sent as a streamedResponse mutation will trigger subscribed users to be notified by every response that matches the filtering requirements.

Implementing the solution

In this section, we will go over how to implement the solution that we described in the previous step.

All details and code can be found in the following sample application repository.

Prerequisites

To correctly follow and deploy the sample application, developers will need to fulfill the following requisites:

Node JS installation
AWS Account to deploy the API
Postman or GraphBolt to send requests and test the flow

GraphQL Schema

A mock schema has been defined for this application, part of the schema can be seen here:

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

type Query @aws_api_key @aws_iam {
  getSessionId: ID!
}

type Mutation {
  sendPrompt(userPrompt: userPrompt!): promptResponse @aws_api_key @aws_iam
  streamedResponse(streamedResponseInput: StreamedResponseInput!): StreamedResponse @aws_iam
}

type Subscription @aws_api_key @aws_iam {
  onStreamedResponse(sessionId: ID!): StreamedResponse @aws_subscribe(mutations: ["streamedResponse"])
}

The most important part of it is the auth directives for the mutations, where streamedResponse is only enabled for @aws_iam.

This is an important configuration aspect as we want only our Back End services to be able to trigger this mutation.

AppSync API

To configure the AppSync API using Serverless Framework we will be taking advantage of the Serverless AppSync Plugin.

appSync:
  name: ${self:custom.base}-appsync
  logging:
    level: ALL
    retentionInDays: 1
  xrayEnabled: true
  authentication:
    type: AWS_IAM
  additionalAuthentications:
    - type: API_KEY
  apiKeys:
    - ${self:custom.base}-key
  substitutions:
    accountId:
      Ref: AWS::AccountId
    queueName: decoupling-sqs
...

Some key insights from the above configuration:

Cloudwatch can end up being expensive, but to avoid racking up a high bill we configured them to only be retained for one day. We kept the log level to ALL to ensure we can see all logs during debugging, but make sure to lower that for any production projects, AppSync Logs are very verbose.
Multiple authentication methods, we want two different auth methods to ensure that: Our API is private and that we can limit who can trigger the streamedResponse mutation.
Substitutions: AppSync resolvers don't support environment variables, a workaround for that would be to use substitutions. This feature will act as environment variables by substituting some mock text in the resolver code with the actual required values.

DataSources and Resolvers

Apart from the above API configuration we also need to ensure we configure the code that will resolve each operation and the different data sources used by them.

...
  dataSources:
    localResolverDS:
      type: "NONE"
    sqsDS:
      type: "HTTP"
      config:
        endpoint: !Sub https://sqs.${AWS::Region}.amazonaws.com/
        iamRoleStatements:
          - Effect: "Allow"
            Action:
              - "sqs:*"
            Resource:
              Fn::GetAtt:
                - MyQueue
                - Arn
        authorizationConfig:
          authorizationType: AWS_IAM
          awsIamConfig:
            signingRegion:
              Ref: AWS::Region
            signingServiceName: sqs
  resolvers:
    Mutation.sendPrompt:
      kind: UNIT
      dataSource: sqsDS
      code: "./src/appsync/sendPrompt.js"
    Mutation.streamedResponse:
      kind: UNIT
      dataSource: localResolverDS
      code: "./src/appsync/streamedResponse.js"

Key takeaways from this config are:

Data Sources: What Resolvers use to fetch data and resolve operations. In this case, we configure two different types.
Resolvers: In this section, we define what kind, data source and code will be used to resolve a specific operation or data type.

Decoupling Lambda

Once we have the API up and running, we can focus on how to configure a Lambda function to process all messages from the SQS Queue.

functions:
  sqsHandler:
    handler: src/decoupled.handler
    role: LambdaRole
    logRetentionInDays: 1
    environment:
      GRAPHQL_ENDPOINT: { Fn::GetAtt: [GraphQlApi, GraphQLUrl] }
      REGION:
        Ref: AWS::Region
    events:
      - sqs:
          arn:
            Fn::GetAtt:
              - MyQueue
              - Arn
          batchSize: 1

This configuration is not different than any other Lambda Function triggered by a SQS Queue. But there are still some takeaway points from this configuration:

IAM Role: Developers will need to add and configure a custom IAM role for this Lambda role to be able to sign requests to AppSync.
Log retention: Similar to the AppSync configuration, we want to limit the time that the logs are stored, in this case, the logs should be deleted after one day.
AppSync API Endpoint: Something that developers can struggle with is getting the URL endpoint from the AppSync API generated in the same serverless.yml. To get that value one could use { Fn::GetAtt: [GraphQlApi, GraphQLUrl] } to resolve it during deployment.

Implementing the code

The code to complete the above example configuration can be found on the provided Github Repository, but the following is an example of one of the trickiest parts.

import { util } from "@aws-appsync/utils";

const accountId = "#accountId#";
const queueName = "#queueName#";

export function request(ctx) {
  const { userPrompt } = ctx.args;

  const msgBody = {
    ...userPrompt,
    messageId: util.autoId(),
  };

  ctx.stash.msgBody = msgBody;

  return {
    version: "2018-05-29",
    method: "POST",
    resourcePath: `/${accountId}/${queueName}`,
    params: {
      body: `Action=SendMessage&Version=2012-11-05&MessageBody=${JSON.stringify(
        msgBody
      )}`,
      headers: {
        "content-type": "application/x-www-form-urlencoded",
      },
    },
  };
}

The code sample is part of the JS resolver configured for the sendPrompt mutation. As part of this sample, we can learn:

JS Resolver substitutions: When using substitutions with JS resolvers, developers need to make sure they define a variable const accountId = "#accountId#"; where the value will be replaced with the value provided in the configuration with the same name as the one between the #.
Building a HTTP request: The returned object by the request function is an example of how to build an HTTP request for accessing/triggering the SQS API.

Conclusions

In conclusion, AWS AppSync Subscriptions can effectively decouple long-running tasks from front-end requests in serverless chat applications.

By implementing the two-step process of decoupling and processing with notifications, developers can enhance user experience and avoid request timeouts.

The provided sample code and repository offer a practical guide to implementing this solution, showcasing the use of GraphQL schema, AppSync API configuration, data sources, resolvers, and Lambda function setup.

References

Using AWS X-RAY to improve Serverless performance

Lorenzo Hidalgo Gadea — Wed, 19 Jul 2023 10:00:00 +0000

Building high performance serverless applications can be tough, but a service like AWS X-Ray will help you understand your AWS Lambda application code better, slow DynamoDB queries or HTTPS requests, and then track how your changes improve over time.

AWS X-Ray is a service that collects data from all the requests handled by your services, allowing you to visualize and analyze it. It generates service maps, response time or duration distribution, and segment timelines to help developers debug performance issues and improve the overall performance of their code. Setting up X-Ray is straightforward and only requires a few simple steps, including enabling tracing and configuring what X-Ray should capture.

Introduction

Observability and code profiling is, at least in most cases, an afterthought that comes into play once it’s too late. Most developers start thinking about it when they face issues, timeouts, or bottlenecks that they can’t easily resolve or justify with only the execution logs.

There are a lot of third-party observability and profiling third-party tools out there that might be useful, for example, Sentry.io, Dynatrace, or DataDog. But if you want to stay inside the AWS ecosystem, and have an almost effortless integration, AWS X-Ray would be the tool to choose.

In this article, we will go over what AWS X-Ray is, how we can enable it, and how it will help us to better understand and debug the performance of our code.

What is AWS X-Ray?

As per AWS's words, “AWS X-Ray is a service that collects data from all the requests handled by your services and allows you to visualize and analyze it.” In other words, AWS X-Ray is for requests and services interaction what Cloudwatch is for execution logs.

When enabled and correctly configured, AWS X-Ray will collect and measure all service interactions for a specific request. This information will be stored and made available for analysis in the following ways:

1. Service Maps

AWS X-Ray generates service maps to allow for a visual understanding of how all different services interact with each other. Using a somewhat simple CRUD orders API as an example; we’d be able to see the following two service maps:

Global Service Map:

This type of service map will allow the user to understand and visualize how all the services under the same domain interact. In this screenshot, we can see that the end client interacts with a single API Gateway which, depending on the request type, depends on a set of Lambda functions to process the request and interact with a single DynamoDB table.

Trace Service Map:

The second kind of service map can be found on the console when reviewing a single trace and will contain only the interactions with services for that single trace or user request. This is the one that will help us the most when trying to debug performance issues for different features since we’ll be able to see what services are being used and how the different executions took place.

For example, in the provided screenshot we’re able to see that the execution failed since the nodes displayed for both API Gateway and AWS Lambda are in an error state.

2. Response Time or Duration Distribution

AWS X-Ray also provides a distribution diagram for groups of traces. This is specifically useful when trying to understand the overall performance of your service, how it affects the end users, and how much effort should be put into improving the service for each scenario.

For example, performance issues should be prioritized differently if it affects only 0.5% of all requests or if it affects 50% of them.

3. Segment Timelines

Segment timelines are the most detailed diagrams that X-Ray will provide and allow developers to understand exactly how and when each service is being used.

These timelines are specifically useful when debugging performance issues. For example, in this provided example we can see that the culprit for the long execution time is the Lambda Initialization (a.k.a. Cold Start) which took 859ms to complete, and that most of the execution time for the AWS Lambda invocation itself was spent requesting the deletion of the item in DynamoDB.

Enable AWS X-Ray in AWS Lambda

Enabling AWS X-Ray on your AWS Lambda functions is very straightforward, and can normally be accomplished within a few minutes following two simple steps.

Step 1: Enable AWS X-Ray tracing on Your Services

The easiest way to do so is to enable it from your IaC template. For example, when using Serverless Framework, you can just add the following attributes under 'provider.tracing' to enable AWS X-Ray on all your defined AWS Lambda functions and the generated API Gateway.

Another option, in case you’re not deploying your services with an IaC template, would be to enable it manually through the AWS Console.

You will just need to head over to your Lambda configuration section and Edit the 'Monitoring tools' section by enabling the tracing switch.

Step 2: Configure What X-Ray Should Capture

After enabling AWS X-Ray on your Lambda function, you will also need to add the 'aws-xray-sdk-core' library to your project's dependencies and configure it to add the required traces.

Capturing AWS SDK Usage:

Wrapping the 'aws-sdk client' with the showcased functions will allow AWS X-Ray to capture and trace how the client is being used. For a Node JS project, there are two different configurations depending on the aws-sdk version your project is currently using.

If you are using aws-sdk v2, you'll only need to wrap the library once and it will have a “global” effect.

For example, with the provided code snippet, AWS X-Ray will be able to capture all requests done with the v2 SDK, independently of the client (SSM, DynamoDB, S3, etc).

When using the v3 SDK, the developer will need to add the AWS X-Ray wrapper to all the instantiated clients.

This snippet, for example, will allow AWS X-Ray to only capture the requests made with that specific DynamoDB client. If you instantiate another DynamoDB client (or for any other service) in another file without adding the wrapper, AWS X-Ray won’t be able to capture the usage.

Capturing HTTPS Requests:

In some cases, your project may also use some HTTPS requests to, for example, access third-party APIs which you’d also like to capture.

In order to do so, and similarly to wrapping the v2 SDK, you can add the above snippet to your index file to allow AWS X-Ray to capture all the HTTPS requests made by your code.

Adding Custom Subsegments:

Custom subsegments will allow AWS X-Ray to capture and measure the execution time of the desired part of your code.

One may add a custom segment by following the provided code snippet, where AWS X-Ray will measure the execution time of the code written between the 'segment.addNewSubsegment(…)' and 'subsegment.close()' functions. The custom subsegments will be displayed in the AWS X-Ray console under the Segment Timelines diagram.

How Can AWS X-Ray Help You Find Performance Bottlenecks?

Now that we know what AWS X-Ray has to offer and how to set it up, most of you will already have guessed how it can be a very useful tool but here are my favorite ways to take advantage of it:

Discovering Critical Services Under the Same Domain

AWS X-Ray provides (and builds based on the selected traces) a visual map of all the services linked to a specified domain.

In the example used above, we can see that this domain is composed of one API Gateway, four AWS Lambdas, and a single DynamoDB table.

Apart from seeing all the services linked to a domain, AWS X-Ray will also visually display the percentage of error executions that nodes might have.

In this provided example, we can easily see that the AppSync GraphQL API has an average error rate of around 10%.

Identifying the Performance Bottlenecks

Once the developer has found the nodes to be analyzed, the next step would be taking a look at the different traces for that node to better understand where it’s spending most of the execution time.

For this task, one could take advantage of the Segment Timelines. These timelines will visually display how long each action took to be executed.

From this example, we could see that the bottlenecks for the execution of this Lambda were:

The cold start, which added 733ms to the execution time.
The API request, which took 5.53s of the actual invocation time of the lambda.

After seeing these results, a developer would know that he would need to work possibly on avoiding cold starts and on improving (if owned) the API that is called during the execution.

Using Custom Subsegments to Profile & Improve Your Code

At last, one of the best-kept secrets of AWS X-Ray, using custom subsegments to profile your code and have a better understanding of where the time is spent during an execution.

Given this Segment Timeline, we would know that the execution is taking longer than it should since we expected the DynamoDB request to be the only time-consuming operation. Without the above traces, we wouldn’t be able to understand what is taking so long.

At this point, a developer would have two options:

Spend hours reviewing the code and blindly updating it to try to find the time-consuming task.
Add custom subsegments to the operations we suspect could be the culprit of the high execution time.

After adding a custom subsegment to the suspected function, we would be able to see a trace like this:

Here we can clearly see that the 'time-consuming operation' function is responsible for the extra 2.5 seconds of execution time. Thanks to this insight, the developer would know that they only need to focus on reviewing and improving that specific operation.

Conclusion

We highly recommend correctly setting up AWS X-Ray when developing services on AWS, especially if they are serverless, in order to allow for better observability and profiling. As showcased in this article, AWS X-Ray will allow developers to better understand how a service is performing and speed up the process of debugging performance bottlenecks or timeouts once the service is deployed to production.

Did you find this article interesting or useful? Do you have any questions or would like to chat more about it? I’d love to connect with you on my social media, you can find me on LinkedIn or Twitter.