Log

Log

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.

Constructor

new Log(logging, name, optionsopt)

Parameters:
Name Type Attributes Description
logging Logging

Logging instance.

name string

Name of the log.

options object <optional>

Configuration object.

Properties
Name Type Attributes Description
removeCircular boolean <optional>

Replace circular references in logged objects with a string value, [Circular]. (Default: false)

See:
Example
const {Logging} = require('@google-cloud/logging');
const logging = new Logging();
const log = logging.log('syslog');

Members

name

Methods

alert(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

critical(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

debug(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

(async) delete(gaxOptionsopt, callbackopt) → {Promise.<DeleteLogResponse>}

Delete the log.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

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

callback DeleteLogCallback <optional>

Callback function.

Returns:
Type Description
Promise.<DeleteLogResponse>
See:
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();

emergency(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

entry(metadatanullable, data) → {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 Log#write.

Note, Cloud Logging Quotas and limits dictates that the maximum log entry size, including all LogEntry Resource properties, cannot exceed approximately 256 KB.

Parameters:
Name Type Attributes Description
metadata object <nullable>

See a LogEntry Resource.

data object | string

The data to use as the value for this log entry.

Returns:
Type Description
Entry
See:
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'
//   }
// }

error(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

(async) getEntries(queryopt, callbackopt) → {Promise.<GetEntriesResponse>}

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

Parameters:
Name Type Attributes Description
query GetEntriesRequest <optional>

Query object for listing entries.

callback GetEntriesCallback <optional>

Callback function.

Returns:
Type Description
Promise.<GetEntriesResponse>
See:
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 Stackdriver 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];
});

getEntriesStream(queryopt) → {ReadableStream}

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

Parameters:
Name Type Attributes Description
query GetEntriesRequest <optional>

Query object for listing entries.

Returns:
Type Description
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 Stackdriver 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, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

notice(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

warning(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

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

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

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
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];
});

(async) write(entry, optionsopt, nullable, callbackopt) → {Promise.<LogWriteResponse>}

Write log entries to Stackdriver Logging.

Note, Cloud Logging Quotas and limits dictates that the maximum cumulative size of all entries per write, including all LogEntry Resource properties, cannot exceed approximately 10 MB.

Parameters:
Name Type Attributes Description
entry Entry | Array.<Entry>

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

options WriteOptions <optional>
<nullable>

Write options

callback LogWriteCallback <optional>

Callback function.

Returns:
Type Description
Promise.<LogWriteResponse>
See:
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() {
    // Synchronously write the log entry
    await log.write(text_entry);

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

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

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

include:samples/logs.js

region_tag:logging_write_log_entry_advanced
Another example: