GeezerVison is showing github.com — java-logging/.readme-partials.yaml at main · googleapis/java-logging

This repository was archived by the owner on Feb 6, 2026. It is now read-only.

Expand file tree

.readme-partials.yaml

Copy path

More file actions

Latest commit

History

243 lines (194 loc) · 13.5 KB

.readme-partials.yaml

Copy path

File metadata and controls

243 lines (194 loc) · 13.5 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

custom_content: |

#### Creating an authorized service object

To make requests to Cloud Logging, you must create a service object with valid credentials.

You can then make API calls by calling methods on the Logging service object.

You can obtain credentials by using [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).

Or you can use a [Service Account](https://cloud.google.com/iam/docs/service-accounts) which is a recommended way to obtain credentials.

The credentials can be automatically inferred from your [environment](https://cloud.google.com/docs/authentication/getting-started#setting_the_environment_variable).

Then you only need the following code to create your service object:

```java

import com.google.cloud.logging.Logging;

import com.google.cloud.logging.LoggingOptions;

LoggingOptions options = LoggingOptions.getDefaultInstance();

try(Logging logging = options.getService()) {

// use logging here

}

```

For other options, see the [Authentication](https://github.com/googleapis/google-cloud-java#authentication) page.

The service object should be granted permissions to make API calls.

Each API call describes the permissions under Authorized Scopes section.

See [Logging API](https://cloud.google.com/logging/docs/reference/v2/rest) to find the required list of permissions or consult with [Access control guide](https://cloud.google.com/logging/docs/access-control) for predefined IAM roles that can be granted to the Logging service object.

#### Creating a metric

With Logging you can create logs-based metrics. Logs-based metrics allow to keep track of the number

of log messages associated to specific events. Add the following imports at the top of your file:

```java

import com.google.cloud.logging.Metric;

import com.google.cloud.logging.MetricInfo;

```

Then, to create the metric, use the following code:

```java

MetricInfo metricInfo = MetricInfo.newBuilder("test-metric", "severity >= ERROR")

.setDescription("Log entries with severity higher or equal to ERROR")

.build();

logging.create(metricInfo);

```

#### Writing log entries

For an interactive tutorial click

[![Guide Me](_static/guide-me.svg)](https://console.cloud.google.com/?walkthrough_id=logging__logging-java)

With Logging you can also write custom log entries. Add the following imports at the top of your

file:

```java

import com.google.cloud.MonitoredResource;

import com.google.cloud.logging.LogEntry;

import com.google.cloud.logging.Logging;

import com.google.cloud.logging.Payload.StringPayload;

import java.util.Collections;

```

Then, to write the log entries, use the following code:

```java

LogEntry firstEntry = LogEntry.newBuilder(StringPayload.of("message"))

.setLogName("test-log")

.setResource(MonitoredResource.newBuilder("global")

.addLabel("project_id", options.getProjectId())

.build())

.build();

logging.write(Collections.singleton(firstEntry));

```

The library supports writing log entries synchronously and asynchronously.

In the synchronous mode each call to `write()` method results in a consequent call to Logging API to write a log entry.

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.

The default mode of writing is asynchronous.

It can be configured in the `java.util.logging` handler [configuration file](https://cloud.google.com/logging/docs/setup/java#javautillogging_configuration):

```

com.google.cloud.logging.LoggingHandler.synchronicity=SYNC

```

or in the code after initiating an instance of `Logging` by calling:

```java

logging.setWriteSynchronicity(Synchronicity.SYNC);

```

NOTE:

> Writing log entries asynchronously in some Google Cloud managed environments (e.g. Cloud Functions)

> may lead to unexpected results such as absense of expected log entries or abnormal program execution.

> To avoid these unexpected results, it is recommended to use synchronous mode.

#### Controlling the batching settings

As mentioned before, 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 `LoggingOptions`

is enhanced with `BatchingSettings` which can be set as shown in example below:

```java

import com.google.api.gax.batching.BatchingSettings;

import com.google.api.gax.batching.FlowControlSettings;

import com.google.api.gax.batching.FlowController;

LoggingOptions actual =

LoggingOptions.newBuilder()

.setBatchingSettings(

BatchingSettings.newBuilder()

.setIsEnabled(true)

.setElementCountThreshold(1000L)

.setRequestByteThreshold(1048576L)

.setDelayThreshold(Duration.ofMillis(50L))

.setFlowControlSettings(

FlowControlSettings.newBuilder()

.setMaxOutstandingElementCount(100000L)

.setMaxOutstandingRequestBytes(10485760L)

.setLimitExceededBehavior(

FlowController.LimitExceededBehavior.ThrowException)

.build())

.setProjectId('Your project ID')

.build();

```

You can find more information about batching parameters see [BatchingSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingSettings).

#### Listing log entries

With Logging you can also list log entries that have been previously written. Add the following

imports at the top of your file:

```java

import com.google.api.gax.paging.Page;

import com.google.cloud.logging.LogEntry;

import com.google.cloud.logging.Logging.EntryListOption;

```

Then, to list the log entries, use the following code:

``` java

Page<LogEntry> entries = logging.listLogEntries(

EntryListOption.filter("logName=projects/" + options.getProjectId() + "/logs/test-log"));

while (entries != null) {

for (LogEntry logEntry : entries.iterateAll()) {

System.out.println(logEntry);

}

entries = entries.getNextPage();

}

```

#### Add a Cloud Logging handler to a logger

You can also register a `LoggingHandler` to a `java.util.logging.Logger` that publishes log entries

to Cloud Logging. Given the following logger:

```java

private final static Logger LOGGER = Logger.getLogger(MyClass.class.getName());

```

You can register a `LoggingHandler` with the code:

```java

LoggingHandler.addHandler(LOGGER, new LoggingHandler());

```

After that, logs generated using `LOGGER` will be also directed to Cloud Logging.

Notice that you can also register a `LoggingHandler` via the `logging.properties` configuration

file. Adding, for instance, the following line:

```

com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler

```

#### Alternative way to ingest logs in Google Cloud managed environments

If you use Java logger with the Cloud Logging Handler, you can configure the handler to output logs to `stdout` using

the [structured logging Json format](https://cloud.google.com/logging/docs/structured-logging#special-payload-fields).

To do this, add `com.google.cloud.logging.LoggingHandler.redirectToStdout=true` to the logger configuration file.

You can use this configuration when running applications in Google Cloud managed environments such as AppEngine, Cloud Run,

Cloud Function or GKE. The logger agent installed on these environments can capture STDOUT and ingest it into Cloud Logging.

The agent can parse structured logs printed to STDOUT and capture additional log metadata beside the log payload.

The parsed information includes severity, source location, user labels, http request and tracing information.

#### Auto-population of log entrys' metadata

LogEntry object metadata information such as [monitored resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource),

[Http request](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest) or

[source location](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogEntrySourceLocation)

are automatically populated with information that the library retrieves from the execution context.

The library populates only empty (set to `null`) LogEntry fields.

This behavior in the `Logging` instance can be opted out via `LoggingOptions`.

Call `LoggingOptions.Builder.setAutoPopulateMetadata(false)` to configure logging options to opt-out the metadata auto-population.

Cloud Logging handler can be configured to opt-out automatic population of the metadata using the logger configuration.

To disable the metadata auto-population add `com.google.cloud.logging.LoggingHandler.autoPopulateMetadata=false`

to the logger configuration file.

The auto-population logic populates source location _only_ for log entries with `Severity.DEBUG` severity.

The execution context of the Http request and tracing information is maintained by `ContextHandler` class.

The context is managed in the scope of the thread.

If you do not use thread pools for multi-threading the `ContextHandler` can be configured to propagate the context

to the scope of the child threads.

To enable this add `com.google.cloud.logging.ContextHandler.useInheritedContext=true` to the logger configuration file.

The library provides two methods to update the context:

* Manually set the context. You can use the following methods of the `Context.Builder` to set the context information.

Use the method `setRequest()` to setup the `HttpRequest` instance or `setRequestUrl()`, `setRequestMethod()`,

`setReferer() `, `setRemoteIp()` and `setServerIp()` to setup the fields of the `HttpRequest`.

The trace and span Ids can be set directly using `setTraceId()` and `setSpanId()` respectively.

Alternatively it can be parsed from the W3C tracing context header using `loadW3CTraceParentContext()` or

from the Google Cloud tracing context header using `loadCloudTraceContext()`.

```java

Context context = Context.newBuilder().setHttpRequest(request).setTrace(traceId).setSpanId(spanId).build();

(new ContextHandler()).setCurrentContext(context);

```

* Using [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer).

If your application uses a Web server based on Jakarta servlets (e.g. Jetty or Tomcat), you can add the servlet initializer

package to your WAR. The package implements a service provider interface (SPI) for

[javax.servlet.ServletContainerInitializer](https://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html)

and filters all servlet requests to automatically capture the execution context of the servlet request and store it using

`ContextHandler` class. The stored `Context` class instances are used to populate Http request and tracing information.

If you use Maven, to use the servlet initializer add the following dependency to your BOM:

```xml

<groupId>com.google.cloud</groupId>

<artifactId>google-cloud-logging-servlet-initializer</artifactId>

</dependency>

```

#### Population of Trace/Span ID fields in a LogEntry

Cloud Logging libraries use [trace fields within LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace) to capture trace contexts, which enables the [correlation of logs and traces](https://cloud.google.com/logging/docs/view/correlate-logs), and distributed tracing troubleshooting.

These tracing fields, including [trace](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace), [spanId](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.span_id), and [traceSampled](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace_sampled), define the trace context for a `LogEntry`.

Tracing information set manually takes precedence over information set by the following methods:

* Auto-populate Trace/Span ID from OpenTelemetry Context

If you are using OpenTelemetry and there is an active span in the OpenTelemetry Context, the `trace`, `span_id`, and `trace_sampled` fields in the log entry are populated from the active span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/java/).

* Use the [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to Populate Trace/Span ID from HTTP Headers

If trace/span Id are not manually set or auto-populated from OpenTelemetry context, you can use the [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers.

This package filters all servlet requests to automatically capture the execution context of the servlet request and stores it by using ContextHandler class. Http request and trace/span Id information are populated from the stored Context class instances.

Using this method, trace/span Id can be automatically populated from either the [W3C Traceparent](https://www.w3.org/TR/trace-context) or [X-Cloud-Trace-Context](https://cloud.google.com/trace/docs/trace-context#legacy-http-header) headers.