@google-cloud/logging-min - npm Package Compare versions

Comparing version 9.6.2 to 9.6.3

build/src/entry.d.ts

@@ -157,3 +157,3 @@ /*!
      * @param {object} entry An API representation of an entry. See a
-     *     [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry).
+     *     {@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry| LogEntry}.
      * @returns {Entry}
@@ -160,0 +160,0 @@ */

build/src/index.d.ts

@@ -144,3 +144,3 @@ /*!
 /**
- * [Cloud Logging](https://cloud.google.com/logging/docs) allows you to
+ * {@link https://cloud.google.com/logging/docs| Cloud Logging} allows you to
  * store, search, analyze, monitor, and alert on log data and events from Google
@@ -151,6 +151,6 @@ * Cloud Platform and Amazon Web Services (AWS).
  *
- * @see [What is Cloud Logging?](https://cloud.google.com/logging/docs)
- * @see [Introduction to the Cloud Logging API](https://cloud.google.com/logging/docs/api)
- * @see [Logging to Google Cloud from Bunyan](https://www.npmjs.com/package/@google-cloud/logging-bunyan)
- * @see [Logging to Google Cloud from Winston](https://www.npmjs.com/package/@google-cloud/logging-winston)
+ * See {@link https://cloud.google.com/logging/docs| What is Cloud Logging?}
+ * See {@link https://cloud.google.com/logging/docs/api| Introduction to the Cloud Logging API}
+ * See {@link https://www.npmjs.com/package/@google-cloud/logging-bunyan| Logging to Google Cloud from Bunyan}
+ * See {@link https://www.npmjs.com/package/@google-cloud/logging-winston| Logging to Google Cloud from Winston}
  *
@@ -191,2 +191,32 @@ * @param {ClientConfig} [options] Configuration options.
     constructor(options?: LoggingOptions);
+    /**
+     * Config to set for the sink. Not all available options are listed here, see
+     * the [Sink
+     * resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks#LogSink)
+     * definition for full details.
+     *
+     * @typedef {object} CreateSinkRequest
+     * @property {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @property {Bucket|Dataset|Topic} [destination] The destination. The proper ACL
+     *     scopes will be granted to the provided destination. Can be one of:
+     *     {@link https://googleapis.dev/nodejs/storage/latest/ Bucket},
+     *     {@link https://googleapis.dev/nodejs/bigquery/latest/ Dataset}, or
+     *     {@link https://googleapis.dev/nodejs/pubsub/latest/ Topic}
+     * @property {string} [filter] An advanced logs filter. Only log entries
+     *     matching the filter are written.
+     * @property {string|boolean} [uniqueWriterIdentity] Determines the kind of IAM
+     *     identity returned as `writerIdentity` in the new sink. See {@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/create#query-parameters}.
+     */
+    /**
+     * @typedef {array} CreateSinkResponse
+     * @property {Sink} 0 The new {@link Sink}.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback CreateSinkCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Sink} sink The new {@link Sink}.
+     * @param {object} apiResponse The full API response.
+     */
     createSink(name: string, config: CreateSinkRequest): Promise<[Sink, LogSink]>;
@@ -248,2 +278,88 @@ createSink(name: string, config: CreateSinkRequest, callback: CreateSinkCallback): void;
     entry(resource?: LogEntry, data?: {} | string): Entry;
