gcf-utils

Helper module to make Probot applications easier and more secure to run in Google Cloud Functions

Usage

GCFBootstrapper

In your_bot/src/app.ts:

import {GCFBootstrapper} from 'gcf-utils';
import {handler} from './your-bot';        // the handler that will be called for probot events, of type ApplicationFunction

const bootstrap = new GCFBootstrapper();

const wrapOptions =  {
  background: true,     // enables the use of Cloud Tasks to execute in the background
  logging: true,        // enables automatic logging of metrics
}

module.exports['your_bot'] = bootstrap.gcf(handler, wrapOptions);

GCFLogger

GCFLogger is a standardized logger for Google Cloud Functions. It has in-built support for:

• Cloud Logging Severity Levels
• Cloud Logging Special Fields
• Both string logging and JSON structured Logging
• Synchronous flush
• Logging Custom Metrics

gcf-util exports a configured instance of GCFLogger for bots to use. This instance will be synchronously flushed after the Bot's app function has completed, so you do not need to flush this in your Bot's code.

Import this in your bot

import {logger} from 'gcf-utils';

Log a string statement

logger.info('An info message');  // will show up as INFO log in Cloud Logging
logger.debug('A debug message');  // will show up as DEBUG log in Cloud Logging
logger.error('An error message');  // will show up as ERROR log in Cloud Logging

Log a structured JSON

logger.debug({ 'debug-property': 'value' });

This means you don't have to stringify errors anymore:

try {
    methodThatThrows()
} catch (errorThrown) {      // errorThrown = { name: 'HTTP Error', code: 404 }
    logger.error({
        message: `methodThatThrows threw an error`
        error: errorThrown
    })
}

Cloud Logging output for the lines above:

{
    ... other log properties
    jsonPayload: {
        message: `methodThatThrows threw an error`
        error: {
            name: 'HTTP Error',
            code: 404
        }
    }
    ... other log properties
}

Synchronously Flush Logs

⚠️ If you are importing logger from gcf-utils as shown above, you do not need to call the synchronous flush method. gcf-utils automatically handles this once the Bot's application function completes

⚠️ GCFLogger.flush() only works for SonicBoom destinations, which is the default destination for this logger

To synchronously flush logs:

import {logger} from 'gcf-utils';

logger.flush()

Automatically Logged Metrics

gcf-utils logs some metrics automatically with the help of GCFLogger. This is completely transparent to the Bot and requires no action from the Bot developer.

⚠️ If your Bot is not automatically logging the information above, please ensure that you are using gcf-utils 5.5.1 or above and you have logging: true in the WrapperOptions passed to GCFBootstrapper.gcf()

Execution Trigger Information

gcf-utils automatically logs information related to the trigger that initiated the Bot's execution. The following properties are logged:

Property	Value Type	Value	Notes
message	string	A descriptive message about the trigger
trigger	object	Object containing trigger information
____trigger_type	string	Trigger source (eg. Github Webhook, Cloud Scheduler)
____trigger_sender	string	GitHub username of user that triggered the webhook	Only for GitHub WebHook triggers
____github_delivery_guid	string	GUID of the GitHub WebHook	Only for GitHub WebHook triggers and subsequent Cloud Tasks
____payload_hash	string	An MD5 hash of the GitHub Event Payload	Only for GitHub WebHook triggers
____trigger_source_repo	object	Object containing GitHub source repository information	Only for GitHub WebHook triggers
________owner	string	Username of the repository owner	Only for GitHub WebHook triggers
________owner_type	string	The type of owner (eg. 'User' or 'Organization')	Only for GitHub WebHook triggers
________repo_name	string	The name of the GitHub repository	Only for GitHub WebHook triggers
________url	string	URL to the GitHub repository (may be private)	Only for GitHub WebHook triggers

GitHub Action Information

gcf-utils automatically logs information related to any actions taken by a Bot on GitHub.

Note: only calls to GitHub that make a change to any GitHub objects are logged. Calls to GitHub that simply retrieve information are not logged. For example, if a Bot retrieves a list of issues from a repository and then adds a label to some issues, only the 'add label' actions will be logged, not the retrieving of the issues.

The following properties are logged:

Property	Value Type	Value	Notes
action	object	Object containing action information
____type	string	The type of action (eg. ISSUE_ADD_LABEL)
____value	string	The value associated with the action. (eg. name of label)	If action has no associated value, then value is 'NONE'
____destination_object	object	The GitHub object that received the action	Only for actions that have an associated object
________object_type	string	The type of object (eg. PULL_REQUEST)	Only for actions that have an associated object
________object_id	number	The GitHub ID corresponding to the object	Only for actions that have an associated object
____destination_repo	object	The GitHub repository that received the action
________repo_name	string	The name of the GitHub repository
________owner	string	The username of the GitHub repository owner

Manually Log Metrics

GCFLogger also allows for custom logs-based metrics in addition to the metrics logged above.

To log a metric for the event my_bot.event with additional structured information url:

import {logger} from 'gcf-utils'

logger.metric('my_bot.event', {url: 'http://www.example.com'})

Where url could be any additional structured information you wish to associate with the metric.

Development Setup

# Install dependencies
npm install

Testing

Run Unit Tests

Run npm run test from the root directory to run the unit tests

Run Integration/System Tests

Additional setup is required to run the test/integration/gcf-bootstrapper-integration tests. If you don't wish to run these tests, you can skip this setup. Else, follow these steps:

1. Create a GitHub personal access token
2. Create a test GitHub App and give it the necessary permissions
3. Navigate to https://github.com/settings/apps/{your-app} to find the necessary information for step 4
4. Enable secret manager on your GCP project and create a new secret with the following values:

{
    "id": <your GitHub app id>,
    "cert": <your GitHub app private key at the bottom of the page>,
    "secret": <your GitHub app's webhook secret (not client secret)>,
    "githubToken": <your personal access token from step 1>
}

5. Create a file in gcf-utils root directory called ".env" with the following:

PROJECT_ID=<your GCP project id>
GCF_SHORT_FUNCTION_NAME=<the name of your secret>

Run npm run system-test from the root directory to run the system tests

Contributing

If you have suggestions for how gcf-utils could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.

License

Apache 2.0 © 2019 Google Inc.