Set up Data Usage Alerts using Soracom API and AWS Lambda!
Written by: Cody Lirette
Published: February 12, 2020
Do you know how much you are paying Soracom per month on your own account?
You can quickly check the payment details by logging in to the user console, so if you haven’t seen it, check it out immediately. However, Soracom has many pay-as-you-go services, so while using it properly can save you money, not monitoring your data usage can wind up costing you.
No matter how careful you are, mistakes can always happen which is why we wanted to build a tool that can inform users when their data usage is getting higher than normal.
The idea is simple: we call Soracom’s API from a server-less environment like AWS Lambda to get the usage fee for Soracom and then send a notification to the user via messaging platforms such as Slack and LINE.
Using soracom-cli to call Soracom API
The Soracom API is a simple Rest API, which means it can be easily called but takes some time to authenticate.
That’s why we decided to use soracom-cli to call the Soracom API from AWS Lambda. Once soracom-cli is set up, it automatically performs the authentication process saving valuable time. However, AWS Lambda doesn’t have a permanent file system which means that the credentials would be forgotten each time.
To solve this, we fixed soracom-cli so that it can run in a temporary environment as well!
With soracom-cli version 0.5.2, –auth-key-id and –auth-keynow can now be used to specify the user’s AuthKeyID and Authkey. Choosing these options ensures that you don’t have to run them beforehand each time.
Leveraging AWS Lambda Layer Functionality
soracom-cli has released binary files for Linux, allowing you to download the files, include them in a ZIP file with your program code and upload it. However, since the file size is large, uploading can take some time.
AWS Lambda’s Layer function solves these problems. If you upload soracom-cli as a layer, you can easily use soracom-cli included in that layer from the Lambda function, and upload soracom-cli itself only once along with your own program code.
However, each time a new version of soracom-cli comes out, it has to be uploaded as a layer, which can still be a hassle.
Once you specify the ARN of the soracom-cli layer, you can use it from any Lambda immediately. For more detailed usage procedures, stay tuned for future blog articles.
Setting it Up
Broadly speaking, here are the three steps:
- Prepare a Slack notification destination
- Create a SAM user for SORACOM
- Create a Lambda function
Step 1 – Prepare a Slack Notification Destination
1. Create channels as needed
You can skip this step if you want to notify existing channels.
2. Create a Slack app
If you can’t create your own app in the workspace settings, consult your administrator. To build an app, go to https://api.slack.com/apps and click the “Create New App” button. Then, create an Incoming Webhook and note its URL.
Step 2 – Create a SAM user for SORACOM
If you are using an existing SAM user, you can skip this step.
1. Login to SORACOM User Console
Log in to the account for which you want to monitor usage charges.
2. Create SAM user
Select “Security” from the account name button on the upper right and press the “Create User” button. Enter the “Name” (user name) and click “Create”. Once that is completed, click the created user. Write the following information in the code entry area in the “Direct specification” column on the “Authority setting” tab.
This permission setting can only be called by the API called getLatestBilling. In the unlikely event that this user’s authentication information is leaked, the damage can be minimized (it won’t be lost).
After that is completed, click save and open the “Authentication Settings” tab. In there, click the “Generate Authentication Key” button in the “Authentication Key” Field. Write down the “Authentication Key ID” and “Authentication Key Secret” and close the diallog.
Step 3 – Create an AWS Lambda function
1. Log in to your AWS account
Lambda functions can be created in any region of any account. However, only ap-east-1 is not supported.
2. Create Lambda function
Open the AWS Lambda screen and create a new function with the “Create Function” button. This time, let’s select “Create from scratch” without using Blueprint, etc. Set any name for the function name. For the runtime, select Node.js 12.x (currently the latest version of Node.js). And press the “Create function” button.
3. Setting a layer in the Lambda function
Click “Layers” near the center of the Designer area and press “Add Layer”. Select “Provide Layer Version ARN and enter the following:
Please change the “ap-northeast-1” part according to your region.
If you see soracom-cli-052, then you currently have soracom-cli version 0.5.2. This number will increase as new updates emerge. Once this is completed, press the “Add” button and you have successfully added a layer!
4. Enter the code of Lambda function
Click the function name near the center of the Designer area and replace the contents of index.js with the following contents in the function code area.
In this code, Soracom defines a function named in lines 5-7. The soracom command is executed by specifying AUTH_KEY_ID and AUTH_KEY in the environment variables as arguments.
Lines 9-40 are the code to send a message to Slack. It’s a less essential part, but it makes up the bulk of the code. Line 42 is the body of the Lambda function and the 43rd line uses the soracom command to get the latest usage fee information for Japan Coverage. Line 44 parses the information (JSON), and line 45 notifies Slack while lines 47-49 do the same for global coverage.
5. Set environment variables
Use the following three environment variables:
- AUTH_KEY_ID
- AUTH_KEY
- SLACK_WEBHOOK_URL
Use AUTH_KEY for the value specified in 2-2-9 and SLACK_WEBHOOK_URL for the URL you wrote down in Step 1 B). Press the “Save” button at the top right of the screen.
6. Test
Press the “Test” button in the upper right of the screen. The first time you will see a dialog, so give the “Event Name” an appropriate name and press the “Create” button. The function created this time does not use the contents of this event, so you do not need to tweak the JSON part as it is.
After the test event is completed, press the “Test” button again. Did Slack get the following notification?
If there is an error, it will be displayed on the Lambda screen, so let’s debug it.
7. Set the trigger
Click the “Add Trigger” button at the bottom left of the Designer area.Select CloudWatch Events from the “Select Trigger” drop-down list and create or select a rule.
Select any existing rules that fit your needs. If not, select “Create New Rule” from the drop-down to create a new rule. Set “Rule Name” to something appropriate. For “Rule Type, select “Schedule” and specify the format as shown in the example rate:
Make sure that “enable trigger” is checked, press “add” and voila!
Conclusion
We always want our customers to try out the functions we develop. With this new mechanism, we believe customers will benefit from greater control over their IoT project.
If you want to learn more about this functionality, we will be hosting an event called Technology Camp 2020 on February 18, 2020 where we will be showing how to use the Soracom API.
