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
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.
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
;
Returns
Type
Description
void
alert(entry, callback)
alert
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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.
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.
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
;
Returns
Type
Description
void
critical(entry, callback)
critical
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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.
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
;
Returns
Type
Description
void
debug(entry, callback)
debug
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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.
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
;
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 ).
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 | {}
entry(metadata, data)
entry
(
metadata
?:
LogEntry
,
data
?:
string
|
{})
:
Entry
;
Parameters
Name
Description
metadata
LogEntry
data
string | {}
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.
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
;
Returns
Type
Description
void
error(entry, callback)
error
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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
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
;
Returns
Type
Description
void
getEntries(options, callback)
getEntries
(
options
:
GetEntriesRequest
,
callback
:
GetEntriesCallback
)
:
void
;
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.
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
;
Returns
Type
Description
void
info(entry, callback)
info
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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.
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
;
Returns
Type
Description
void
notice(entry, callback)
notice
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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.
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
;
Returns
Type
Description
void
warning(entry, callback)
warning
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
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.
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
;
Returns
Type
Description
void
write(entry, callback)
write
(
entry
:
Entry
|
Entry
[],
callback
:
ApiResponseCallback
)
:
void
;
Returns
Type
Description
void
