Skip to content

Commit

Permalink
feat: enable auto-population of missing metadata in logs and printing…
Browse files Browse the repository at this point in the history 
… structured logs to stdout (#654)

* feat: add support for metadata auto-population and redirection to STDOUT (#649)

Add configuration to opt-out metadata auto-population.
Add configuration to redirect appender output to stdout.
Add relevant unit tests.
Refactor unit tests.
Improve javadoc comments for methods.
Remove warnings.
Make methods with no modifier to be private.

* 🦉 Updates from OwlBot

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
  • Loading branch information
@minherz @gcf-owl-bot
minherz and gcf-owl-bot[bot] committed Jan 18, 2022
1 parent 8f99e75 commit 6530782
Show file tree
Hide file tree
Showing 6 changed files with 411 additions and 258 deletions.
42 changes: 39 additions & 3 deletions .readme-partials.yaml
View file
Expand Up @@ -19,7 +19,16 @@ custom_content: |
<!-- Optional: defaults to "ERROR" -->
<flushLevel>WARNING</flushLevel>
<!-- Optional: auto detects on App Engine Flex, Standard, GCE and GKE, defaults to "global". See supported resource types -->
<!-- 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 -->
Expand All @@ -39,7 +48,7 @@ custom_content: |
</configuration>
```
In your code :
In your code:
```java
import org.slf4j.Logger;
Expand All @@ -57,4 +66,31 @@ custom_content: |
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.
41 changes: 39 additions & 2 deletions README.md
View file
Expand Up @@ -90,7 +90,16 @@ See [Logback filters](https://logback.qos.ch/manual/filters.html#thresholdFilter
<!-- Optional: defaults to "ERROR" -->
<flushLevel>WARNING</flushLevel>

<!-- Optional: auto detects on App Engine Flex, Standard, GCE and GKE, defaults to "global". See supported resource types -->
<!-- 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 -->
Expand All @@ -110,7 +119,7 @@ See [Logback filters](https://logback.qos.ch/manual/filters.html#thresholdFilter
</configuration>
```

In your code :
In your code:

```java
import org.slf4j.Logger;
Expand All @@ -130,6 +139,34 @@ public class TestLogger {
}
```

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




## Samples
Expand Down

0 comments on commit 6530782

Please sign in to comment.