Debugging NodeJS Google Cloud Functions Locally with Functions Framework in VSCode

Debugging NodeJS Google Cloud Functions Locally with Functions Framework in VSCode, by Ayushka Partohap

The ability to debug software can give the developers much needed insights into how systems behave under certain inputs. This is an invaluable tool when debugging unexpected behavior in a system as we can see how the state of the system evolves in each step of the code.

For traditional services, it is relatively straightforward to run the service locally with a debug port open for our IDEs to attach to.

With serverless technologies such as Google Cloud functions, it is not as obvious how to run locally let alone debug, as Google Cloud handles the boot of the function.

In this article, we will go through the steps that allow us to debug NodeJS based on cloud functions using the ‘functions-framework’ npm package.

Creating a HTTP Cloud Function

An HTTP triggered Google Cloud function is essentially an “express” JS route handler. It is a function that takes in an express Request and Response object. Let’s create one as follows.

Now we can save this file into a new project folder at the root level and initialize an npm project.

Our project folder should now contain the following:

Running Locally with ‘functions-framework’

The ‘functions-framework’ library is an open source library for writing portable Google Cloud functions. It is maintained by the Google Cloud Platform team themselves. This library also allows us to run our functions locally on our machines.

To install it in our project, navigate to our project root and run npm install.

This will save the library as a development dependency.

To run our function, we can create a start script in our ‘package.json’.

Then, we can unpack the command arguments:

• The ‘ — target’ flag specifies the name of our handler function as it is exported from our main file. Our main file in our case is ‘index.js’ just as we created in the last section.
• The ‘ — signature-type’ flag specifies the argument signature of the target function. In our case, we want to be passed Express HTTP handler arguments.

Now we can run the start script and should see the following output in our terminal.

And, if we access the URL given, we will get the string ‘Hello World!’.

Debugging Setup in VSCode

In order to set up debugging to run with ‘functions-framework’, we have to make several modifications to the start script and make a debugging launch configuration.

Opening Debug Port

First, we can modify the start script to open up the debug port when running our project.

Now you can see we are running the function with a debug port open on port 9229.

Attaching VSCode Debugger

To attach to this port with VSCode, let’s create a vscode launch definition.

Now we can attach vscode to the debug port by using the Run and Debug menu on the sidebar of vscode.

Run & Debug menu on the sidebar of vscode. (Image: Ayushka Partohap/GajiGesa)

We can test this by adding a breakpoint and making a request. As we can see below, after adding a breakpoint to line 2 of ‘index.js’ and making a request with ‘curl localhost:8080’, VSCode pauses the execution and allows us to debug our code.

Debugging our code. (Image: Ayushka Partohap/GajiGesa)

Event Triggered Cloud Functions

There are two other signature types for a cloud function run with functions framework namely ‘event’ and ‘cloudevent’. They are conceptually the same but are supported by different runtimes. In the case of Node we are interested in the `event` type.

A common use of event based cloud functions is for handling Google Pub/Sub events and Google Cloud Storage events.

The main difference between ‘event’ and ‘http’ cloud functions is in the signature. In ‘event’ cloud functions, the handler functions is passed a ‘data’, ‘context’ and ‘callback’ arguments as described in the main [documentation](https://cloud.google.com/functions/docs/writing/background#function_parameters).

We can make a simple event based cloud function in ‘index.js’.

…And, modify our start script to point to the new handler.

In order to call this function we make a POST request, with a body that follows the arguments schema. Here is an example for simulating a Pub/Sub message event trigger.

Once we have this running, we simply attach our debugger using the same launch config to enable debugging in VSCode.

Congratulations! 🎉 Now you now know how to debug Google Cloud functions with VSCode on your local machine.

Share your thoughts or any confusions you have in the comment section below!

This article is contributed by Ayushka Partohap, Backend Engineer at GajiGesa.
He claimed he is a hardware & software programmer — but, please apologize as he’s not accepting any thesis-jockey now. Reach out to him via his LinkedIn.