+    /**
+     * Query object for listing entries.
+     *
+     * @typedef {object} GetEntriesRequest
+     * @property {boolean} [autoPaginate=true] Have pagination handled
+     *     automatically.
+     * @property {string} [filter] An
+     *     [advanced logs
+     * filter](https://cloud.google.com/logging/docs/view/advanced_filters). An
+     * empty filter matches all log entries.
+     * @property {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @property {string} [log] A name of the log specifying to pnly return
+     *     entries from this log.
+     * @property {number} [maxApiCalls] Maximum number of API calls to make.
+     * @property {number} [maxResults] Maximum number of items plus prefixes to
+     *     return.
+     * @property {string} [orderBy] How the results should be sorted,
+     *     `timestamp asc` (oldest first) and `timestamp desc` (newest first,
+     *     **default**).
+     * @property {number} [pageSize] Maximum number of logs to return.
+     * @property {string} [pageToken] A previously-returned page token
+     *     representing part of the larger set of results to view.
+     */
+    /**
+     * @typedef {array} GetEntriesResponse
+     * @property {Entry[]} 0 Array of {@link Entry} instances.
+     * @property {object} 1 The full API request.
+     * @property {object} 2 The full API response.
+     */
+    /**
+     * @callback GetEntriesCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Entry[]} entries Array of {@link Entry} instances.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * List the entries in your logs.
+     *
+     * @see [entries.list API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/list}
+     *
+     * @param {GetEntriesRequest} [query] Query object for listing entries.
+     * @param {GetEntriesCallback} [callback] Callback function.
+     * @returns {Promise<GetEntriesResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     *
+     * logging.getEntries((err, entries) => {
+     *   // `entries` is an array of Cloud Logging entry objects.
+     *   // See the `data` property to read the data from the entry.
+     * });
+     *
+     * //-
+     * // To control how many API requests are made and page through the results
+     * // manually, set `autoPaginate` to `false`.
+     * //-
+     * function callback(err, entries, nextQuery, apiResponse) {
+     *   if (nextQuery) {
+     *     // More results exist.
+     *     logging.getEntries(nextQuery, callback);
+     *   }
+     * }
+     *
+     * logging.getEntries({
+     *   autoPaginate: false
+     * }, callback);
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * logging.getEntries().then(data => {
+     *   const entries = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/logs.js</caption>
+     * region_tag:logging_list_log_entries
+     * Another example:
+     *
+     * @example <caption>include:samples/logs.js</caption>
+     * region_tag:logging_list_log_entries_advanced
+     * Another example:
+     */
     getEntries(options?: GetEntriesRequest): Promise<GetEntriesResponse>;
@@ -340,2 +456,74 @@ getEntries(callback: GetEntriesCallback): void;
     tailEntries(options?: TailEntriesRequest): Duplex;
+    /**
+     * Query object for listing entries.
+     *
+     * @typedef {object} GetLogsRequest
+     * @property {boolean} [autoPaginate=true] Have pagination handled
+     *     automatically.
+     * @property {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @property {number} [maxApiCalls] Maximum number of API calls to make.
+     * @property {number} [maxResults] Maximum number of items plus prefixes to
+     *     return.
+     * @property {number} [pageSize] Maximum number of logs to return.
+     * @property {string} [pageToken] A previously-returned page token
+     *     representing part of the larger set of results to view.
+     */
+    /**
+     * @typedef {array} GetLogsResponse
+     * @property {Log[]} 0 Array of {@link Log} instances.
+     * @property {object} 1 The full API request.
+     * @property {object} 2 The full API response.
+     */
+    /**
+     * @callback GetLogsCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Log[]} logs Array of {@link Log} instances.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * List the entries in your logs.
+     *
+     * @see [logs.list API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/logs/list}
+     *
+     * @param {GetLogsRequest} [query] Query object for listing entries.
+     * @param {GetLogsCallback} [callback] Callback function.
+     * @returns {Promise<GetLogsResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     *
+     * logging.getLogs((err, logs) => {
+     *   // `logs` is an array of Cloud Logging log objects.
+     * });
+     *
+     * //-
+     * // To control how many API requests are made and page through the results
+     * // manually, set `autoPaginate` to `false`.
+     * //-
+     * function callback(err, entries, nextQuery, apiResponse) {
+     *   if (nextQuery) {
+     *     // More results exist.
+     *     logging.getLogs(nextQuery, callback);
+     *   }
+     * }
+     *
+     * logging.getLogs({
+     *   autoPaginate: false
+     * }, callback);
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * logging.getLogs().then(data => {
+     *   const entries = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/logs.js</caption>
+     * region_tag:logging_list_logs
+     * Another example:
+     */
     getLogs(options?: GetLogsRequest): Promise<GetLogsResponse>;
