Class Log (11.0.0)

A log is a named collection of entries, each entry representing a timestamped event. Logs can be produced by Google Cloud Platform services, by third-party services, or by your applications. For example, the log apache-access is produced by the Apache Web Server, but the log compute.googleapis.com/activity_log is produced by Google Compute Engine.

See Introduction to Logs

Package

@google-cloud/logging

Example


import {Logging} from '@google-cloud/logging';
import {LogOptions} from '@google-cloud/logging/build/src/log';
const options: LogOptions = {
  maxEntrySize: 256,
  jsonFieldsToTruncate: [
    'jsonPayload.fields.metadata.structValue.fields.custom.stringValue',
  ],
  defaultWriteDeleteCallback: (err: any) => {
    if (err) {
      console.log('Error: ' + err);
    }
  },
};
const logging = new Logging();
const log = logging.log('syslog', options);

Constructors

(constructor)(logging, name, options)

constructor(logging: Logging, name: string, options?: LogOptions);

Constructs a new instance of the Log class

Parameters
Name	Description
`logging`	`Logging`
`name`	`string`
`options`	`LogOptions`

Properties

defaultWriteDeleteCallback

defaultWriteDeleteCallback?: ApiResponseCallback;

formattedName_

formattedName_: string;

jsonFieldsToTruncate

jsonFieldsToTruncate: string[];

logging

logging: Logging;

maxEntrySize

maxEntrySize?: number;

name

name: string;

partialSuccess

partialSuccess: boolean;

removeCircular_

removeCircular_: boolean;

Methods

alert(entry, options)

