Adding logger SDK to reference, with some edits. (#714)

* Adding logger SDK to reference, with some edits.

* Adding link to structured logging details per feedback.

Author: egilmorez

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:

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];

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,

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) {