From b0e273dc2a8be919a0cffd1f5a7cba464c2bf899 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Mon, 22 Jun 2020 17:03:37 -0700 Subject: [PATCH 1/6] Adding logger SDK to reference, with some edits. --- docgen/content-sources/toc.yaml | 6 ++++++ src/logger.ts | 15 ++++++++------- src/logger/common.ts | 3 +++ src/logger/compat.ts | 1 + 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docgen/content-sources/toc.yaml b/docgen/content-sources/toc.yaml index 91544d4f6..a394975df 100644 --- a/docgen/content-sources/toc.yaml +++ b/docgen/content-sources/toc.yaml @@ -93,6 +93,12 @@ toc: - title: 'CallableContext' path: /docs/reference/functions/providers_https_.callablecontext.html + - title: 'functions.logger' + path: /docs/reference/functions/logger_.html + section: + - title: 'LogEntry' + path: /docs/reference/functions/logger_.logentry.html + - title: 'functions.pubsub' path: /docs/reference/functions/providers_pubsub_.html section: diff --git a/src/logger.ts b/src/logger.ts index 258dbbdff..f8fb6a261 100644 --- a/src/logger.ts +++ b/src/logger.ts @@ -7,7 +7,7 @@ import { } from './logger/common'; /** - * `LogSeverity` indicates the detailed severity of the log entry. See [LogSeverity](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity) for more. + * `LogSeverity` indicates the detailed severity of the log entry. See [LogSeverity](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity). */ export type LogSeverity = | 'DEBUG' @@ -31,7 +31,7 @@ export interface LogEntry { /** * Writes a `LogEntry` to `stdout`/`stderr` (depending on severity). - * @param entry The LogEntry including severity, message, and any additional structured metadata. + * @param entry The `LogEntry` including severity, message, and any additional structured metadata. */ export function write(entry: LogEntry) { if (SUPPORTS_STRUCTURED_LOGS) { @@ -56,7 +56,7 @@ export function write(entry: LogEntry) { /** * Writes a `DEBUG` severity log. If the last argument provided is a plain object, - * it will be added to the `jsonPayload` in the Cloud Logging entry. + * it is added to the `jsonPayload` in the Cloud Logging entry. * @param args Arguments, concatenated into the log message with space separators. */ export function debug(...args: any[]) { @@ -65,7 +65,7 @@ export function debug(...args: any[]) { /** * Writes an `INFO` severity log. If the last argument provided is a plain object, - * it will be added to the `jsonPayload` in the Cloud Logging entry. + * it is added to the `jsonPayload` in the Cloud Logging entry. * @param args Arguments, concatenated into the log message with space separators. */ export function log(...args: any[]) { @@ -74,7 +74,7 @@ export function log(...args: any[]) { /** * Writes an `INFO` severity log. If the last argument provided is a plain object, - * it will be added to the `jsonPayload` in the Cloud Logging entry. + * it is added to the `jsonPayload` in the Cloud Logging entry. * @param args Arguments, concatenated into the log message with space separators. */ export function info(...args: any[]) { @@ -83,7 +83,7 @@ export function info(...args: any[]) { /** * Writes a `WARNING` severity log. If the last argument provided is a plain object, - * it will be added to the `jsonPayload` in the Cloud Logging entry. + * it is added to the `jsonPayload` in the Cloud Logging entry. * @param args Arguments, concatenated into the log message with space separators. */ export function warn(...args: any[]) { @@ -92,13 +92,14 @@ export function warn(...args: any[]) { /** * Writes an `ERROR` severity log. If the last argument provided is a plain object, - * it will be added to the `jsonPayload` in the Cloud Logging entry. + * it is added to the `jsonPayload` in the Cloud Logging entry. * @param args Arguments, concatenated into the log message with space separators. */ export function error(...args: any[]) { write(entryFromArgs('ERROR', args)); } +/** @hidden */ function entryFromArgs(severity: LogSeverity, args: any[]): LogEntry { let entry = {}; const lastArg = args[args.length - 1]; diff --git a/src/logger/common.ts b/src/logger/common.ts index f8b1f0ed9..f7ff0de78 100644 --- a/src/logger/common.ts +++ b/src/logger/common.ts @@ -1,9 +1,11 @@ // Determine if structured logs are supported (node >= 10). If something goes wrong, // assume no since unstructured is safer. +/** @hidden */ export const SUPPORTS_STRUCTURED_LOGS = parseInt(process.versions?.node?.split('.')?.[0] || '8', 10) >= 10; // Map LogSeverity types to their equivalent `console.*` method. +/** @hidden */ export const CONSOLE_SEVERITY: { [severity: string]: 'debug' | 'info' | 'warn' | 'error'; } = { @@ -18,6 +20,7 @@ export const CONSOLE_SEVERITY: { }; // safely preserve unpatched console.* methods in case of compat require +/** @hidden */ export const UNPATCHED_CONSOLE = { debug: console.debug, info: console.info, diff --git a/src/logger/compat.ts b/src/logger/compat.ts index 48647f5e3..a7c27bd16 100644 --- a/src/logger/compat.ts +++ b/src/logger/compat.ts @@ -5,6 +5,7 @@ import { } from './common'; import { format } from 'util'; +/** @hidden */ function patchedConsole(severity: string): (data: any, ...args: any[]) => void { return function(data: any, ...args: any[]): void { if (SUPPORTS_STRUCTURED_LOGS) { From c80b51ba70bf68bbcf0270e8477498f04fa4a23a Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Tue, 23 Jun 2020 12:52:16 -0700 Subject: [PATCH 2/6] Adding link to structured logging details per feedback. --- src/logger.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/logger.ts b/src/logger.ts index f8fb6a261..4bc851cec 100644 --- a/src/logger.ts +++ b/src/logger.ts @@ -20,7 +20,8 @@ export type LogSeverity = | 'EMERGENCY'; /** - * `LogEntry` represents a structured Cloud Logging entry. All keys aside from `severity` and `message` are + * `LogEntry` represents a [structured Cloud Logging](https://cloud.google.com/logging/docs/structured-logging) + * entry. All keys aside from `severity` and `message` are * included in the `jsonPayload` of the logged entry. */ export interface LogEntry { From e2c7891bd13e6543e2b2f469066c3efa2e49b2e1 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Wed, 8 Jul 2020 16:48:44 -0700 Subject: [PATCH 3/6] Adding ScheduleBuilder class to TOC and adding minimal commenting. --- docgen/content-sources/toc.yaml | 2 ++ src/providers/pubsub.ts | 13 +++++++++++++ 2 files changed, 15 insertions(+) diff --git a/docgen/content-sources/toc.yaml b/docgen/content-sources/toc.yaml index a394975df..41155b8f5 100644 --- a/docgen/content-sources/toc.yaml +++ b/docgen/content-sources/toc.yaml @@ -106,6 +106,8 @@ toc: path: /docs/reference/functions/providers_pubsub_.message.html - title: 'TopicBuilder' path: /docs/reference/functions/providers_pubsub_.topicbuilder.html + - title: 'ScheduleBuilder' + path: /docs/reference/functions/providers_pubsub_.schedulebuilder - title: 'functions.remoteconfig' path: /docs/reference/functions/providers_remoteconfig_.html diff --git a/src/providers/pubsub.ts b/src/providers/pubsub.ts index 0f12f669c..b4533cc34 100644 --- a/src/providers/pubsub.ts +++ b/src/providers/pubsub.ts @@ -98,6 +98,11 @@ export class TopicBuilder { } } +/** + * The Google Cloud Pub/Sub schedule builder. + * + * Access via [`functions.pubsub.schedule()`](providers_pubsub_.html#schedule). + */ export function schedule(schedule: string): ScheduleBuilder { return _scheduleWithOptions(schedule, {}); } @@ -137,6 +142,14 @@ export class ScheduleBuilder { return this; } + /** + * Event handler that fires when a scheduled event occurs for + * a specified Cloud Pub/Sub message. + * + * @param handler Event handler that fires when a scheduled event occurs for + * a specified Cloud Pub/Sub message. + * @return A Cloud Function that you can export and deploy. + */ onRun(handler: (context: EventContext) => PromiseLike | any) { const cloudFunction = makeCloudFunction({ contextOnlyHandler: handler, From a7fe694ab8bbc0e7c6daeae7f13b9b465ca12bab Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Thu, 9 Jul 2020 17:47:21 -0700 Subject: [PATCH 4/6] Improving wording and format per feedback. --- docgen/content-sources/toc.yaml | 2 +- src/providers/pubsub.ts | 14 +++++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docgen/content-sources/toc.yaml b/docgen/content-sources/toc.yaml index 41155b8f5..37093f7c2 100644 --- a/docgen/content-sources/toc.yaml +++ b/docgen/content-sources/toc.yaml @@ -107,7 +107,7 @@ toc: - title: 'TopicBuilder' path: /docs/reference/functions/providers_pubsub_.topicbuilder.html - title: 'ScheduleBuilder' - path: /docs/reference/functions/providers_pubsub_.schedulebuilder + path: /docs/reference/functions/providers_pubsub_.schedulebuilder.html - title: 'functions.remoteconfig' path: /docs/reference/functions/providers_remoteconfig_.html diff --git a/src/providers/pubsub.ts b/src/providers/pubsub.ts index b4533cc34..4027a8d6c 100644 --- a/src/providers/pubsub.ts +++ b/src/providers/pubsub.ts @@ -99,7 +99,11 @@ export class TopicBuilder { } /** - * The Google Cloud Pub/Sub schedule builder. + * The builder for scheduled functions, which are powered by + * Google Pub/Sub and Cloud Scheduler. Describes the Cloud Scheduler + * job that is deployed to trigger a scheduled function at the provided + * frequency. For more information, see + * [Schedule functions](/docs/functions/schedule-functions). * * Access via [`functions.pubsub.schedule()`](providers_pubsub_.html#schedule). */ @@ -143,11 +147,11 @@ export class ScheduleBuilder { } /** - * Event handler that fires when a scheduled event occurs for - * a specified Cloud Pub/Sub message. + * Event handler for scheduled functions. Triggered whenever the associated + * scheduler job sends a Pub/Sub message. * - * @param handler Event handler that fires when a scheduled event occurs for - * a specified Cloud Pub/Sub message. + * @param handler Handler that fires whenever the associated + * scheduler job sends a Pub/Sub message. * @return A Cloud Function that you can export and deploy. */ onRun(handler: (context: EventContext) => PromiseLike | any) { From 1c23b4d026a8b70129ce9d799952c1ea96593aad Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Thu, 9 Jul 2020 18:16:32 -0700 Subject: [PATCH 5/6] I think we need to document both the schedule function and the builder class this way. --- src/providers/pubsub.ts | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/providers/pubsub.ts b/src/providers/pubsub.ts index 4027a8d6c..71c7fe3c7 100644 --- a/src/providers/pubsub.ts +++ b/src/providers/pubsub.ts @@ -99,13 +99,10 @@ export class TopicBuilder { } /** - * The builder for scheduled functions, which are powered by - * Google Pub/Sub and Cloud Scheduler. Describes the Cloud Scheduler - * job that is deployed to trigger a scheduled function at the provided - * frequency. For more information, see - * [Schedule functions](/docs/functions/schedule-functions). + * Registers a Cloud Function to run at specified times. * - * Access via [`functions.pubsub.schedule()`](providers_pubsub_.html#schedule). + * @param schedule The scheduling logic, in Unix Crontab or AppEngine syntax. + * @return ScheduleBuilder interface. */ export function schedule(schedule: string): ScheduleBuilder { return _scheduleWithOptions(schedule, {}); @@ -129,6 +126,15 @@ export function _scheduleWithOptions( }); } +/** + * The builder for scheduled functions, which are powered by + * Google Pub/Sub and Cloud Scheduler. Describes the Cloud Scheduler + * job that is deployed to trigger a scheduled function at the provided + * frequency. For more information, see + * [Schedule functions](/docs/functions/schedule-functions). + * + * Access via [`functions.pubsub.schedule()`](providers_pubsub_.html#schedule). + */ export class ScheduleBuilder { /** @hidden */ constructor( From f32f380ad749e29ad2c1633a0db734d3e773862a Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Fri, 10 Jul 2020 10:56:41 -0700 Subject: [PATCH 6/6] Last edits from feedback. --- src/providers/pubsub.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/providers/pubsub.ts b/src/providers/pubsub.ts index 71c7fe3c7..264ef9480 100644 --- a/src/providers/pubsub.ts +++ b/src/providers/pubsub.ts @@ -101,7 +101,7 @@ export class TopicBuilder { /** * Registers a Cloud Function to run at specified times. * - * @param schedule The scheduling logic, in Unix Crontab or AppEngine syntax. + * @param schedule The schedule, in Unix Crontab or AppEngine syntax. * @return ScheduleBuilder interface. */ export function schedule(schedule: string): ScheduleBuilder {