An extension for running Probot in Google Cloud Functions
npm install gcf-utils> Helper module to make Probot applications easier and more secure to run in Google Cloud Functions
In your_bot/src/app.ts:
``typescript
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 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
`typescript`
import {logger} from 'gcf-utils';
#### Log a string statement
`typescript
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
`typescript`
logger.debug({ 'debug-property': 'value' });
This means you don't have to stringify errors anymore:
`typescriptmethodThatThrows threw an error
try {
methodThatThrows()
} catch (errorThrown) { // errorThrown = { name: 'HTTP Error', code: 404 }
logger.error({
message:
error: errorThrown
})
}
Cloud Logging output for the lines above:
`javascriptmethodThatThrows threw an error
{
... other log properties
jsonPayload: {
message:
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:
`typescript
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:
| 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:
`typescript
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.
`sh`Install dependencies
npm install
Run npm run test from the root directory to run the unit 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":
"cert":
"secret":
"githubToken":
}
5. Create a file in gcf-utils root directory called ".env" with the following:
PROJECT_ID=
GCF_SHORT_FUNCTION_NAME=
Run npm run system-test` from the root directory to run the system tests
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.
Apache 2.0 © 2019 Google Inc.