@@ -377,2 +565,58 @@ getLogs(callback: GetLogsCallback): void;
     getLogsStream(options?: GetLogsRequest): Duplex;
+    /**
+     * Query object for listing sinks.
+     *
+     * @typedef {object} GetSinksRequest
+     * @property {boolean} [autoPaginate=true] Have pagination handled
+     *     automatically.
+     * @property {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @property {number} [maxApiCalls] Maximum number of API calls to make.
+     * @property {number} [maxResults] Maximum number of items plus prefixes to
+     *     return.
+     * @property {number} [pageSize] Maximum number of logs to return.
+     * @property {string} [pageToken] A previously-returned page token
+     *     representing part of the larger set of results to view.
+     */
+    /**
+     * @typedef {array} GetSinksResponse
+     * @property {Sink[]} 0 Array of {@link Sink} instances.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback GetSinksCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Sink[]} sinks Array of {@link Sink} instances.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Get the sinks associated with this project.
+     *
+     * @see [projects.sinks.list API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/list}
+     *
+     * @param {GetSinksRequest} [query] Query object for listing sinks.
+     * @param {GetSinksCallback} [callback] Callback function.
+     * @returns {Promise<GetSinksResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     *
+     * logging.getSinks((err, sinks) => {
+     *   // sinks is an array of Sink objects.
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * logging.getSinks().then(data => {
+     *   const sinks = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/sinks.js</caption>
+     * region_tag:logging_list_sinks
+     * Another example:
+     */
     getSinks(options?: GetSinksRequest): Promise<GetSinksResponse>;
@@ -379,0 +623,0 @@ getSinks(callback: GetSinksCallback): void;

build/src/log-sync.d.ts

@@ -141,2 +141,37 @@ /*!
     emergency(entry: Entry | Entry[], options?: WriteOptions): void;
+    /**
+     * Create an entry object for this log.
+     *
+     * Using this method will not itself do any logging.
+     *
+     * @see [LogEntry JSON representation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry}
+     *
+     * @param {?object} metadata See a
+     *     [LogEntry
+     * Resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry).
+     * @param {object|string} data The data to use as the value for this log
+     *     entry.
+     * @returns {Entry}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.logSync('my-log');
+     *
+     * const metadata = {
+     *   resource: {
+     *     type: 'gce_instance',
+     *     labels: {
+     *       zone: 'global',
+     *       instance_id: '3'
+     *     }
+     *   }
+     * };
+     *
+     * const entry = log.entry(metadata, {
+     *   delegate: 'my_username'
+     * });
+     * ```
+     */
     entry(metadata?: LogEntry): Entry;
@@ -143,0 +178,0 @@ entry(data?: string | {}): Entry;

build/src/log.d.ts

@@ -87,22 +87,316 @@ /*!
     constructor(logging: Logging, name: string, options?: LogOptions);
+    /**
+     * Write a log entry with a severity of "ALERT".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.alert(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.alert(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     alert(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     alert(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     alert(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * Write a log entry with a severity of "CRITICAL".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.critical(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.critical(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     critical(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     critical(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     critical(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * Write a log entry with a severity of "DEBUG".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.debug(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.debug(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     debug(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     debug(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     debug(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * @typedef {array} DeleteLogResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback DeleteLogCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Delete the log.
+     *
+     * @see [projects.logs.delete API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.logs/delete}
+     *
+     * @param {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @param {DeleteLogCallback} [callback] Callback function.
+     * @returns {Promise<DeleteLogResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * log.delete((err, apiResponse) => {
+     *   if (!err) {
+     *     // The log was deleted.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.delete().then(data => {
+     *   const apiResponse = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/logs.js</caption>
+     * region_tag:logging_delete_log
+     * Another example:
+     */
     delete(gaxOptions?: CallOptions): Promise<ApiResponse>;
     delete(gaxOptions: CallOptions, callback: DeleteCallback): void;
     delete(callback: DeleteCallback): void;
