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:

  // 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 write to, e.g. my-log';

  const log = logging.log(logName);

  // Modify this resource to match a resource in your project
  // See
  // https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/MonitoredResource
  const resource = {
    // This example targets the "global" resource for simplicity
    type: 'global',
  };

  // A text log entry
  const entry = log.entry({resource}, 'Hello, world!');

  // A structured log entry
  const secondEntry = log.entry(
    {resource: resource},
    {
      name: 'King Arthur',
      quest: 'Find the Holy Grail',
      favorite_color: 'Blue',
    }
  );

  async function writeLogEntry() {
    // Save the two log entries. You can write entries one at a time, but it is
    // best to write multiple entires together in a batch.
    await log.write([entry, secondEntry]);
    console.log(`Wrote to ${logName}`);
  }
  writeLogEntry();

include:samples/logs.js

region_tag:logging_write_log_entry_advanced
Another example: