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.
Package
@google-cloud/loggingExample
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
|
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
|
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
|
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.
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
|
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
|
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.
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} |
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
|
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.
Parameter | |
---|---|
Name | Description |
options |
GetEntriesRequest
|
Returns | |
---|---|
Type | Description |
Promise<GetEntriesResponse> | {Promise
|
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. |
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
|
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
|
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. |
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
|
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.
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
|
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 |