gcf-utils v15.0.1

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

:warning: 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

:warning: 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.

:warning: 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:

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:

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.