com.google.cloud.logging.logback

Class LoggingAppender

java.lang.Object

ch.qos.logback.core.spi.ContextAwareBase

ch.qos.logback.core.UnsynchronizedAppenderBase<ch.qos.logback.classic.spi.ILoggingEvent>

com.google.cloud.logging.logback.LoggingAppender

All Implemented Interfaces:

ch.qos.logback.core.Appender<ch.qos.logback.classic.spi.ILoggingEvent>, ch.qos.logback.core.spi.ContextAware, ch.qos.logback.core.spi.FilterAttachable<ch.qos.logback.classic.spi.ILoggingEvent>, ch.qos.logback.core.spi.LifeCycle

public class LoggingAppender
extends ch.qos.logback.core.UnsynchronizedAppenderBase<ch.qos.logback.classic.spi.ILoggingEvent>

Logback appender for Google Cloud Logging.

Appender configuration in logback.xml:

    <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
         <!-- Optional: filter logs at and above this level -->
         <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
             <level>INFO</level>
         </filter>

         <!-- Optional: defaults to  "java.log" -->
         <log>application.log</log>

         <!-- Optional: defaults to  "ERROR" -->
         <flushLevel>WARN</flushLevel>

         <!-- Optional: defaults to  ASYNC -->
         <writeSynchronicity>SYNC</writeSynchronicity>

         <!-- Optional: defaults to  true -->
         <autoPopulateMetadata>false</autoPopulateMetadata>

         <!-- Optional: defaults to  false -->
         <redirectToStdout>true</redirectToStdout>

         <!-- Optional: auto detects on App Engine Flex, Standard, GCE and GKE, defaults to "global". See supported resource types -->
         <resourceType></resourceType>

         <!-- Optional: defaults to the default credentials of the environment -->
         <credentialsFile>/path/to/credentials/file</credentialsFile>

         <!-- Optional: defaults to the project id obtained during authentication process. Project id is also used to construct resource name of the log entries -->
         <logDestinationProjectId>String</logDestinationProjectId>

         <!-- Optional: add custom labels to log entries using LoggingEnhancer classes -->
         <enhancer>com.example.enhancers.TestLoggingEnhancer</enhancer>
         <enhancer>com.example.enhancers.AnotherEnhancer</enhancer>

         <!-- Optional: specifies if a batch's valid entries should be written even if some other entry failed due to an error. Defaults to  true -->
         <partialSuccess>true</partialSuccess>

         <!-- Optional: In the asynchronous mode the call(s) to Logging API takes place asynchronously and few calls to `write()`
         method may be batched together to compose a single call to Logging API. In order to control the batching settings,
         the `logbackBatchingSettings` section can be used as shown below.
         See [BatchingSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingSettings)
         for more info regarding parameters shown below -->
         <logbackBatchingSettings>
            <elementCountThreshold>100</elementCountThreshold>
            <requestByteThreshold>1000</requestByteThreshold>
            <delayThreshold>500</delayThreshold>
            <maxOutstandingElementCount>10000</maxOutstandingElementCount>
            <maxOutstandingRequestBytes>100000</maxOutstandingRequestBytes>
            <limitExceededBehavior>Ignore</limitExceededBehavior>
         </logbackBatchingSettings>
     </appender>
 

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_INSTRUMENTATION_VERSION
static String	JAVA_LOGBACK_LIBRARY_NAME

Fields inherited from class ch.qos.logback.core.UnsynchronizedAppenderBase

name, started

Fields inherited from class ch.qos.logback.core.spi.ContextAwareBase

context

Constructor Summary

Constructors

Constructor and Description
LoggingAppender()

Method Summary

Modifier and Type	Method and Description
void	addEnhancer(String enhancerClassName) Add extra labels using classes that implement LoggingEnhancer.
void	addLoggingEventEnhancer(String enhancerClassName)
protected void	append(ch.qos.logback.classic.spi.ILoggingEvent e)
void	flush() Deprecated.
protected com.google.cloud.logging.LoggingOptions	getLoggingOptions() Gets the LoggingOptions to use for this LoggingAppender.
com.google.cloud.logging.Synchronicity	getWriteSynchronicity() Deprecated.
void	setAutoPopulateMetadata(boolean flag) Sets the automatic population of metadata fields for ingested logs.
void	setCredentialsFile(String credentialsFile) Sets the path to the https://cloud.google.com/iam/docs/creating-managing-service-account-keys.
void	setFlushLevel(ch.qos.logback.classic.Level flushLevel) Sets a threshold for log severity level to flush all log entries that were batched so far.
void	setLog(String log) Sets the LOG_ID part of the https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.log_name for which the logs are ingested.
void	setLogbackBatchingSettings(LogbackBatchingSettings batchingSettings) Sets the LogbackBatchingSettings to be used for the asynchronous mode call(s) to Logging API
void	setLogDestinationProjectId(String projectId) Sets project ID to be used to customize log destination name for written log entries.
void	setPartialSuccess(boolean flag) Sets the flag indicating if a batch's valid entries should be written even if some other entry failed due to an error.
void	setRedirectToStdout(boolean flag) Sets the redirect of the appender's output to STDOUT instead of ingesting logs to Cloud Logging using Logging API.
void	setResourceType(String resourceType) Sets the name of the monitored resource (Optional).
void	setWriteSynchronicity(com.google.cloud.logging.Synchronicity flag) Sets the log ingestion mode.
void	start() Initialize and configure the cloud logging service.
void	stop()

