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..4bc851cec 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' @@ -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 { @@ -31,7 +32,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 +57,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 +66,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 +75,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 +84,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 +93,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) {