alert(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "ALERT".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

alert(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

alert(entry, callback)

alert(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

assignSeverityToEntries_(entries, severity)

static assignSeverityToEntries_(entries: Entry | Entry[], severity: string): Entry[];

Return an array of log entries with the desired severity assigned.

Parameters
Name	Description
`entries`	`Entry \| Entry[]` Log entries.
`severity`	`string` The desired severity level.

Returns
Type	Description
`Entry[]`

critical(entry, options)

critical(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "CRITICAL".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

critical(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

critical(entry, callback)

critical(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

debug(entry, options)

debug(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "DEBUG".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

debug(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

debug(entry, callback)

debug(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

delete(gaxOptions)

delete(gaxOptions?: CallOptions): Promise<ApiResponse>;

Delete the log.

See projects.logs.delete API Documentation

Parameter
Name	Description
`gaxOptions`	`CallOptions` Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.

Returns

Type Description

Promise<ApiResponse>

{Promise

Examples


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

Another example:


  // Imports the Google Cloud client library
  const {Logging} = require('@google-cloud/logging');

  // Creates a client
  const logging = new Logging();

  /**
   * TODO(developer): Uncomment the following line to run the code.
   */
  // const logName = 'Name of the log to delete, e.g. my-log';

  const log = logging.log(logName);

  async function deleteLog() {
    // Deletes a logger and all its entries.
    // Note that a deletion can take several minutes to take effect.
    // See https://googleapis.dev/nodejs/logging/latest/Log.html#delete
    await log.delete();
    console.log(`Deleted log: ${logName}`);
  }
  deleteLog();

delete(gaxOptions, callback)

delete(gaxOptions: CallOptions, callback: DeleteCallback): void;

Parameters
Name	Description
`gaxOptions`	`CallOptions`
`callback`	`DeleteCallback`

Returns
Type	Description
`void`

delete(callback)

delete(callback: DeleteCallback): void;

Parameter
Name	Description
`callback`	`DeleteCallback`

Returns
Type	Description
`void`

emergency(entry, options, callback)

emergency(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Write a log entry with a severity of "EMERGENCY".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options
`callback`	`ApiResponseCallback` Callback function.

Returns

Type Description

void

{Promise

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, callback)

emergency(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

entry(metadata)

entry(metadata?: LogEntry): Entry;

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 .

Note, Cloud Logging Quotas and limits dictates that the maximum log entry size, including all [LogEntry Resource properties]https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry, cannot exceed _approximately_ 256 KB.

See LogEntry JSON representation

Parameter
Name	Description
`metadata`	`LogEntry` See a [LogEntry Resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry).

Returns
Type	Description
`Entry`	{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(data)

entry(data?: string | {}): Entry;

Parameter
Name	Description
`data`	`string \| {}`

Returns
Type	Description
`Entry`

entry(metadata, data)

entry(metadata?: LogEntry, data?: string | {}): Entry;

Parameters
Name	Description
`metadata`	`LogEntry`
`data`	`string \| {}`

Returns
Type	Description
`Entry`

error(entry, options)

error(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "ERROR".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

error(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

error(entry, callback)

error(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

formatName_(projectId, name)

static formatName_(projectId: string, name: string): string;

Format the name of a log. A log's full name is in the format of 'projects/{projectId}/logs/{logName}'.

Parameters
Name	Description
`projectId`	`string`
`name`	`string`

Returns
Type	Description
`string`	{string}

getEntries(options)

getEntries(options?: GetEntriesRequest): Promise<GetEntriesResponse>;

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

Parameter
Name	Description
`options`	`GetEntriesRequest`

Returns

Type Description

Promise<GetEntriesResponse>

{Promise

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(callback)

getEntries(callback: GetEntriesCallback): void;

Parameter
Name	Description
`callback`	`GetEntriesCallback`

Returns
Type	Description
`void`

getEntries(options, callback)

getEntries(options: GetEntriesRequest, callback: GetEntriesCallback): void;

Parameters
Name	Description
`options`	`GetEntriesRequest`
`callback`	`GetEntriesCallback`

Returns
Type	Description
`void`

getEntriesStream(options)

getEntriesStream(options: GetEntriesRequest): import("stream").Duplex;

This method is a wrapper around {module:logging#getEntriesStream}, but with a filter specified to only return {module:logging/entry} objects from this log.

Log#getEntriesStream

Parameter
Name	Description
`options`	`GetEntriesRequest`

Returns
Type	Description
`import("stream")."\"stream\"".internal.Duplex`	{ReadableStream} A readable stream that emits Entry instances.

Example


const {Logging} = require('@google-cloud/logging');
const logging = new Logging();
const log = logging.log('my-log');

log.getEntriesStream()
  .on('error', console.error)
  .on('data', entry => {
    // `entry` is a Cloud Logging entry object.
    // See the `data` property to read the data from the entry.
  })
  .on('end', function() {
    // All entries retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
log.getEntriesStream()
  .on('data', function(entry) {
    this.end();
  });

info(entry, options)

info(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "INFO".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

info(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

info(entry, callback)

info(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

notice(entry, options)

notice(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "NOTICE".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

notice(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

notice(entry, callback)

notice(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

tailEntries(options)

tailEntries(options?: TailEntriesRequest): import("stream").Duplex;

This method is a wrapper around {module:logging#tailEntries}, but with a filter specified to only return {module:logging/entry} objects from this log.

Log#tailEntries

Parameter
Name	Description
`options`	`TailEntriesRequest`

Returns
Type	Description
`import("stream")."\"stream\"".internal.Duplex`	{DuplexStream} A duplex stream that emits TailEntriesResponses containing an array of Entry instances.

Example


const {Logging} = require('@google-cloud/logging');
const logging = new Logging();
const log = logging.log('my-log');

log.tailEntries()
  .on('error', console.error)
  .on('data', resp => {
    console.log(resp.entries);
    console.log(resp.suppressionInfo);
  })
  .on('end', function() {
    // All entries retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
log.tailEntries()
  .on('data', function(entry) {
    this.end();
  });

warning(entry, options)

warning(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write a log entry with a severity of "WARNING".

This is a simple wrapper around . All arguments are the same as documented there.

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

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, options, callback)

warning(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

warning(entry, callback)

warning(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

write(entry, options)

write(entry: Entry | Entry[], options?: WriteOptions): Promise<ApiResponse>;

Write log entries to Cloud Logging.

Note, Cloud Logging Quotas and limits dictates that the maximum cumulative size of all entries per write, including all [LogEntry Resource properties]https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry, cannot exceed _approximately_ 10 MB.

See entries.write API Documentation

Parameters
Name	Description
`entry`	`Entry \| Entry[]` A log entry, or array of entries, to write.
`options`	`WriteOptions` Write options

Returns

Type Description

Promise<ApiResponse>

{Promise

Examples


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

Another example:


  const {Logging} = require('@google-cloud/logging');
  const logging = new Logging();

  /**
   * TODO(developer): Uncomment the following line and replace with your values.
   */
  // const logName = 'my-log';
  const log = logging.log(logName);

  // A text log entry
  const text_entry = log.entry('Hello world!');

  // A json log entry with additional context
  const metadata = {
    severity: 'WARNING',
    labels: {
      foo: 'bar',
    },
    // A default log resource is added for some GCP environments
    // This log resource can be overwritten per spec:
    // https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource
    resource: {
      type: 'global',
    },
  };

  const message = {
    name: 'King Arthur',
    quest: 'Find the Holy Grail',
    favorite_color: 'Blue',
  };

  const json_Entry = log.entry(metadata, message);

  async function writeLogEntry() {
    // Asynchronously write the log entry
    await log.write(text_entry);

    // Asynchronously batch write the log entries
    await log.write([text_entry, json_Entry]);

    // Let the logging library dispatch logs
    log.write(text_entry);

    console.log(`Wrote to ${logName}`);
  }
  writeLogEntry();

Another example:


  // [START logging_http_request]
  /*
  const projectId = 'YOUR_PROJECT_ID'; // Your Google Cloud Platform project ID
  const logName = 'my-log'; // The name of the log to write to
  const requestMethod = 'GET'; // GET, POST, PUT, etc.
  const requestUrl = 'http://www.google.com';
  const status = 200;
  const userAgent = `my-user-agent/1.0.0`;
  const latencySeconds = 3;
  const responseSize = 256; // response size in bytes.
  */

  // Imports the Google Cloud client library
  const {Logging} = require('@google-cloud/logging');

  // Creates a client
  const logging = new Logging({projectId});

  // Selects the log to write to
  const log = logging.log(logName);

  // The data to write to the log
  const text = 'Hello, world!';

  // The metadata associated with the entry
  const metadata = {
    resource: {type: 'global'},
    httpRequest: {
      requestMethod,
      requestUrl,
      status,
      userAgent,
      latency: {
        seconds: latencySeconds,
      },
      responseSize,
    },
  };

  // Prepares a log entry
  const entry = log.entry(metadata, text);

  // Writes the log entry
  async function writeLog() {
    await log.write(entry);
    console.log(`Logged: ${text}`);
  }
  writeLog();

write(entry, options, callback)

write(entry: Entry | Entry[], options: WriteOptions, callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`options`	`WriteOptions`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`

write(entry, callback)

write(entry: Entry | Entry[], callback: ApiResponseCallback): void;

Parameters
Name	Description
`entry`	`Entry \| Entry[]`
`callback`	`ApiResponseCallback`

Returns
Type	Description
`void`