@@ -134,3 +134,62 @@ custom_content: |
134134 ```
135135 com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler
136136 ```
137+
138+ #### Alternative way to ingest logs in Google Cloud managed environments
139+
140+ If you use Java logger with the Cloud Logging Handler, you can configure the handler to output logs to `stdout` using
141+ the [structured logging Json format](https://cloud.google.com/logging/docs/structured-logging#special-payload-fields).
142+ To do this, add `com.google.cloud.logging.LoggingHandler.redirectToStdout=true` to the logger configuration file.
143+ You can use this configuration when running applications in Google Cloud managed environments such as AppEngine, Cloud Run,
144+ Cloud Function or GKE. The logger agent installed on these environments can capture STDOUT and ingest it into Cloud Logging.
145+ The agent can parse structured logs printed to STDOUT and capture additional log metadata beside the log payload.
146+ The parsed information includes severity, source location, user labels, http request and tracing information.
147+
148+ #### Auto-population of log entrys' metadata
149+
150+ LogEntry object metadata information such as [monitored resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource),
151+ [Http request](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest) or
152+ [source location](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogEntrySourceLocation)
153+ are automatically populated with information that the library retrieves from the execution context.
154+ The library populates only empty (set to `null`) LogEntry fields.
155+ This behavior in the `Logging` instance can be opted out via `LoggingOptions`.
156+ Call `LoggingOptions.Builder.setAutoPopulateMetadata(false)` to configure logging options to opt-out the metadata auto-population.
157+ Cloud Logging handler can be configured to opt-out automatic population of the metadata using the logger configuration.
158+ To disable the metadata auto-population add `com.google.cloud.logging.LoggingHandler.autoPopulateMetadata=false`
159+ to the logger configuration file.
160+
161+ The auto-population logic populates source location _only_ for log entries with `Severity.DEBUG` severity.
162+ The execution context of the Http request and tracing information is maintained by `ContextHandler` class.
163+ The context is managed in the scope of the thread.
164+ If you do not use thread pools for multi-threading the `ContextHandler` can be configured to propagate the context
165+ to the scope of the child threads.
166+ To enable this add `com.google.cloud.logging.ContextHandler.useInheritedContext=true` to the logger configuration file.
167+ The library provides two methods to update the context:
168+
169+ * Manually set the context. You can use the following methods of the `Context.Builder` to set the context information.
170+ Use the method `setRequest()` to setup the `HttpRequest` instance or `setRequestUrl()`, `setRequestMethod()`,
171+ `setReferer() `, `setRemoteIp()` and `setServerIp()` to setup the fields of the `HttpRequest`.
172+ The trace and span Ids can be set directly using `setTraceId()` and `setSpanId()` respectively.
173+ Alternatively it can be parsed from the W3C tracing context header using `loadW3CTraceParentContext()` or
174+ from the Google Cloud tracing context header using `loadCloudTraceContext()`.
175+
176+ ```java
177+ Context context = Context.newBuilder().setHttpRequest(request).setTrace(traceId).setSpanId(spanId).build();
178+ (new ContextHandler()).setCurrentContext(context);
179+ ```
180+
181+ * Using [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer).
182+ If your application uses a Web server based on Jakarta servlets (e.g. Jetty or Tomcat), you can add the servlet initializer
183+ package to your WAR. The package implements a service provider interface (SPI) for
184+ [javax.servlet.ServletContainerInitializer](https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html)
185+ and filters all servlet requests to automatically capture the execution context of the servlet request and store it using
186+ `ContextHandler` class. The stored `Context` class instances are used to populate Http request and tracing information.
187+ If you use Maven, to use the servlet initializer add the following dependency to your BOM:
188+
189+ ```xml
190+ <dependency>
191+ <groupId>com.google.cloud</groupId>
192+ <artifactId>google-cloud-logging-servlet-initializer</artifactId>
193+ </dependency>
194+ ```
195+
0 commit comments