+    /**
+     * Write a log entry with a severity of "EMERGENCY".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.emergency(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.emergency(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     emergency(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     emergency(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * Create an entry object for this log.
+     *
+     * Using this method will not itself make any API requests. You will use
+     * the object returned in other API calls, such as
+     * {@link Log#write}.
+     *
+     * Note, [Cloud Logging Quotas and limits]{@link https://cloud.google.com/logging/quotas}
+     * dictates that the maximum log entry size, including all
+     * [LogEntry Resource properties]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry},
+     * cannot exceed _approximately_ 256 KB.
+     *
+     * @see [LogEntry JSON representation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry}
+     *
+     * @param {?object} metadata See a
+     *     [LogEntry
+     * Resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry).
+     * @param {object|string} data The data to use as the value for this log
+     *     entry.
+     * @returns {Entry}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const metadata = {
+     *   resource: {
+     *     type: 'gce_instance',
+     *     labels: {
+     *       zone: 'global',
+     *       instance_id: '3'
+     *     }
+     *   }
+     * };
+     *
+     * const entry = log.entry(metadata, {
+     *   delegate: 'my_username'
+     * });
+     *
+     * entry.toJSON();
+     * // {
+     * //   logName: 'projects/grape-spaceship-123/logs/syslog',
+     * //   resource: {
+     * //     type: 'gce_instance',
+     * //     labels: {
+     * //       zone: 'global',
+     * //       instance_id: '3'
+     * //     }
+     * //   },
+     * //   jsonPayload: {
+     * //     delegate: 'my_username'
+     * //   }
+     * // }
+     * ```
+     */
     entry(metadata?: LogEntry): Entry;
     entry(data?: string | {}): Entry;
     entry(metadata?: LogEntry, data?: string | {}): Entry;
+    /**
+     * Write a log entry with a severity of "ERROR".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.error(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.error(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     error(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     error(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     error(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * This method is a wrapper around {module:logging#getEntries}, but with a
+     * filter specified to only return entries from this log.
+     *
+     * @see [entries.list API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/list}
+     *
+     * @param {GetEntriesRequest} [query] Query object for listing entries.
+     * @param {GetEntriesCallback} [callback] Callback function.
+     * @returns {Promise<GetEntriesResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * log.getEntries((err, entries) => {
+     *   // `entries` is an array of Cloud Logging entry objects.
+     *   // See the `data` property to read the data from the entry.
+     * });
+     *
+     * //-
+     * // To control how many API requests are made and page through the results
+     * // manually, set `autoPaginate` to `false`.
+     * //-
+     * function callback(err, entries, nextQuery, apiResponse) {
+     *   if (nextQuery) {
+     *     // More results exist.
+     *     log.getEntries(nextQuery, callback);
+     *   }
+     * }
+     *
+     * log.getEntries({
+     *   autoPaginate: false
+     * }, callback);
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.getEntries().then(data => {
+     *   const entries = data[0];
+     * });
+     * ```
+     */
     getEntries(options?: GetEntriesRequest): Promise<GetEntriesResponse>;
@@ -185,11 +479,204 @@ getEntries(callback: GetEntriesCallback): void;
     tailEntries(options?: TailEntriesRequest): import("stream").Duplex;
