Class Log (10.1.1)

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

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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

alert(entry, callback)

alert(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
void

assignSeverityToEntries_(entries, severity)

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

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

Parameters
NameDescription
entries Entry | Entry[]

Log entries.

severity string

The desired severity level.

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

critical(entry, callback)

critical(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

debug(entry, callback)

debug(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
void

delete(gaxOptions)

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

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

Returns
TypeDescription
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
NameDescription
gaxOptions CallOptions
callback DeleteCallback
Returns
TypeDescription
void

delete(callback)

delete(callback: DeleteCallback): void;
Parameter
NameDescription
callback DeleteCallback
Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

callback ApiResponseCallback

Callback function.

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
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
NameDescription
metadata LogEntry

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

Returns
TypeDescription
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
NameDescription
data string | {}
Returns
TypeDescription
Entry

entry(metadata, data)

entry(metadata?: LogEntry, data?: string | {}): Entry;
Parameters
NameDescription
metadata LogEntry
data string | {}
Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

error(entry, callback)

error(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
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
NameDescription
projectId string
name string
Returns
TypeDescription
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
NameDescription
options GetEntriesRequest
Returns
TypeDescription
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
NameDescription
callback GetEntriesCallback
Returns
TypeDescription
void

getEntries(options, callback)

getEntries(options: GetEntriesRequest, callback: GetEntriesCallback): void;
Parameters
NameDescription
options GetEntriesRequest
callback GetEntriesCallback
Returns
TypeDescription
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
NameDescription
options GetEntriesRequest
Returns
TypeDescription
import("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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

info(entry, callback)

info(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

notice(entry, callback)

notice(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
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
NameDescription
options TailEntriesRequest
Returns
TypeDescription
import("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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

warning(entry, callback)

warning(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]

A log entry, or array of entries, to write.

options WriteOptions

Write options

Returns
TypeDescription
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
NameDescription
entry Entry | Entry[]
options WriteOptions
callback ApiResponseCallback
Returns
TypeDescription
void

write(entry, callback)

write(entry: Entry | Entry[], callback: ApiResponseCallback): void;
Parameters
NameDescription
entry Entry | Entry[]
callback ApiResponseCallback
Returns
TypeDescription
void