Package 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 "OFF" -->
         <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
    Description
    static final String
    DEFAULT_INSTRUMENTATION_VERSION
     
    static final 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
    Description
    LoggingAppender()
     

  • Method Summary

    Modifier and Type
    Method
    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
    setCredentials(com.google.auth.oauth2.GoogleCredentials credentials)
    Sets the credential to use.
    void
    setCredentialsFile(String credentialsFile)
    This method is obsolete because of a potential security risk.
    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 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 Details

  • Constructor Details

    • LoggingAppender

      public LoggingAppender()

  • Method Details

    • 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 OFF.

      Parameters:
      flushLevel - Logback log level

    • setLog

      public void setLog(String log)
      Sets the LOG_ID part of the 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

      @ObsoleteApi("This method is obsolete because of a potential security risk. Use the setCredentials() method instead") public void setCredentialsFile(String credentialsFile)
      This method is obsolete because of a potential security risk. Use the setCredentials(GoogleCredentials) method instead.

      If you know that you will be loading credential configurations of a specific type, it is recommended to use a credential-type-specific `fromStream()` method. This will ensure that an unexpected credential type with potential for malicious intent is not loaded unintentionally. You might still have to do validation for certain credential types. Please follow the recommendation for that method.

      If you are loading your credential configuration from an untrusted source and have not mitigated the risks (e.g. by validating the configuration yourself), make these changes as soon as possible to prevent security risks to your environment.

      Regardless of the method used, it is always your responsibility to validate configurations received from external sources.

      Sets the path to the credential file. If not set the appender will use GoogleCredentials.getApplicationDefault() to authenticate.

      Parameters:
      credentialsFile - the path to the credentials file.

    • setCredentials

      public void setCredentials(com.google.auth.oauth2.GoogleCredentials credentials)
      Sets the credential to use. If not set the appender will use GoogleCredentials.getApplicationDefault() to authenticate.
      Parameters:
      credentials - the GoogleCredentials to set

    • 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.