+    /**
+     * Write a log entry with a severity of "INFO".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.info(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.info(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     info(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     info(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     info(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * Write a log entry with a severity of "NOTICE".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.notice(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.notice(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     notice(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     notice(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     notice(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * Write a log entry with a severity of "WARNING".
+     *
+     * This is a simple wrapper around {@link Log#write}. All arguments are
+     * the same as documented there.
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const log = logging.log('my-log');
+     *
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.warning(entry, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.warning(entry).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     warning(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
     warning(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;
     warning(entry: Entry | Entry[], callback: ApiResponseCallback): void;
+    /**
+     * @typedef {array} LogWriteResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback LogWriteCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Write options.
+     *
+     * @typedef {object} WriteOptions
+     * @property {boolean} [dryRun] If true, the request should expect normal
+     *     response, but the entries won't be persisted nor exported.
+     * @property {object} gaxOptions Request configuration options, outlined here:
+     *     https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @property {object[]} labels Labels to set on the log.
+     * @property {boolean} [partialSuccess] Whether valid entries should be
+     *     written even if some other entries fail due to INVALID_ARGUMENT
+     *     or PERMISSION_DENIED errors.
+     * @property {object} resource A default monitored resource for entries where
+     *     one isn't specified.
+     */
+    /**
+     * Write log entries to Cloud Logging.
+     *
+     * Note, [Cloud Logging Quotas and limits]{@link https://cloud.google.com/logging/quotas}
+     * dictates that the maximum cumulative size of all entries per write,
+     * including all [LogEntry Resource properties]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry},
+     * cannot exceed _approximately_ 10 MB.
+     *
+     * @see [entries.write API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/write}
+     *
+     * @param {Entry|Entry[]} entry A log entry, or array of entries, to write.
+     * @param {?WriteOptions} [options] Write options
+     * @param {LogWriteCallback} [callback] Callback function.
+     * @returns {Promise<LogWriteResponse>}
+     *
+     * @example
+     * ```
+     * const entry = log.entry('gce_instance', {
+     *   instance: 'my_instance'
+     * });
+     *
+     * log.write(entry, (err, apiResponse) => {
+     *   if (!err) {
+     *     // The log entry was written.
+     *   }
+     * });
+     *
+     * //-
+     * // You may also pass multiple log entries to write.
+     * //-
+     * const secondEntry = log.entry('compute.googleapis.com', {
+     *   user: 'my_username'
+     * });
+     *
+     * log.write([
+     *   entry,
+     *   secondEntry
+     * ], (err, apiResponse) => {
+     *   if (!err) {
+     *     // The log entries were written.
+     *   }
+     * });
+     *
+     * //-
+     * // To save some steps, you can also pass in plain values as your entries.
+     * // Note, however, that you must provide a configuration object to specify
+     * // the resource.
+     * //-
+     * const entries = [
+     *   {
+     *     user: 'my_username'
+     *   },
+     *   {
+     *     home: process.env.HOME
+     *   }
+     * ];
+     *
+     * const options = {
+     *   resource: 'compute.googleapis.com'
+     * };
+     *
+     * log.write(entries, options, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * log.write(entries).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/logs.js</caption>
+     * region_tag:logging_write_log_entry
+     * Another example:
+     *
+     * @example <caption>include:samples/logs.js</caption>
+     * region_tag:logging_write_log_entry_advanced
+     * Another example:
+     */
     write(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;
@@ -196,0 +683,0 @@ write(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

build/src/sink.d.ts

@@ -53,12 +53,228 @@ /*!
     constructor(logging: Logging, name: string);
+    /**
+     * Create a sink.
+     *
+     * @param {CreateSinkRequest} config Config to set for the sink.
+     * @param {CreateSinkCallback} [callback] Callback function.
+     * @returns {Promise<CreateSinkResponse>}
+     * @throws {Error} if a config object is not provided.
+     * @see Logging#createSink
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const sink = logging.sink('my-sink');
+     *
+     * const config = {
+     *   destination: {
+     *     // ...
+     *   }
+     * };
+     *
+     * sink.create(config, (err, sink, apiResponse) => {
+     *   if (!err) {
+     *     // The sink was created successfully.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * sink.create(config).then(data => {
+     *   const sink = data[0];
+     *   const apiResponse = data[1];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/sinks.js</caption>
+     * region_tag:logging_create_sink
+     * Another example:
+     */
     create(config: CreateSinkRequest): Promise<[Sink, LogSink]>;
     create(config: CreateSinkRequest, callback: CreateSinkCallback): void;
+    /**
+     * @typedef {array} DeleteSinkResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback DeleteSinkCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Delete the sink.
+     *
+     * @see [projects.sink.delete API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/delete}
+     *
+     * @param {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @param {DeleteSinkCallback} [callback] Callback function.
+     * @returns {Promise<DeleteSinkResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const sink = logging.sink('my-sink');
+     *
+     * sink.delete((err, apiResponse) => {
+     *   if (!err) {
+     *     // The log was deleted.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * sink.delete().then(data => {
+     *   const apiResponse = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/sinks.js</caption>
+     * region_tag:logging_delete_sink
+     * Another example:
+     */
     delete(gaxOptions?: CallOptions): Promise<DeleteResponse>;
     delete(callback: DeleteCallback): void;
     delete(gaxOptions: CallOptions, callback: DeleteCallback): void;
+    /**
+     * @typedef {array} GetSinkMetadataResponse
+     * @property {object} 0 The {@link Sink} metadata.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback GetSinkMetadataCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} metadata The {@link Sink} metadata.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Get the sink's metadata.
+     *
+     * @see [Sink Resource]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks#LogSink}
+     * @see [projects.sink.get API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/get}
+     *
+     * @param {object} [gaxOptions] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @param {SinkMetadataCallback} [callback] Callback function.
+     * @returns {Promise<SinkMetadataResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const sink = logging.sink('my-sink');
+     *
+     * sink.getMetadata((err, metadata, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * sink.getMetadata().then(data => {
+     *   const metadata = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/sinks.js</caption>
+     * region_tag:logging_get_sink
+     * Another example:
+     */
     getMetadata(gaxOptions?: CallOptions): Promise<SinkMetadataResponse>;
     getMetadata(callback: SinkMetadataCallback): void;
     getMetadata(gaxOptions: CallOptions, callback: SinkMetadataCallback): void;
+    /**
+     * @typedef {array} SetSinkFilterResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback SetSinkFilterCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Set the sink's filter.
+     *
+     * This will override any filter that was previously set.
+     *
+     * @see [Advanced Logs Filters]{@link https://cloud.google.com/logging/docs/view/advanced_filters}
+     *
+     * @param {string} filter The new filter.
+     * @param {SetSinkFilterCallback} [callback] Callback function.
+     * @returns {Promise<SetSinkFilterResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const sink = logging.sink('my-sink');
+     *
+     * const filter = 'metadata.severity = ALERT';
+     *
+     * sink.setFilter(filter, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * sink.setFilter(filter).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     setFilter(filter: string): Promise<SinkMetadataResponse>;
     setFilter(filter: string, callback: SinkMetadataCallback): void;
+    /**
+     * @typedef {array} SetSinkMetadataResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback SetSinkMetadataCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Set the sink's metadata.
+     *
+     * Note: If the sink was previously created or updated with
+     * uniqueWriterIdentity = true, then you must update the sink by setting
+     * uniqueWriterIdentity = true. Read more about using a unique writer identity
+     * here: https://cloud.google.com/logging/docs/api/tasks/exporting-logs#using_a_unique_writer_identity
+     *
+     * @see [Sink Resource]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks#LogSink}
+     * @see [projects.sink.update API Documentation]{@link https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/update}
+     *
+     * @param {object} metadata See a
+     *     [Sink
+     * resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks#LogSink).
+     * @param {object} [metadata.gaxOptions] Request configuration options,
+     *     outlined here:
+     * https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
+     * @param {SetSinkMetadataCallback} [callback] Callback function.
+     * @returns {Promise<SetSinkMetadataResponse>}
+     *
+     * @example
+     * ```
+     * const {Logging} = require('@google-cloud/logging');
+     * const logging = new Logging();
+     * const sink = logging.sink('my-sink');
+     *
+     * const metadata = {
+     *   filter: 'metadata.severity = ALERT'
+     * };
+     *
+     * sink.setMetadata(metadata, (err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * sink.setMetadata(metadata).then(data => {
+     *   const apiResponse = data[0];
+     * });
+     *
+     * ```
+     * @example <caption>include:samples/sinks.js</caption>
+     * region_tag:logging_update_sink
+     * Another example:
+     */
     setMetadata(metadata: SetSinkMetadata): Promise<SinkMetadataResponse>;
@@ -65,0 +281,0 @@ setMetadata(metadata: SetSinkMetadata, callback: SinkMetadataCallback): void;

build/src/v2/logging_service_v2_client.d.ts

@@ -36,3 +36,3 @@ /// <reference types="node" />
      * The options accepted by the constructor are described in detail
-     * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance).
+     * in {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance| this document}.
      * The common options are:
@@ -122,3 +122,3 @@ * @param {object} [options.credentials] - Credentials object.
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#bi-directional-streaming)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#bi-directional-streaming| documentation}
      *   for more details and examples.
@@ -192,3 +192,3 @@ * @example
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -247,3 +247,3 @@ */
      * @returns {Object}
-     *   An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).
+     *   An iterable Object that allows {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols| async iteration}.
      *   When you iterate the returned iterable, each element will be an object representing
