.readme-partials.yaml

custom_content: |
  ### Usage
  Add the appender to your [Logback configuration](https://logback.qos.ch/manual/configuration.html) `logback.xml`.
  See [Logback filters](https://logback.qos.ch/manual/filters.html#thresholdFilter) for information on filtering log output and
   [encoders](https://logback.qos.ch/manual/encoders.html) for information on formatting.


  ```xml
  <configuration>
    <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". -->
      <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 
      See [partial_success](https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/write#body.request_body.FIELDS.partial_success) for more info -->
      <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>

    <root level="info">
      <appender-ref ref="CLOUD" />
    </root>
  </configuration>
  ```

  In your code:

  ```java
  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;

  public class TestLogger {
      private final Logger logger = LoggerFactory.getLogger(TestLogger.class);

      public void log(String name) {
          logger.info("This is a test");
      }

      public static void main(String[] args) {
          TestLogger testLogger = new TestLogger();
          testLogger.log("test");
      }
  }
  ```

  ### Populate log entries with metadata

  The library provides multiple ways to enrich log entries with additional information.
  You can select one or more ways to customize log entries that will be written into Cloud Logging.

  * Manually update a log entry using [`LoggingEnhancer`]
  (https://github.com/googleapis/java-logging/blob/main/google-cloud-logging/src/main/java/com/google/cloud/logging/.
  * Use [`ILoggingEvent`](https://logback.qos.ch/apidocs/ch/qos/logback/classic/spi/ILoggingEvent.html) to update a log entry with [`LoggingEventEnhancer`]
  (https://github.com/googleapis/java-logging-logback/blob/main/src/main/java/com/google/cloud/logging/logback/LoggingEventEnhancer.java).
  * Enable [auto-population](https://github.com/googleapis/java-logging#auto-population-of-log-entrys-metadata) of the `LogEntry` metadata using the `autoPopulateMetadata` configuration flag.

  #### Optimize log ingestion

  By default, the appender will ingest log entries asynchronously by calling Logging API.
  Multiple calls may be aggregated before being sent to improve use of API quota and bandwidth.
  You can set the `writeSynchronicity` configuration flag to `SYNC` if they want to ingest log entries synchronously.
  Note that configuring synchronous ingestion will probably result in performance penalties to your applications.
  If you plan to deploy your application in one of Google Cloud managed environments (e.g. Cloud Run, Cloud Function or App Engine),
  you can leverage the support provided by the implicit logging agent and the [structured logging](https://cloud.google.com/logging/docs/structured-logging) feature.
  To use it, set the `redirectToStdout` configuration flag to `true`.
  This flag instructs the appender to print the log entries to `stdout` instead of ingesting them using Logging API.
  The log entries are printed using the [structured logging Json format](https://cloud.google.com/logging/docs/structured-logging#special-payload-fields).
  In result, the logging agent will be responsible for ingesting the logs to Logging API.
  Note that using the structured logging Json format you cannot control the log name where the logs will be ingested.
  The logs will be ingested into the project that hosts the environment where your application is running.
  The configuration `logDestinationProjectId` will be ignored.