Skip to content

Query and Test Your Application

This section assumes that you have created and deployed a BACE application using sam build and sam deploy --guided. Review the List of API calls for the available API calls to your BACE application.

When you update your application, you should query and test these API calls. While there are different ways to query and test your application, the provided API notebooks in /tools/API_notebooks provide a convenient way to access these API calls both locally and on the cloud.

Local Testing

You may want to test how your application performs locally before pushing changes to the cloud.

See the AWS page on Using sam local start-api for more details on this feature.

AWS Lambda provides a helpful tool for building and hosting a local Lambda container that allows you to test your application on your local computer.

From the root of your project, build a current version of your application.

sam build

Start a local API using the following command:

sam local start-api

Example output:

sam local start-api

Initializing the lambda functions containers.
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.

Mounting /Users/.../sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
Containers Initialization is done.
Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
2023-04-12 14:41:05 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:3000

You can then access the API from within your browser at localhost:3000.

We also provide a Python notebook that you can run from your local computer to test the basic API queries: /tools/API_notebooks/API_Queries_Local.ipynb. The code works directly with the provided template in the BACE package, and will need to be modified for your own BACE application.

If there are errors when querying your API calls, they will be shown on the command line, which can be helpful for debugging. Anything the application prints out will also appear on the command line output.

Notes on local testing

  • If you do not exit the call to sam local start-api correctly, the call will continue and port 3000 will be occupied. This means that the next call will not work. The following command line commands can be helpful in clearing the old process: - lsof -i tcp:3000 to get the PID, then - kill -9 PID
  • Local changes are not automatically reflected in your application. Make sure to re-run sam build then sam local start-api to update your application.
  • Computation speeds do not reflect what you will observe when the application is hosted externally. Local calls tested using these methods will typically be slower than what you would achieve externally.

Test Application on the Cloud

First, get the URL of your application (<your-URL>).

We provide a Python notebook to query your application on the cloud: /tools/API_notebooks/API_Queries.ipynb. This works out of the box for the BACE application created by the BACE package template.

  • The first block is an alternative way to obtain <your-URL>.
  • The speeds that you will observe using this method better reflect those that you can expect when the application is deployed on the cloud.
  • In particular, after deploying new changes to your application, the first query will take up to 10 or 15 seconds while the machine warms up. This is a one-time delay and we recommend querying the root API call at <your-URL> once to warm up the machine. This is done in the second block of /tools/API_notebooks/API_Queries.ipynb.

Troubleshooting Errors

If your application is not functioning correctly, you can view the logs for your AWS application in order to identify what is causing the problems. To view logs from the command line, use the following command:

sam logs --stack-name <stack-name> --region <region-name> --tail

(Find the name for your stack and region by opening the /samconfig.toml file located in the root of your application directory.)

Alternatively, you can view logs directly from the AWS CloudWatch console.

Oftentimes, errors may come from likelihood functions that do not properly handle inputs. For example, overflow errors may be triggered in logistic likelihood functions when calculating exponents for large utility differences.

Run a Sample Survey

With both local testing and cloud testing, the Survey route can be helpful to confirm that all the components work together.

  • The local survey route can be accessed at: http://127.0.0.1:3000/survey after running sam local start-api.
  • The cloud survey route can be accessed at: <your-URL>/survey after deploying with sam deploy.