@@ -253,3 +253,3 @@ *   [LogEntry]{@link google.logging.v2.LogEntry}. The API will be called under the hood as needed, once per the page,
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -290,3 +290,3 @@ * @example
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -313,3 +313,3 @@ */
      * @returns {Object}
-     *   An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).
+     *   An iterable Object that allows {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols| async iteration}.
      *   When you iterate the returned iterable, each element will be an object representing
@@ -319,3 +319,3 @@ *   [MonitoredResourceDescriptor]{@link google.api.MonitoredResourceDescriptor}. The API will be called under the hood as needed, once per the page,
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -375,3 +375,3 @@ * @example
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -417,3 +417,3 @@ */
      * @returns {Object}
-     *   An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).
+     *   An iterable Object that allows {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols| async iteration}.
      *   When you iterate the returned iterable, each element will be an object representing
@@ -423,3 +423,3 @@ *   string. The API will be called under the hood as needed, once per the page,
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -426,0 +426,0 @@ * @example

build/src/v2/metrics_service_v2_client.d.ts

@@ -36,3 +36,3 @@ /// <reference types="node" />
      * The options accepted by the constructor are described in detail
-     * in [this document](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance).
+     * in {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#creating-the-client-instance| this document}.
      * The common options are:
@@ -146,3 +146,3 @@ * @param {object} [options.credentials] - Credentials object.
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -173,3 +173,3 @@ */
      * @returns {Object}
-     *   An iterable Object that allows [async iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols).
+     *   An iterable Object that allows {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols| async iteration}.
      *   When you iterate the returned iterable, each element will be an object representing
@@ -179,3 +179,3 @@ *   [LogMetric]{@link google.logging.v2.LogMetric}. The API will be called under the hood as needed, once per the page,
      *   Please see the
-     *   [documentation](https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination)
+     *   {@link https://github.com/googleapis/gax-nodejs/blob/master/client-libraries.md#auto-pagination| documentation}
      *   for more details and examples.
@@ -182,0 +182,0 @@ * @example

CHANGELOG.md

@@ -7,2 +7,9 @@ # Changelog
 
+### [9.6.3](https://www.github.com/googleapis/nodejs-logging/compare/v9.6.2...v9.6.3) (2021-11-08)
+
+
+### Bug Fixes
+
+* **cloud-rad:** move comments for TSDoc ([#1181](https://www.github.com/googleapis/nodejs-logging/issues/1181)) ([51d6efd](https://www.github.com/googleapis/nodejs-logging/commit/51d6efd3341e6a02ffd130e36eb1491f410e1dc1))
+
 ### [9.6.2](https://www.github.com/googleapis/nodejs-logging/compare/v9.6.1...v9.6.2) (2021-11-01)
@@ -9,0 +16,0 @@

package.json

 {
   "name": "@google-cloud/logging-min",
-  "version": "9.6.2",
+  "version": "9.6.3",
   "description": "Stackdriver Logging Client Library for Node.js",
@@ -5,0 +5,0 @@ "keywords": [

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

2007024

increased by1.73%

Lines of code

21589

increased by4.77%

No dependency changes