Methods inherited from class ch.qos.logback.core.UnsynchronizedAppenderBase

addFilter, clearAllFilters, doAppend, getCopyOfAttachedFiltersList, getFilterChainDecision, getName, isStarted, setName, toString

Methods inherited from class ch.qos.logback.core.spi.ContextAwareBase

addError, addError, addInfo, addInfo, addStatus, addWarn, addWarn, getContext, getDeclaredOrigin, getStatusManager, setContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ch.qos.logback.core.spi.ContextAware

addError, addError, addInfo, addInfo, addStatus, addWarn, addWarn, getContext, setContext

Field Detail

JAVA_LOGBACK_LIBRARY_NAME

public static final String JAVA_LOGBACK_LIBRARY_NAME

See Also:

Constant Field Values

DEFAULT_INSTRUMENTATION_VERSION

public static final String DEFAULT_INSTRUMENTATION_VERSION

See Also:

Constant Field Values

Constructor Detail

LoggingAppender

public LoggingAppender()

Method Detail

setFlushLevel

public void setFlushLevel(ch.qos.logback.classic.Level flushLevel)

Sets a threshold for log severity level to flush all log entries that were batched so far.

Defaults to Error.

Parameters:

flushLevel - Logback log level

setLog

public void setLog(String log)

Sets the LOG_ID part of the https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.log_name for which the logs are ingested.

Parameters:

log - LOG_ID part of the name

setResourceType

public void setResourceType(String resourceType)

Sets the name of the monitored resource (Optional). If not define the appender will try to identify the resource type automatically. Currently support resource types include "gae_app", "gce_instance", "k8s_container", "cloud_run_revision" and "cloud_function". If the appender fails to identify the resource type, it will be set to "global".

Must be a one of the supported resource types.

Parameters:

resourceType - the name of the monitored resource.

setCredentialsFile

public void setCredentialsFile(String credentialsFile)

Sets the path to the https://cloud.google.com/iam/docs/creating-managing-service-account-keys. If not set the appender will use GoogleCredentials.getApplicationDefault() to authenticate.

Parameters:

credentialsFile - the path to the credentials file.

setLogDestinationProjectId

public void setLogDestinationProjectId(String projectId)

Sets project ID to be used to customize log destination name for written log entries.

Parameters:

projectId - The project ID to be used to construct the resource destination name for log entries.

setWriteSynchronicity

public void setWriteSynchronicity(com.google.cloud.logging.Synchronicity flag)

Sets the log ingestion mode. It can be one of the Synchronicity values.

Default to Synchronicity.ASYNC

Parameters:

flag - the new ingestion mode.

setAutoPopulateMetadata

public void setAutoPopulateMetadata(boolean flag)

Sets the automatic population of metadata fields for ingested logs.

Default to true.

Parameters:

flag - the metadata auto-population flag.

setRedirectToStdout

public void setRedirectToStdout(boolean flag)

Sets the redirect of the appender's output to STDOUT instead of ingesting logs to Cloud Logging using Logging API.

Default to false.

Parameters:

flag - the redirect flag.

setLogbackBatchingSettings

public void setLogbackBatchingSettings(LogbackBatchingSettings batchingSettings)

Sets the LogbackBatchingSettings to be used for the asynchronous mode call(s) to Logging API

Default to null.

Parameters:

batchingSettings - the LogbackBatchingSettings to be used for asynchronous mode call(s) to Logging API

setPartialSuccess

public void setPartialSuccess(boolean flag)

Sets the flag indicating if a batch's valid entries should be written even if some other entry failed due to an error.

Default to true.

Parameters:

flag - the partialSuccess flag.

addEnhancer

public void addEnhancer(String enhancerClassName)

Add extra labels using classes that implement LoggingEnhancer.

addLoggingEventEnhancer

public void addLoggingEventEnhancer(String enhancerClassName)

getWriteSynchronicity

@Deprecated
public com.google.cloud.logging.Synchronicity getWriteSynchronicity()

Deprecated.

Returns the current value of the ingestion mode.

The method is deprecated. Use appender configuration to set up the ingestion

Returns:

a Synchronicity value of the ingestion module.

start

public void start()

Initialize and configure the cloud logging service.

Specified by:

start in interface ch.qos.logback.core.spi.LifeCycle

Overrides:

start in class ch.qos.logback.core.UnsynchronizedAppenderBase<ch.qos.logback.classic.spi.ILoggingEvent>

append

protected void append(ch.qos.logback.classic.spi.ILoggingEvent e)

Specified by:

append in class ch.qos.logback.core.UnsynchronizedAppenderBase<ch.qos.logback.classic.spi.ILoggingEvent>

stop

public void stop()

Specified by:

stop in interface ch.qos.logback.core.spi.LifeCycle

Overrides:

stop in class ch.qos.logback.core.UnsynchronizedAppenderBase<ch.qos.logback.classic.spi.ILoggingEvent>

flush

@Deprecated
public void flush()

Deprecated.

Flushes any pending asynchronous logging writes.

getLoggingOptions

protected com.google.cloud.logging.LoggingOptions getLoggingOptions()

Gets the LoggingOptions to use for this LoggingAppender.