public class LoggingHandler extends Handler
A logging handler that outputs logs generated with java.util.logging.Logger to Cloud Logging.
Java logging levels (see java.util.logging.Level) are mapped to the following Google Cloud Logging severities:
Java Level | Cloud Logging Severity |
---|---|
SEVERE | ERROR |
WARNING | WARNING |
INFO | INFO |
CONFIG | INFO |
FINE | DEBUG |
FINER | DEBUG |
FINEST | DEBUG |
Original Java logging levels are added as labels (with levelName
and
levelValue
keys, respectively) to the corresponding Cloud Logging LogEntry. You can read
entry labels using LogEntry#getLabels(). To use logging levels that correspond to Cloud
Logging severities you can use LoggingLevel.
Configuration: By default each LoggingHandler
is initialized using the
following LogManager
configuration properties (that you can set in the
logging.properties
file). If properties are not defined (or have invalid values) then the
specified default values are used.
com.google.cloud.logging.LoggingHandler.log
the log name (defaults tojava.log
).com.google.cloud.logging.LoggingHandler.level
specifies the default level for the handler (defaults toLevel.INFO
).com.google.cloud.logging.LoggingHandler.filter
specifies the name of a Filter class to use (defaults to no filter).com.google.cloud.logging.LoggingHandler.formatter
specifies the name of a Formatter class to use (defaults to SimpleFormatter).com.google.cloud.logging.LoggingHandler.flushLevel
specifies the flush log level. When a log with this level is published, logs are transmitted to the Cloud Logging service (defaults to LoggingLevel#ERROR).com.google.cloud.logging.LoggingHandler.enhancers
specifies a comma separated list of LoggingEnhancer classes. This handler will call each enhancer list whenever it builds a LogEntry instance (defaults to empty list).com.google.cloud.logging.LoggingHandler.resourceType
the type name to use when creating the default MonitoredResource (defaults to auto-detected resource type, else "global").com.google.cloud.logging.Synchronicity
the synchronicity of the write method to use to write logs to the Cloud Logging service (defaults to Synchronicity#ASYNC).com.google.cloud.logging.LoggingHandler.autoPopulateMetadata
is a boolean flag that opts-out the population of the log entries metadata before the logs are sent to Cloud Logging (defaults totrue
).com.google.cloud.logging.LoggingHandler.redirectToStdout
is a boolean flag that opts-in redirecting the output of the handler to STDOUT instead of ingesting logs to Cloud Logging using Logging API (defaults tofalse
). Redirecting logs can be used in Google Cloud environments with installed logging agent to delegate log ingestions to the agent. Redirected logs are formatted as one line Json string following the structured logging guidelines. This flag is deprecated; usecom.google.cloud.logging.LoggingHandler.logTarget
instead.com.google.cloud.logging.LoggingHandler.logTarget
is an enumeration controlling log routing (defaults toCLOUD_LOGGING
). If set to STDOUT or STDERR, logs will be printed to the corresponding stream in the Json format that can be parsed by the logging agent. If set to CLOUD_LOGGING, logs will be sent directly to the Google Cloud Logging API.
To add a LoggingHandler
to an existing Logger and be sure to avoid infinite
recursion when logging, use the #addHandler(Logger, LoggingHandler) method. Alternatively
you can add the handler via logging.properties
. For example using the following line:
com.example.mypackage.handlers=com.google.cloud.logging.LoggingHandler
See Also: Structured logging
Static Methods
addHandler(Logger logger, LoggingHandler handler)
public static void addHandler(Logger logger, LoggingHandler handler)
Adds the provided LoggingHandler
to logger
. Use this method to register Cloud
Logging handlers instead of Logger#addHandler(Handler) to avoid infinite recursion when
logging.
Name | Description |
logger | Logger |
handler | LoggingHandler |
Constructors
LoggingHandler()
public LoggingHandler()
Creates an handler that publishes messages to Cloud Logging.
LoggingHandler(String log)
public LoggingHandler(String log)
Creates a handler that publishes messages to Cloud Logging.
Name | Description |
log | String the name of the log to which log entries are written |
LoggingHandler(String log, LoggingOptions options)
public LoggingHandler(String log, LoggingOptions options)
Creates a handler that publishes messages to Cloud Logging.
Name | Description |
log | String the name of the log to which log entries are written |
options | LoggingOptions options for the Cloud Logging service |
LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource)
public LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource)
Creates a handler that publishes messages to Cloud Logging.
Name | Description |
log | String the name of the log to which log entries are written |
options | LoggingOptions options for the Cloud Logging service |
monitoredResource | com.google.cloud.MonitoredResource the monitored resource to which log entries refer. If it is null then a default resource is created based on the project ID and deployment environment. |
LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource, List<LoggingEnhancer> enhancers)
public LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource, List<LoggingEnhancer> enhancers)
Creates a handler that publishes messages to Cloud Logging.
Name | Description |
log | String the name of the log to which log entries are written |
options | LoggingOptions options for the Cloud Logging service |
monitoredResource | com.google.cloud.MonitoredResource the monitored resource to which log entries refer. If it is null then a default resource is created based on the project ID and deployment environment. |
enhancers | List<LoggingEnhancer> List of LoggingEnhancer instances used to enhance anyLogEntry instances built by this handler. |
LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource, List<LoggingEnhancer> enhancers, LogDestinationName destination)
public LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource, List<LoggingEnhancer> enhancers, LogDestinationName destination)
Creates a handler that publishes messages to Cloud Logging. Auto-population of the logs
metadata can be opted-out in options
argument or in the configuration file. At least
one flag LoggingOptions or LoggingConfig has to be explicitly set to
false
in order to opt-out the metadata auto-population.
Name | Description |
log | String the name of the log to which log entries are written |
options | LoggingOptions options for the Cloud Logging service |
monitoredResource | com.google.cloud.MonitoredResource the monitored resource to which log entries refer. If it is null then a default resource is created based on the project ID and deployment environment. |
enhancers | List<LoggingEnhancer> List of LoggingEnhancer instances used to enhance anyLogEntry instances built by this handler. |
destination | LogDestinationName the log destination LogDestinationName (see 'logName' parameter in https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry) |
Methods
close()
public synchronized void close()
Closes the handler and the associated Logging object.
flush()
public void flush()
getAutoPopulateMetadata()
public Boolean getAutoPopulateMetadata()
Gets the metadata auto population flag.
Type | Description |
Boolean |
getFlushLevel()
public Level getFlushLevel()
Get the flush log level.
Type | Description |
Level |
getLogTarget()
public LoggingHandler.LogTarget getLogTarget()
Type | Description |
LoggingHandler.LogTarget |
getRedirectToStdout()
public Boolean getRedirectToStdout()
Type | Description |
Boolean |
getSynchronicity()
public Synchronicity getSynchronicity()
Get the flush log level.
Type | Description |
Synchronicity |
logEntryFor(LogRecord record)
protected LogEntry.Builder logEntryFor(LogRecord record)
Name | Description |
record | LogRecord |
Type | Description |
LogEntry.Builder |
publish(LogRecord record)
public void publish(LogRecord record)
Name | Description |
record | LogRecord |
setAutoPopulateMetadata(boolean value)
public void setAutoPopulateMetadata(boolean value)
Sets the metadata auto population flag.
Name | Description |
value | boolean |
setFlushLevel(Level flushLevel)
public void setFlushLevel(Level flushLevel)
Sets minimum logging level to log immediately and flush any pending writes.
Name | Description |
flushLevel | Level minimum log level to trigger flush |
setLogTarget(LoggingHandler.LogTarget value)
public void setLogTarget(LoggingHandler.LogTarget value)
Configure the destination for ingested logs. If set to STDOUT or STDERR, logs will be printed to the corresponding stream in the Json format that can be parsed by the logging agent. If set to CLOUD_LOGGING, logs will be sent directly to the Google Cloud Logging API.
This method is mutually exclusive with #setRedirectToStdout(boolean).
Name | Description |
value | LoggingHandler.LogTarget |
setRedirectToStdout(boolean value) (deprecated)
public void setRedirectToStdout(boolean value)
Deprecated. Use #setLogTarget(LogTarget).
Enable/disable redirection to STDOUT. If set to true
, logs will be printed to STDOUT in
the Json format that can be parsed by the logging agent. If set to false
, logs will be
ingested to Cloud Logging by calling Logging API.
This method is mutually exclusive with #setLogTarget(LogTarget).
Name | Description |
value | boolean |
setSynchronicity(Synchronicity synchronicity)
public void setSynchronicity(Synchronicity synchronicity)
Sets synchronicity of logging writes. By default, writes are asynchronous.
Name | Description |
synchronicity | Synchronicity Synchronicity |