Protected: Getting Started with AWS Lambda and Ruby

In this article, we’ll guide you through how to develop and deploy a small serverless Ruby application using the Serverless Framework and AWS Lambda. We’ll show you how to create the resources, deploy the code, and troubleshoot scenarios. Most importantly, we’ll highlight the importance of observability by having you integrate your finished app into Epsagon to achieve full monitoring. Sample code for this article is available here

Which Ruby App Are You Building?

For this article, you’ll be building a very simple calculator application, which will take three arguments:

• Operator: The operation to perform; possible values of add, subtract, multiply
• LHS: An integer representing the left-hand side of the operation; possible value of any valid integer

• RHS: An integer representing the right-hand side of the operation; possible value of any valid integer

The application will then return a status code and a result. In the event of an invalid operation, the application will return an error message with a related status code.

Prerequisites

This application depends on having the following components installed.

AWS

You’ll need to have an active AWS account, configured and authenticated with the AWS Command Line Interface, to run your AWS Lambda serverless functions; the serverless framework tool also uses it behind the scenes. For all of this, you will also have to create an access key/secret key pair in the AWS dashboard.

Ruby

This project will use the Ruby programming language, so you will need to install and configure it on your local operating system. You can do this by following the instructions here.

NPM

You will need a node package manager, or NPM, to install the Serverless Framework; this will also require the use of the Node programming language. To install Node and NPM, follow the instructions here.

Serverless Framework

The final component of your stack for this project is the Serverless Framework tool, used to configure and maintain your serverless function deployments. To install Serverless Framework, simply follow the instructions here.

Configuring Dependencies

Once you’ve installed all of the required components, you’ll want to verify they all work together properly. To do this, create a new folder on your machine to store the project, and then create a new Ruby serverless function using the Serverless Framework and its aws-ruby template:

serverless create -t aws-ruby -p myservice

Note: You can change “myservice” to whatever name you prefer, but for the purposes of this post, we will leave as is. Next, navigate to the myservice folder:

cd myservice

And deploy the service to AWS Lambda:

sls deploy

Note: A failure at this stage usually indicates an improperly configured AWS CLI. Run aws configure again and ensure that the AWS CLI has the appropriate credentials and region settings. You can now invoke the “hello” function to test that everything is working:

sls invoke -f hello -d ‘{}’

If the above has worked, you should see the following output, meaning your application is successfully configured and you are ready to iterate:

{ "statusCode": 200, "body": "{\"message\":\"Go Serverless v1.0! Your function executed successfully!\",\"input\":{}}" }

Configuring Your Ruby Code

The next step is to configure your calculator function. This begins by modifying the serverless.yml file. Navigate to your myservice folder and open the file serverless.yml. Add the following lines in the functions section:

functions:
  calculator:
    handler: handler.calculator

This tells the Serverless Framework that we have a new serverless function named “calculator” and that it is handled by the function “handler.caclulator,” which we now need to create. Open the file handler.rb in the same directory, and add a new Ruby function named “calculator.” This is the entry point for our Lambda calculator and will be called when we invoke the function:

def calculator(event:, context:)
  {
    statusCode: 200,
    body: {
      message: “Success”,
      event: event
    }.to_json
  }
end

Save the file, then run the following commands:

sls deploy
sls invoke -f calculator -d ‘{}’
You should see the following output:
{
    "statusCode": 200,
    "body": "{\"message\":\"Success\",\"event\":{}}"
}

As a final step, you need to add the code to make your calculator function. Any parameters you pass to the function are provided in the event object, so let’s grab those now:

operator = event['operator']
  lhs = event['lhs']
  rhs = event['rhs']
With these variables available, implementing the calculator as specified above is straightforward using the following case statement:
  result = case operator
    when 'add' then lhs+rhs
    when 'subtract' then lhs-rhs
    when 'multiply' then lhs*rhs
    else 'INVALID'
  end

This code performs the operation based on the received parameters or stores a sentinel value of “INVALID” if an invalid operation is encountered. With the result in hand, you can now communicate this back to the caller with the following code:

if(result != 'INVALID')
    {
      statusCode: 200,
      body: {
        result: result
      }.to_json
    }
else
    {
      statusCode: 500,
      body: {
        message: 'The operation was invalid',
        input: event
      }.to_json
    }
end

With all of these changes made, save your work, and then deploy the code to AWS Lambda using sls deploy. You can now call the function from the command line, but you’ll encounter an error if you do not pass in parameters:

> sls invoke -f calculator -d '{}'
{
    "statusCode": 500,
    "body": "{\"message\":\"The operation was invalid\",\"input\":{}}"
}

You can specify parameters for your calculator function:

• Via the -d parameter: -d ‘{‘operator’:’add’,’rhs’:2,’lhs’:3}’

or

• By using the –path parameter to point at a JSON file: –path events/add.json

The associated GitHub repo provides example JSON files to be used with the –path approach above.

Deployment of the Ruby App

With your code configured via a serverless.yml file, deploying your application is a simple matter of typing “sls deploy” into the console. The file you have currently is very sparse and only enables your function to deploy to AWS. But the Serverless Framework offers a large number of options, allowing you to configure your AWS serverless environment however you need. Once you’ve deployed your code, you’ll likely want to verify that your deployment was successful. You can manually verify this in the AWS dashboard by navigating to the service “AWS Lambda” and selecting the appropriate region from the selector in the upper-right corner of the interface. You should be able to quickly find your function name as reported by the Serverless Framework command line output.

The Importance of Monitoring

With the first of many serverless functions deployed for your application, it’s time to figure out how to track the application’s activity effectively. Out of the box, AWS CloudWatch offers a few very useful tools with log analysis and event details received and handled by your Lambda functions. However, this only gives you a small part of the picture of your application’s behavior. Monitoring, which focuses on building a more complete view of application behavior, can help you catch issues as they happen—rather than down the line when the impact is felt by end users. You can add distributed tracing to start building this capability, but you will need extra effort to enforce the coding standards that drive tracing adoption. Thus, while provider toolchains give you a good start, you’re ultimately going to need help understanding what’s going on with your serverless code.

Observability with Epsagon

Epsagon is a powerful observability suite you can use to make sense of your serverless application’s behavior. The Epsagon platform provides full monitoring for serverless applications, plus installation is simple and straightforward with the Epsagon Ruby gem:

gem install epsagon

Once this is done, you’ll need to set up and configure your Epsagon account to get your application connected. Next, you’ll need to configure the Serverless Framework to include the gem alongside your serverless functions. There are a couple of plugins available to do this, including the Serverless Ruby Layer and Serverless Ruby Package. Make sure to pick one that most closely matches your needs. Once the gem has been deployed, send a couple of test invocations to your serverless calculator function. If your environment is configured properly, you should be able to see this activity appear in the Epsagon dashboard.

Summary

In this article, we’ve walked through setting up an AWS Lambda function, driven by Ruby and the Serverless Framework. As you can see above, getting a basic application running with AWS Lambda and Ruby is very straightforward. More complex applications, though, require additional monitoring on top of first-party tools. In those cases, Epsagon can help you obtain the full picture of your serverless application, giving you complete visibility into its behavior. Check out Epsagon for FREE!