labels = new HashMap<>();
+ private Operation operation;
+ private String trace;
+ private String spanId;
+ private boolean traceSampled;
+ private SourceLocation sourceLocation;
+ private Payload payload;
+ private LogDestinationName destination;
+
+ Builder(Payload payload) {
+ this.payload = payload;
+ }
+
+ Builder(LogEntry entry) {
+ this.logName = entry.logName;
+ this.resource = entry.resource;
+ this.timestamp = entry.timestamp;
+ this.receiveTimestamp = entry.receiveTimestamp;
+ this.severity = entry.severity;
+ this.insertId = entry.insertId;
+ this.httpRequest = entry.httpRequest;
+ this.labels = new HashMap<>(entry.labels);
+ this.operation = entry.operation;
+ this.trace = entry.trace;
+ this.spanId = entry.spanId;
+ this.traceSampled = entry.traceSampled;
+ this.sourceLocation = entry.sourceLocation;
+ this.payload = entry.payload;
+ this.destination = entry.destination;
+ }
+
+ /**
+ * Sets the name of the log to which this log entry belongs. The log name must be less than 512
+ * characters long and can only include the following characters: upper and lower case
+ * alphanumeric characters: {@code [A-Za-z0-9]}; and punctuation characters: {@code _-./}. The
+ * forward-slash ({@code /}) characters in the log name must be URL-encoded. Examples: {@code
+ * syslog}, {@code library.googleapis.com%2Fbook_log}.
+ */
+ @CanIgnoreReturnValue
+ public Builder setLogName(String logName) {
+ this.logName = logName;
+ return this;
+ }
+
+ /**
+ * Sets the monitored resource associated with this log entry. Example: a log entry that reports
+ * a database error would be associated with the monitored resource designating the particular
+ * database that reported the error.
+ */
+ @CanIgnoreReturnValue
+ public Builder setResource(MonitoredResource resource) {
+ this.resource = resource;
+ return this;
+ }
+
+ /**
+ * Sets the time at which the event described by the log entry occurred, in milliseconds. If
+ * omitted, the Logging service will use the time at which the log entry is received.
+ *
+ * @deprecated This method is no longer recommended to setup the entry timestamp.
+ * Use {@link #setTimestamp(Instant)} instead.
+ */
+ @CanIgnoreReturnValue
+ @Deprecated
+ public Builder setTimestamp(long milliseconds) {
+ this.timestamp = Instant.ofEpochMilli(milliseconds);
+ return this;
+ }
+
+ /**
+ * Sets the time at which the event described by the log entry occurred. If omitted, the Logging
+ * service will use the time at which the log entry is received.
+ */
+ @CanIgnoreReturnValue
+ public Builder setTimestamp(Instant timestamp) {
+ this.timestamp = timestamp;
+ return this;
+ }
+
+ /**
+ * Sets the time the log entry was received by Cloud Logging, in milliseconds. If omitted, the
+ * Logging service will set the time at which the log entry is received.
+ *
+ * @deprecated This method is no longer recommended to setup the receive time timestamp.
+ *
Use {@link setReceiveTimestamp(Instant)} instead.
+ */
+ @CanIgnoreReturnValue
+ @Deprecated
+ public Builder setReceiveTimestamp(long milliseconds) {
+ this.receiveTimestamp = Instant.ofEpochMilli(milliseconds);
+ return this;
+ }
+
+ /**
+ * Sets the time the log entry was received by Cloud Logging. If omitted, the Logging service
+ * will set the time at which the log entry is received.
+ */
+ @CanIgnoreReturnValue
+ public Builder setReceiveTimestamp(Instant receiveTimestamp) {
+ this.receiveTimestamp = receiveTimestamp;
+ return this;
+ }
+
+ /** Sets the severity of the log entry. If not set, {@link Severity#DEFAULT} is used. */
+ @CanIgnoreReturnValue
+ public Builder setSeverity(Severity severity) {
+ this.severity = severity;
+ return this;
+ }
+
+ /**
+ * Sets a unique ID for the log entry. If you provide this field, the Logging service considers
+ * other log entries in the same log with the same ID as duplicates which can be removed. If
+ * omitted, the Logging service will generate a unique ID for this log entry.
+ */
+ @CanIgnoreReturnValue
+ public Builder setInsertId(String insertId) {
+ this.insertId = insertId;
+ return this;
+ }
+
+ /** Sets information about the HTTP request associated with this log entry, if applicable. */
+ @CanIgnoreReturnValue
+ public Builder setHttpRequest(HttpRequest httpRequest) {
+ this.httpRequest = httpRequest;
+ return this;
+ }
+
+ /**
+ * Sets an optional set of user-defined (key, value) data that provides additional information
+ * about the log entry.
+ */
+ @CanIgnoreReturnValue
+ public Builder setLabels(Map labels) {
+ this.labels = new HashMap<>(checkNotNull(labels));
+ return this;
+ }
+
+ /**
+ * Adds a label to the log entry's labels. Labels are user-defined (key, value) data that
+ * provides additional information about the log entry.
+ */
+ @CanIgnoreReturnValue
+ public Builder addLabel(String key, String value) {
+ this.labels.put(key, value);
+ return this;
+ }
+
+ /**
+ * Clears all the labels of the log entry. Labels are user-defined (key, value) data that
+ * provides additional information about the log entry.
+ */
+ @CanIgnoreReturnValue
+ public Builder clearLabels() {
+ this.labels.clear();
+ return this;
+ }
+
+ /** Sets information about an operation associated with the log entry, if applicable. */
+ @CanIgnoreReturnValue
+ public Builder setOperation(Operation operation) {
+ this.operation = operation;
+ return this;
+ }
+
+ /**
+ * Sets the resource name of the trace associated with the log entry, if any. If it contains a
+ * relative resource name, the name is assumed to be relative to `//tracing.googleapis.com`.
+ */
+ @CanIgnoreReturnValue
+ public Builder setTrace(String trace) {
+ this.trace = trace;
+ return this;
+ }
+
+ /**
+ * Sets the resource name of the trace associated with the log entry, if any. If it contains a
+ * relative resource name, the name is assumed to be relative to `//tracing.googleapis.com`.
+ */
+ @CanIgnoreReturnValue
+ public Builder setTrace(Object trace) {
+ this.trace = trace != null ? trace.toString() : null;
+ return this;
+ }
+
+ /** Sets the ID of the trace span associated with the log entry, if any. */
+ @CanIgnoreReturnValue
+ public Builder setSpanId(String spanId) {
+ this.spanId = spanId;
+ return this;
+ }
+
+ /** Sets the ID of the trace span associated with the log entry, if any. */
+ @CanIgnoreReturnValue
+ public Builder setSpanId(Object spanId) {
+ this.spanId = spanId != null ? spanId.toString() : null;
+ return this;
+ }
+
+ /** Sets the sampling decision of the trace span associated with the log entry. */
+ @CanIgnoreReturnValue
+ public Builder setTraceSampled(boolean traceSampled) {
+ this.traceSampled = traceSampled;
+ return this;
+ }
+
+ /** Sets the source code location information associated with the log entry if any. */
+ @CanIgnoreReturnValue
+ public Builder setSourceLocation(SourceLocation sourceLocation) {
+ this.sourceLocation = sourceLocation;
+ return this;
+ }
+
+ /**
+ * Sets the payload for this log entry. The log entry payload can be provided as an UTF-8 string
+ * (see {@link Payload.StringPayload}), a JSON object (see {@link Payload.JsonPayload}, or a
+ * protobuf object (see {@link Payload.ProtoPayload}).
+ *
+ * @see Log Entries and Logs
+ */
+ @CanIgnoreReturnValue
+ public Builder setPayload(Payload payload) {
+ this.payload = payload;
+ return this;
+ }
+
+ /** Sets the log path destination name type associated with the log entry. */
+ @CanIgnoreReturnValue
+ public Builder setDestination(LogDestinationName destination) {
+ this.destination = destination;
+ return this;
+ }
+
+ /** Creates a {@code LogEntry} object for this builder. */
+ public LogEntry build() {
+ return new LogEntry(this);
+ }
+ }
+
+ LogEntry(Builder builder) {
+ this.logName = builder.logName;
+ this.resource = builder.resource;
+ this.timestamp = builder.timestamp;
+ this.receiveTimestamp = builder.receiveTimestamp;
+ this.severity = builder.severity;
+ this.insertId = builder.insertId;
+ this.httpRequest = builder.httpRequest;
+ this.labels = ImmutableMap.copyOf(builder.labels);
+ this.operation = builder.operation;
+ this.trace = builder.trace;
+ this.spanId = builder.spanId;
+ this.traceSampled = builder.traceSampled;
+ this.sourceLocation = builder.sourceLocation;
+ this.payload = builder.payload;
+ this.destination = builder.destination;
+ }
+
+ /**
+ * Returns the name of the log to which this log entry belongs. The log name must be less than 512
+ * characters long and can only include the following characters: upper and lower case
+ * alphanumeric characters: {@code [A-Za-z0-9]}; and punctuation characters: {@code _-./}. The
+ * forward-slash ({@code /}) characters in the log name must be URL-encoded. Examples: {@code
+ * syslog}, {@code library.googleapis.com%2Fbook_log}.
+ */
+ public String getLogName() {
+ return logName;
+ }
+
+ /**
+ * Returns the monitored resource associated with this log entry. Example: a log entry that
+ * reports a database error would be associated with the monitored resource designating the
+ * particular database that reported the error.
+ */
+ public MonitoredResource getResource() {
+ return resource;
+ }
+
+ /**
+ * Returns the time at which the event described by the log entry occurred, in milliseconds.
+ *
+ * @deprecated This method is no longer recommended to get the entry timestamp.
+ * Use {@link getInstantTimestamp()} instead.
+ * @return timestamp in milliseconds
+ */
+ @Deprecated
+ public Long getTimestamp() {
+ return timestamp != null ? timestamp.toEpochMilli() : null;
+ }
+
+ /**
+ * Returns the time at which the event described by the log entry occurred.
+ *
+ * @return timestamp as {@link Instant}
+ */
+ public Instant getInstantTimestamp() {
+ return timestamp;
+ }
+
+ /**
+ * Returns the time the log entry was received by Cloud Logging, in milliseconds.
+ *
+ * @deprecated This method is no longer recommended to get the received time timestamp.
+ *
Use {@link getInstantReceiveTimestamp()} instead.
+ * @return timestamp in milliseconds
+ */
+ @Deprecated
+ public Long getReceiveTimestamp() {
+ return receiveTimestamp != null ? receiveTimestamp.toEpochMilli() : null;
+ }
+
+ /**
+ * Returns the time the log entry was received by Cloud Logging, in milliseconds.
+ *
+ * @return timestamp as {@link Instant}
+ */
+ public Instant getInstantReceiveTimestamp() {
+ return receiveTimestamp;
+ }
+
+ /** Returns the severity of the log entry. If not set, {@link Severity#DEFAULT} is used. */
+ public Severity getSeverity() {
+ return severity;
+ }
+
+ /**
+ * Returns a unique ID for the log entry. The Logging service considers other log entries in the
+ * same log with the same ID as duplicates which can be removed.
+ */
+ public String getInsertId() {
+ return insertId;
+ }
+
+ /** Returns information about the HTTP request associated with this log entry, if applicable. */
+ public HttpRequest getHttpRequest() {
+ return httpRequest;
+ }
+
+ /**
+ * Returns an optional set of user-defined (key, value) data that provides additional information
+ * about the log entry.
+ */
+ public Map getLabels() {
+ return labels;
+ }
+
+ /** Returns information about an operation associated with the log entry, if applicable. */
+ public Operation getOperation() {
+ return operation;
+ }
+
+ /**
+ * Returns the resource name of the trace associated with the log entry, if any. If it contains a
+ * relative resource name, the name is assumed to be relative to `//tracing.googleapis.com`.
+ */
+ public String getTrace() {
+ // For backwards compatibility return null when trace not set instead of "null".
+ return trace == null ? null : trace;
+ }
+
+ /** Returns the ID of the trace span associated with the log entry, if any. */
+ public String getSpanId() {
+ // For backwards compatibility return null when spanId not set instead of "null".
+ return spanId == null ? null : spanId;
+ }
+
+ /**
+ * Returns the sampling decision of the trace span associated with the log entry, or {@code false}
+ * if there is no trace span.
+ */
+ public boolean getTraceSampled() {
+ return traceSampled;
+ }
+
+ /** Returns the source code location information associated with the log entry, if any. */
+ public SourceLocation getSourceLocation() {
+ return sourceLocation;
+ }
+
+ /**
+ * Returns the payload for this log entry. The log entry payload can be an UTF-8 string (see
+ * {@link Payload.StringPayload}), a JSON object (see {@link Payload.JsonPayload}, or a protobuf
+ * object (see {@link Payload.ProtoPayload}).
+ *
+ * @see Log Entries and Logs
+ */
+ @SuppressWarnings("unchecked")
+ public > T getPayload() {
+ return (T) payload;
+ }
+
+ /**
+ * Returns the log path destination name type associated with log entry. By default, project name
+ * based destination is used.
+ *
+ * @see logName
+ */
+ public LogDestinationName getDestination() {
+ return destination;
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(
+ logName,
+ resource,
+ timestamp,
+ receiveTimestamp,
+ severity,
+ insertId,
+ httpRequest,
+ labels,
+ operation,
+ getTrace(),
+ getSpanId(),
+ traceSampled,
+ sourceLocation,
+ payload,
+ destination);
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+ if (!(obj instanceof LogEntry)) {
+ return false;
+ }
+ LogEntry other = (LogEntry) obj;
+ return Objects.equals(logName, other.logName)
+ && Objects.equals(resource, other.resource)
+ && Objects.equals(timestamp, other.timestamp)
+ && Objects.equals(receiveTimestamp, other.receiveTimestamp)
+ && Objects.equals(severity, other.severity)
+ && Objects.equals(insertId, other.insertId)
+ && Objects.equals(httpRequest, other.httpRequest)
+ && Objects.equals(labels, other.labels)
+ && Objects.equals(operation, other.operation)
+ && Objects.equals(getTrace(), other.getTrace())
+ && Objects.equals(getSpanId(), other.getSpanId())
+ && (traceSampled == other.traceSampled)
+ && Objects.equals(sourceLocation, other.sourceLocation)
+ && Objects.equals(payload, other.payload)
+ && Objects.equals(destination, other.destination);
+ }
+
+ @Override
+ public String toString() {
+ return MoreObjects.toStringHelper(this)
+ .add("logName", logName)
+ .add("resource", resource)
+ .add("timestamp", timestamp)
+ .add("receiveTimestamp", receiveTimestamp)
+ .add("severity", severity)
+ .add("insertId", insertId)
+ .add("httpRequest", httpRequest)
+ .add("labels", labels)
+ .add("operation", operation)
+ .add("trace", trace)
+ .add("spanId", spanId)
+ .add("traceSampled", traceSampled)
+ .add("sourceLocation", sourceLocation)
+ .add("payload", payload)
+ .add("destination", destination)
+ .toString();
+ }
+
+ /** Returns a {@code Builder} for this log entry. */
+ public Builder toBuilder() {
+ return new Builder(this);
+ }
+
+ com.google.logging.v2.LogEntry toPb(String projectId) {
+ com.google.logging.v2.LogEntry.Builder builder = payload.toPb();
+ builder.putAllLabels(labels);
+
+ if (logName != null) {
+ if (destination == null) {
+ builder.setLogName(LogName.ofProjectLogName(projectId, logName).toString());
+ } else {
+ builder.setLogName(destination.toLogName(logName).toString());
+ }
+ }
+ if (resource != null) {
+ builder.setResource(resource.toPb());
+ }
+ if (timestamp != null) {
+ builder.setTimestamp(JavaTimeConversions.toProtoTimestamp(timestamp));
+ }
+ if (receiveTimestamp != null) {
+ builder.setReceiveTimestamp(JavaTimeConversions.toProtoTimestamp(receiveTimestamp));
+ }
+ if (severity != null) {
+ builder.setSeverity(severity.toPb());
+ }
+ if (insertId != null) {
+ builder.setInsertId(insertId);
+ }
+ if (httpRequest != null) {
+ builder.setHttpRequest(httpRequest.toPb());
+ }
+ if (operation != null) {
+ builder.setOperation(operation.toPb());
+ }
+ if (trace != null) {
+ builder.setTrace(getTrace());
+ }
+ if (spanId != null) {
+ builder.setSpanId(getSpanId());
+ }
+ builder.setTraceSampled(traceSampled);
+ if (sourceLocation != null) {
+ builder.setSourceLocation(sourceLocation.toPb());
+ }
+ return builder.build();
+ }
+
+ /**
+ * Customized serializers to match the expected format for timestamp, source location and request
+ * method
+ */
+ static final class InstantSerializer implements JsonSerializer {
+ @Override
+ public JsonElement serialize(
+ Instant src, java.lang.reflect.Type typeOfSrc, JsonSerializationContext context) {
+ return new JsonPrimitive(src.toString());
+ }
+ }
+
+ static final class DurationSerializer implements JsonSerializer {
+ @Override
+ public JsonElement serialize(
+ Duration src, java.lang.reflect.Type typeOfSrc, JsonSerializationContext context) {
+ return new JsonPrimitive(src.toString());
+ }
+ }
+
+ static final class SourceLocationSerializer implements JsonSerializer {
+ @Override
+ public JsonElement serialize(
+ SourceLocation src, java.lang.reflect.Type typeOfSrc, JsonSerializationContext context) {
+ JsonObject obj = new JsonObject();
+ if (src.getFile() != null) {
+ obj.addProperty("file", src.getFile());
+ }
+ if (src.getLine() != null) {
+ obj.addProperty("line", src.getLine().toString());
+ }
+ if (src.getFunction() != null) {
+ obj.addProperty("function", src.getFunction());
+ }
+ return obj;
+ }
+ }
+
+ static final class RequestMethodSerializer implements JsonSerializer {
+ @Override
+ public JsonElement serialize(
+ HttpRequest.RequestMethod src,
+ java.lang.reflect.Type typeOfSrc,
+ JsonSerializationContext context) {
+ return new JsonPrimitive(src.name());
+ }
+ }
+
+ /** Helper class to format one line Json representation of the LogEntry for structured log. */
+ static final class StructuredLogFormatter {
+ private final Gson gson;
+ private final StringBuilder builder;
+
+ public StructuredLogFormatter(StringBuilder builder) {
+ checkNotNull(builder);
+ this.gson =
+ new GsonBuilder()
+ .registerTypeAdapter(Duration.class, new DurationSerializer())
+ .registerTypeAdapter(Instant.class, new InstantSerializer())
+ .registerTypeAdapter(SourceLocation.class, new SourceLocationSerializer())
+ .registerTypeAdapter(HttpRequest.RequestMethod.class, new RequestMethodSerializer())
+ .create();
+ this.builder = builder;
+ }
+
+ /**
+ * Adds a Json field and value pair to the current string representation. Method does not
+ * validate parameters to be multi-line strings. Nothing is added if {@code value} parameter is
+ * {@code null}.
+ *
+ * @param name a valid Json field name string.
+ * @param value an object to be serialized to Json using {@link Gson}.
+ * @param appendComma a flag to add a trailing comma.
+ * @return a reference to this object.
+ */
+ @CanIgnoreReturnValue
+ public StructuredLogFormatter appendField(String name, Object value, boolean appendComma) {
+ checkNotNull(name);
+ if (value != null) {
+ builder.append(gson.toJson(name)).append(":").append(gson.toJson(value));
+ if (appendComma) {
+ builder.append(",");
+ }
+ }
+ return this;
+ }
+
+ @CanIgnoreReturnValue
+ public StructuredLogFormatter appendField(String name, Object value) {
+ return appendField(name, value, true);
+ }
+
+ /**
+ * Serializes a dictionary of key, values as Json fields.
+ *
+ * @param value a {@link Map} of key, value arguments to be serialized using {@link Gson}.
+ * @param appendComma a flag to add a trailing comma.
+ * @return a reference to this object.
+ */
+ @CanIgnoreReturnValue
+ public StructuredLogFormatter appendDict(Map value, boolean appendComma) {
+ if (value != null) {
+ String json = gson.toJson(value);
+ // append json object without brackets
+ if (json.length() > 1) {
+ builder.append(json.substring(0, json.length() - 1).substring(1));
+ if (appendComma) {
+ builder.append(",");
+ }
+ }
+ }
+ return this;
+ }
+ }
+
+ /**
+ * Serializes the object to a one line JSON string in the simplified format that can be parsed by
+ * the logging agents that run on Google Cloud resources.
+ */
+ public String toStructuredJsonString() {
+ if (payload.getType() == Payload.Type.PROTO) {
+ throw new UnsupportedOperationException("LogEntry with protobuf payload cannot be converted");
+ }
+ if (severity == Severity.NONE) {
+ throw new IllegalArgumentException("Severity.NONE cannot be used for LogEntry");
+ }
+
+ final StringBuilder builder = new StringBuilder("{");
+ final StructuredLogFormatter formatter = new StructuredLogFormatter(builder);
+
+ formatter
+ .appendField("severity", severity)
+ .appendField("time", timestamp)
+ .appendField("httpRequest", httpRequest)
+ .appendField("logging.googleapis.com/insertId", insertId)
+ .appendField("logging.googleapis.com/labels", labels)
+ .appendField("logging.googleapis.com/operation", operation)
+ .appendField("logging.googleapis.com/sourceLocation", sourceLocation)
+ .appendField("logging.googleapis.com/spanId", spanId)
+ .appendField("logging.googleapis.com/trace", trace)
+ .appendField("logging.googleapis.com/trace_sampled", traceSampled);
+ if (payload.getType() == Payload.Type.STRING) {
+ formatter.appendField("message", payload.getData(), false);
+ } else if (payload.getType() == Payload.Type.JSON) {
+ Payload.JsonPayload jsonPayload = (Payload.JsonPayload) payload;
+ formatter.appendDict(jsonPayload.getDataAsMap(), false);
+ }
+ builder.append("}");
+ return builder.toString();
+ }
+
+ /** Returns a builder for {@code LogEntry} objects given the entry payload. */
+ public static Builder newBuilder(Payload payload) {
+ return new Builder(payload);
+ }
+
+ /** Creates a {@code LogEntry} object given the entry payload. */
+ public static LogEntry of(Payload payload) {
+ return newBuilder(payload).build();
+ }
+
+ /**
+ * Creates a {@code LogEntry} object given the log name, the monitored resource and the entry
+ * payload.
+ */
+ public static LogEntry of(String logName, MonitoredResource resource, Payload payload) {
+ return newBuilder(payload).setLogName(logName).setResource(resource).build();
+ }
+
+ public static LogEntry fromPb(com.google.logging.v2.LogEntry entryPb) {
+ Builder builder = newBuilder(Payload.fromPb(entryPb));
+ builder.setLabels(entryPb.getLabelsMap());
+ builder.setSeverity(Severity.fromPb(entryPb.getSeverity()));
+ if (!entryPb.getLogName().isEmpty()) {
+ LogName name = LogName.parse(entryPb.getLogName());
+ builder.setLogName(name.getLog());
+ LogDestinationName resource = LogDestinationName.fromLogName(name);
+ if (resource != null) {
+ builder.setDestination(resource);
+ }
+ }
+ if (!entryPb.getResource().equals(com.google.api.MonitoredResource.getDefaultInstance())) {
+ builder.setResource(MonitoredResource.fromPb(entryPb.getResource()));
+ }
+ if (entryPb.hasTimestamp()) {
+ builder.setTimestamp(JavaTimeConversions.toJavaInstant(entryPb.getTimestamp()));
+ }
+ if (entryPb.hasReceiveTimestamp()) {
+ builder.setReceiveTimestamp(JavaTimeConversions.toJavaInstant(entryPb.getReceiveTimestamp()));
+ }
+ if (!entryPb.getInsertId().isEmpty()) {
+ builder.setInsertId(entryPb.getInsertId());
+ }
+ if (!entryPb
+ .getHttpRequest()
+ .equals(com.google.logging.type.HttpRequest.getDefaultInstance())) {
+ builder.setHttpRequest(HttpRequest.fromPb(entryPb.getHttpRequest()));
+ }
+ if (!entryPb.getOperation().equals(LogEntryOperation.getDefaultInstance())) {
+ builder.setOperation(Operation.fromPb(entryPb.getOperation()));
+ }
+ if (!entryPb.getTrace().isEmpty()) {
+ builder.setTrace(entryPb.getTrace());
+ }
+ if (!entryPb.getSpanId().isEmpty()) {
+ builder.setSpanId(entryPb.getSpanId());
+ }
+ builder.setTraceSampled(entryPb.getTraceSampled());
+ if (!entryPb.getSourceLocation().equals(LogEntrySourceLocation.getDefaultInstance())) {
+ builder.setSourceLocation(SourceLocation.fromPb(entryPb.getSourceLocation()));
+ }
+ return builder.build();
+ }
+
+ public static Function toPbFunction(
+ final String projectId) {
+ return (LogEntry entry) -> {
+ return entry.toPb(projectId);
+ };
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryIterator.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryIterator.java
new file mode 100644
index 000000000000..3faaeebbb40b
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryIterator.java
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.common.collect.Lists;
+import com.google.logging.v2.TailLogEntriesResponse;
+import java.util.ArrayDeque;
+import java.util.Iterator;
+
+/**
+ * The class implements {@see Iterator} interface over {@see LogEntry} by iterating through {@see
+ * TailLogEntriesResponse} streamed by {@code BidiStream}. This class is instantiated by {@see
+ * LogEntryServerStream} and is not intended to be used explicitly.
+ */
+public class LogEntryIterator implements Iterator {
+ // TODO: consider converting this to use generics instead of
+ // fixed TailLogEntriesResponse
+ private final Iterator streamIterator;
+ private final ArrayDeque buffer = new ArrayDeque<>();
+
+ LogEntryIterator(Iterator streamIterator) {
+ this.streamIterator = streamIterator;
+ }
+
+ /** {@inheritDoc} */
+ @Override
+ public boolean hasNext() {
+ return !buffer.isEmpty() || streamIterator.hasNext();
+ }
+
+ /** {@inheritDoc} */
+ @Override
+ public LogEntry next() {
+ if (buffer.isEmpty()) {
+ TailLogEntriesResponse response = streamIterator.next();
+ buffer.addAll(Lists.transform(response.getEntriesList(), LogEntry.FROM_PB_FUNCTION));
+ }
+ return buffer.pop();
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryServerStream.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryServerStream.java
new file mode 100644
index 000000000000..41969c7441b2
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryServerStream.java
@@ -0,0 +1,85 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.api.gax.rpc.BidiStream;
+import com.google.common.collect.Lists;
+import com.google.logging.v2.TailLogEntriesRequest;
+import com.google.logging.v2.TailLogEntriesResponse;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * The class implements {@link Iterable} interface over {@see LogEntry}. It wraps around {@link
+ * BidiStream} bi-directional gRPC stream to support iterating through ingested responses. The class
+ * uses {@see LogEntryIterator} to iterate through the processed responses. The stream should be
+ * explicitly canceled by calling {@see LogEntryServerStream#cancel()} method. The class does not
+ * provide recovery or resuming functionality over the stream.
+ *
+ * To iterate run:
+ *
+ *
{@code
+ * LogEntryServerStream stream;
+ * // code to initialize stream
+ * for (LogEntry log : stream) {
+ * // do something with logs
+ * }
+ * stream.cancel();
+ * }
+ *
+ * The iteration can be blocked on waiting for another response sent in the stream.
+ */
+public class LogEntryServerStream implements Iterable {
+ private final BidiStream serverStream;
+
+ LogEntryServerStream(BidiStream serverStream) {
+ this.serverStream = serverStream;
+ }
+
+ /** {@inheritDoc} */
+ @Override
+ public Iterator iterator() {
+ return new LogEntryIterator(serverStream.iterator());
+ }
+
+ public BidiStream getInternalStream() {
+ return serverStream;
+ }
+
+ public List convert(TailLogEntriesResponse resp) {
+ return Lists.transform(resp.getEntriesList(), LogEntry.FROM_PB_FUNCTION);
+ }
+
+ /**
+ * Returns true if the next call to the iterator's hasNext() or next() is guaranteed to be
+ * nonblocking.
+ *
+ * @return If the call on any of the iterator's methods is guaranteed to be nonblocking.
+ */
+ public boolean isReceiveReady() {
+ return serverStream.isReceiveReady();
+ }
+
+ /**
+ * Cleanly cancels a partially consumed stream. The associated iterator will return false for the
+ * hasNext() in the next iteration. This maintains the contract that an observed true from
+ * hasNext() will yield an item in next(), but afterwards will return false.
+ */
+ public void cancel() {
+ serverStream.cancel();
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/Logging.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/Logging.java
new file mode 100644
index 000000000000..3c4cc3078556
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/Logging.java
@@ -0,0 +1,1208 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.api.core.ApiFuture;
+import com.google.api.core.BetaApi;
+import com.google.api.gax.paging.AsyncPage;
+import com.google.api.gax.paging.Page;
+import com.google.cloud.MonitoredResource;
+import com.google.cloud.MonitoredResourceDescriptor;
+import com.google.cloud.Service;
+import com.google.common.base.Ascii;
+import com.google.common.collect.ImmutableMap;
+import java.util.Map;
+
+public interface Logging extends AutoCloseable, Service {
+
+ /**
+ * Class for specifying options for listing sinks, monitored resources and monitored resource
+ * descriptors.
+ */
+ final class ListOption extends Option {
+
+ private static final long serialVersionUID = -6857294816115909271L;
+
+ enum OptionType implements Option.OptionType {
+ PAGE_SIZE,
+ PAGE_TOKEN;
+
+ @SuppressWarnings("unchecked")
+ T get(Map options) {
+ return (T) options.get(this);
+ }
+ }
+
+ private ListOption(ListOption.OptionType option, Object value) {
+ super(option, value);
+ }
+
+ /** Returns an option to specify the maximum number of resources returned per page. */
+ public static ListOption pageSize(int pageSize) {
+ return new ListOption(ListOption.OptionType.PAGE_SIZE, pageSize);
+ }
+
+ /** Returns an option to specify the page token from which to start listing resources. */
+ public static ListOption pageToken(String pageToken) {
+ return new ListOption(ListOption.OptionType.PAGE_TOKEN, pageToken);
+ }
+ }
+
+ /** Class for specifying options for writing log entries. */
+ final class WriteOption extends Option {
+
+ private static final long serialVersionUID = 715900132268584612L;
+
+ enum OptionType implements Option.OptionType {
+ LOG_NAME,
+ RESOURCE,
+ LABELS,
+ LOG_DESTINATION,
+ AUTO_POPULATE_METADATA,
+ PARTIAL_SUCCESS;
+
+ @SuppressWarnings("unchecked")
+ T get(Map options) {
+ return (T) options.get(this);
+ }
+ }
+
+ private WriteOption(WriteOption.OptionType option, Object value) {
+ super(option, value);
+ }
+
+ /**
+ * Returns an option to specify a default log name (see {@link LogEntry#getLogName()}) for those
+ * log entries that do not specify their own log name. Example: {@code syslog}.
+ */
+ public static WriteOption logName(String logName) {
+ return new WriteOption(WriteOption.OptionType.LOG_NAME, logName);
+ }
+
+ /**
+ * Returns an option to specify a default monitored resource (see {@link
+ * LogEntry#getResource()}) for those log entries that do not specify their own resource.
+ */
+ public static WriteOption resource(MonitoredResource resource) {
+ return new WriteOption(WriteOption.OptionType.RESOURCE, resource);
+ }
+
+ /**
+ * Sets an option to specify (key, value) pairs that are added to the {@link
+ * LogEntry#getLabels()} of each log entry written, except when a log entry already has a value
+ * associated to the same key.
+ */
+ public static WriteOption labels(Map labels) {
+ return new WriteOption(WriteOption.OptionType.LABELS, ImmutableMap.copyOf(labels));
+ }
+
+ /**
+ * Returns an option to specify a log destination resource path (see {@link LogDestinationName}
+ * for details)
+ */
+ public static WriteOption destination(LogDestinationName destination) {
+ return new WriteOption(WriteOption.OptionType.LOG_DESTINATION, destination);
+ }
+
+ /**
+ * Returns an option to opt-out automatic population of log entries metadata fields that are not
+ * set.
+ */
+ public static WriteOption autoPopulateMetadata(boolean autoPopulateMetadata) {
+ return new WriteOption(WriteOption.OptionType.AUTO_POPULATE_METADATA, autoPopulateMetadata);
+ }
+
+ /**
+ * Returns an option to set partialSuccess flag. See the
+ * API documentation for more details.
+ */
+ public static WriteOption partialSuccess(boolean partialSuccess) {
+ return new WriteOption(WriteOption.OptionType.PARTIAL_SUCCESS, partialSuccess);
+ }
+ }
+
+ /** Fields according to which log entries can be sorted. */
+ enum SortingField {
+ TIMESTAMP;
+
+ String selector() {
+ return Ascii.toLowerCase(name());
+ }
+ }
+
+ /** Sorting orders available when listing log entries. */
+ enum SortingOrder {
+ DESCENDING("desc"),
+ ASCENDING("asc");
+
+ private final String selector;
+
+ SortingOrder(String selector) {
+ this.selector = selector;
+ }
+
+ String selector() {
+ return selector;
+ }
+ }
+
+ /** Class for specifying options for listing log entries. */
+ final class EntryListOption extends Option {
+
+ private static final long serialVersionUID = -1561159676386917050L;
+
+ enum OptionType implements Option.OptionType {
+ ORDER_BY,
+ FILTER,
+ ORGANIZATION,
+ BILLINGACCOUNT,
+ FOLDER;
+
+ @SuppressWarnings("unchecked")
+ T get(Map options) {
+ return (T) options.get(this);
+ }
+ }
+
+ private EntryListOption(Option.OptionType option, Object value) {
+ super(option, value);
+ }
+
+ /** Returns an option to specify the maximum number of log entries returned per page. */
+ public static EntryListOption pageSize(int pageSize) {
+ return new EntryListOption(ListOption.OptionType.PAGE_SIZE, pageSize);
+ }
+
+ /** Returns an option to specify the page token from which to start listing log entries. */
+ public static EntryListOption pageToken(String pageToken) {
+ return new EntryListOption(ListOption.OptionType.PAGE_TOKEN, pageToken);
+ }
+
+ /**
+ * Returns an option to sort log entries. If not specified, log entries are sorted in ascending
+ * (most-recent last) order with respect to the {@link LogEntry#getTimestamp()} value.
+ */
+ public static EntryListOption sortOrder(SortingField field, SortingOrder order) {
+ return new EntryListOption(
+ EntryListOption.OptionType.ORDER_BY, field.selector() + ' ' + order.selector());
+ }
+
+ /**
+ * Returns an option to specify a filter to the log entries to be listed.
+ *
+ * @see Advanced Logs
+ * Filters
+ */
+ public static EntryListOption filter(String filter) {
+ return new EntryListOption(EntryListOption.OptionType.FILTER, filter);
+ }
+
+ /** Returns an option to specify an organization for the log entries to be listed. */
+ public static EntryListOption organization(String organization) {
+ return new EntryListOption(EntryListOption.OptionType.ORGANIZATION, organization);
+ }
+
+ /** Returns an option to specify a billingAccount for the log entries to be listed. */
+ public static EntryListOption billingAccount(String billingAccount) {
+ return new EntryListOption(EntryListOption.OptionType.BILLINGACCOUNT, billingAccount);
+ }
+
+ /** Returns an option to specify a folder for the log entries to be listed. */
+ public static EntryListOption folder(String folder) {
+ return new EntryListOption(EntryListOption.OptionType.FOLDER, folder);
+ }
+ }
+
+ /** Class for specifying options for tailing log entries. */
+ final class TailOption extends Option {
+
+ private static final long serialVersionUID = -772271612198662617L;
+
+ enum OptionType implements Option.OptionType {
+ FILTER,
+ BUFFERWINDOW,
+ PROJECT,
+ ORGANIZATION,
+ BILLINGACCOUNT,
+ FOLDER;
+
+ @SuppressWarnings("unchecked")
+ T get(Map options) {
+ return (T) options.get(this);
+ }
+ }
+
+ private TailOption(Option.OptionType option, Object value) {
+ super(option, value);
+ }
+
+ /**
+ * Returns an option to specify a filter to the log entries to be tailed.
+ *
+ * @see Advanced Logs
+ * Filters
+ */
+ public static TailOption filter(String filter) {
+ return new TailOption(TailOption.OptionType.FILTER, filter);
+ }
+
+ /**
+ * Returns an option to specify the amount of time to buffer log entries at the server before
+ * being returned to prevent out of order results due to late arriving log entries. Valid values
+ * are between 0-60000 ms. Default is 2000 ms.
+ *
+ * @see Duration
+ * format
+ */
+ public static TailOption bufferWindow(String duration) {
+ return new TailOption(TailOption.OptionType.BUFFERWINDOW, duration);
+ }
+
+ /** Returns an option to specify an organization for the log entries to be tailed. */
+ public static TailOption organization(String organization) {
+ return new TailOption(TailOption.OptionType.ORGANIZATION, organization);
+ }
+
+ /** Returns an option to specify a billingAccount for the log entries to be tailed. */
+ public static TailOption billingAccount(String billingAccount) {
+ return new TailOption(TailOption.OptionType.BILLINGACCOUNT, billingAccount);
+ }
+
+ /** Returns an option to specify a folder for the log entries to be tailed. */
+ public static TailOption folder(String folder) {
+ return new TailOption(TailOption.OptionType.FOLDER, folder);
+ }
+
+ /** Returns an option to specify a project for the log entries to be tailed. */
+ public static TailOption project(String project) {
+ return new TailOption(TailOption.OptionType.PROJECT, project);
+ }
+ }
+
+ /** Sets synchronicity {@link Synchronicity} of logging writes, defaults to asynchronous. */
+ void setWriteSynchronicity(Synchronicity synchronicity);
+
+ /** Retrieves current set synchronicity {@link Synchronicity} of logging writes. */
+ Synchronicity getWriteSynchronicity();
+
+ /**
+ * Sets flush severity for asynchronous logging writes. It is disabled by default, enabled when
+ * this method is called with any {@link Severity} value other than {@link Severity#NONE}. Logs
+ * will be immediately written out for entries at or higher than flush severity.
+ *
+ * Enabling this can cause the leaking and hanging threads, see BUG(2796) BUG(3880). However
+ * you can explicitly call {@link #flush}.
+ *
+ *
TODO: Enable this by default once functionality to trigger rpc is available in generated
+ * code.
+ */
+ void setFlushSeverity(Severity flushSeverity);
+
+ /* Retrieves flush severity for asynchronous logging writes. */
+ Severity getFlushSeverity();
+
+ /**
+ * Creates a new sink.
+ *
+ *
Example of creating a sink to export logs to a BigQuery dataset (in the {@link
+ * LoggingOptions#getProjectId()} project).
+ *
+ *
+ * {
+ * @code
+ * String sinkName = "my_sink_name";
+ * String datasetName = "my_dataset";
+ * SinkInfo sinkInfo = SinkInfo.of(sinkName, DatasetDestination.of(datasetName));
+ * Sink sink = logging.create(sinkInfo);
+ * }
+ *
+ *
+ * @return the created sink
+ * @throws LoggingException upon failure
+ */
+ Sink create(SinkInfo sink);
+
+ /**
+ * Creates a new metric.
+ *
+ * Example of creating a metric for logs with severity higher or equal to ERROR.
+ *
+ *
+ * {
+ * @code
+ * String metricName = "my_metric_name";
+ * MetricInfo metricInfo = MetricInfo.of(metricName, "severity>=ERROR");
+ * Metric metric = logging.create(metricInfo);
+ * }
+ *
+ *
+ * @return the created metric
+ * @throws LoggingException upon failure
+ */
+ Metric create(MetricInfo metric);
+
+ /**
+ * Creates a new exclusion in a specified parent resource. Only log entries belonging to that
+ * resource can be excluded. You can have up to 10 exclusions in a resource.
+ *
+ * Example of creating the exclusion:
+ *
+ *
+ * {
+ * @code
+ * String exclusionName = "my_exclusion_name";
+ * Exclusion exclusion = Exclusion.of(exclusionName,
+ * "resource.type=gcs_bucket severity<ERROR sample(insertId, 0.99)");
+ * Exclusion exclusion = logging.create(exclusion);
+ * }
+ *
+ *
+ * @return the created exclusion
+ * @throws LoggingException upon failure
+ */
+ Exclusion create(Exclusion exclusion);
+
+ /**
+ * Sends a request for creating a sink. This method returns a {@code ApiFuture} object to consume
+ * the result. {@link ApiFuture#get()} returns the created sink.
+ *
+ * Example of asynchronously creating a sink to export logs to a BigQuery dataset (in the
+ * {@link LoggingOptions#getProjectId()} project).
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * String datasetName = "my_dataset";
+ * SinkInfo sinkInfo = SinkInfo.of(sinkName, DatasetDestination.of(datasetName));
+ * ApiFuture future = logging.createAsync(sinkInfo);
+ * // ...
+ * Sink sink = future.get();
+ * }
+ */
+ ApiFuture createAsync(SinkInfo sink);
+
+ /**
+ * Sends a request for creating a metric. This method returns a {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns the created metric.
+ *
+ * Example of asynchronously creating a metric for logs with severity higher or equal to ERROR.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * MetricInfo metricInfo = MetricInfo.of(metricName, "severity>=ERROR");
+ * ApiFuture future = logging.createAsync(metricInfo);
+ * // ...
+ * Metric metric = future.get();
+ * }
+ */
+ ApiFuture createAsync(MetricInfo metric);
+
+ /**
+ * Sends a request to create the exclusion. This method returns an {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns the created exclusion.
+ *
+ * Example of asynchronously creating the exclusion:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * Exclusion exclusion = Exclusion.of(exclusionName,
+ * "resource.type=gcs_bucket severity future = logging.createAsync(exclusion);
+ * // ...
+ * Exclusion exclusion = future.get();
+ * }
+ */
+ ApiFuture createAsync(Exclusion exclusion);
+
+ /**
+ * Updates a sink or creates one if it does not exist.
+ *
+ * Example of updating a sink.
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * String datasetName = "my_dataset";
+ * SinkInfo sinkInfo = SinkInfo.newBuilder(sinkName, DatasetDestination.of(datasetName))
+ * .setVersionFormat(SinkInfo.VersionFormat.V2).setFilter("severity>=ERROR").build();
+ * Sink sink = logging.update(sinkInfo);
+ * }
+ *
+ * @return the created sink
+ * @throws LoggingException upon failure
+ */
+ Sink update(SinkInfo sink);
+
+ /**
+ * Updates a metric or creates one if it does not exist.
+ *
+ * Example of updating a metric.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * MetricInfo metricInfo = MetricInfo.newBuilder(metricName, "severity>=ERROR").setDescription("new description")
+ * .build();
+ * Metric metric = logging.update(metricInfo);
+ * }
+ *
+ * @return the created metric
+ * @throws LoggingException upon failure
+ */
+ Metric update(MetricInfo metric);
+
+ /**
+ * Updates one or more properties of an existing exclusion.
+ *
+ * Example of updating the exclusion:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * Exclusion exclusion = Exclusion
+ * .newBuilder(exclusionName, "resource.type=gcs_bucket severity
+ *
+ * @return the updated exclusion
+ * @throws LoggingException upon failure
+ */
+ Exclusion update(Exclusion exclusion);
+
+ /**
+ * Sends a request for updating a sink (or creating it, if it does not exist). This method returns
+ * a {@code ApiFuture} object to consume the result. {@link ApiFuture#get()} returns the
+ * updated/created sink or {@code null} if not found.
+ *
+ * Example of asynchronously updating a sink.
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * String datasetName = "my_dataset";
+ * SinkInfo sinkInfo = SinkInfo.newBuilder(sinkName, DatasetDestination.of(datasetName))
+ * .setVersionFormat(SinkInfo.VersionFormat.V2).setFilter("severity>=ERROR").build();
+ * ApiFuture future = logging.updateAsync(sinkInfo);
+ * // ...
+ * Sink sink = future.get();
+ * }
+ */
+ ApiFuture updateAsync(SinkInfo sink);
+
+ /**
+ * Sends a request for updating a metric (or creating it, if it does not exist). This method
+ * returns a {@code ApiFuture} object to consume the result. {@link ApiFuture#get()} returns the
+ * updated/created metric or {@code null} if not found.
+ *
+ * Example of asynchronously updating a metric.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * MetricInfo metricInfo = MetricInfo.newBuilder(metricName, "severity>=ERROR").setDescription("new description")
+ * .build();
+ * ApiFuture future = logging.updateAsync(metricInfo);
+ * // ...
+ * Metric metric = future.get();
+ * }
+ */
+ ApiFuture updateAsync(MetricInfo metric);
+
+ /**
+ * Sends a request to change one or more properties of an existing exclusion. This method returns
+ * an {@code ApiFuture} object to consume the result. {@link ApiFuture#get()} returns the updated
+ * exclusion or {@code null} if not found.
+ *
+ * Example of asynchronous exclusion update:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * Exclusion exclusion = Exclusion
+ * .newBuilder(exclusionName, "resource.type=gcs_bucket severity future = logging.updateAsync(exclusion);
+ * // ...
+ * Exclusion exclusion = future.get();
+ * }
+ */
+ ApiFuture updateAsync(Exclusion exclusion);
+
+ /**
+ * Returns the requested sink or {@code null} if not found.
+ *
+ * Example of getting a sink.
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * Sink sink = logging.getSink(sinkName);
+ * if (sink == null) {
+ * // sink was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Sink getSink(String sink);
+
+ /**
+ * Sends a request for getting a sink. This method returns a {@code ApiFuture} object to consume
+ * the result. {@link ApiFuture#get()} returns the requested sink or {@code null} if not found.
+ *
+ * Example of asynchronously getting a sink.
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * ApiFuture future = logging.getSinkAsync(sinkName);
+ * // ...
+ * Sink sink = future.get();
+ * if (sink == null) {
+ * // sink was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ ApiFuture getSinkAsync(String sink);
+
+ /**
+ * Lists the sinks. This method returns a {@link Page} object that can be used to consume
+ * paginated results. Use {@link ListOption} to specify the page size or the page token from which
+ * to start listing sinks.
+ *
+ * Example of listing sinks, specifying the page size.
+ *
+ *
{@code
+ * Page sinks = logging.listSinks(ListOption.pageSize(100));
+ * Iterator sinkIterator = sinks.iterateAll().iterator();
+ * while (sinkIterator.hasNext()) {
+ * Sink sink = sinkIterator.next();
+ * // do something with the sink
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Page listSinks(ListOption... options);
+
+ /**
+ * Sends a request for listing sinks. This method returns a {@code ApiFuture} object to consume
+ * the result. {@link ApiFuture#get()} returns an {@link AsyncPage} object that can be used to
+ * asynchronously handle paginated results. Use {@link ListOption} to specify the page size or the
+ * page token from which to start listing sinks.
+ *
+ * Example of asynchronously listing sinks, specifying the page size.
+ *
+ *
{@code
+ * ApiFuture> future = logging.listSinksAsync(ListOption.pageSize(100));
+ * // ...
+ * AsyncPage sinks = future.get();
+ * Iterator sinkIterator = sinks.iterateAll().iterator();
+ * while (sinkIterator.hasNext()) {
+ * Sink sink = sinkIterator.next();
+ * // do something with the sink
+ * }
+ * }
+ */
+ ApiFuture> listSinksAsync(ListOption... options);
+
+ /**
+ * Deletes the requested sink.
+ *
+ * Example of deleting a sink.
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * boolean deleted = logging.deleteSink(sinkName);
+ * if (deleted) {
+ * // the sink was deleted
+ * } else {
+ * // the sink was not found
+ * }
+ * }
+ *
+ * @return {@code true} if the sink was deleted, {@code false} if it was not found
+ */
+ boolean deleteSink(String sink);
+
+ /**
+ * Sends a request for deleting a sink. This method returns a {@code ApiFuture} object to consume
+ * the result. {@link ApiFuture#get()} returns {@code true} if the sink was deleted, {@code false}
+ * if it was not found.
+ *
+ * Example of asynchronously deleting a sink.
+ *
+ *
{@code
+ * String sinkName = "my_sink_name";
+ * ApiFuture future = logging.deleteSinkAsync(sinkName);
+ * // ...
+ * boolean deleted = future.get();
+ * if (deleted) {
+ * // the sink was deleted
+ * } else {
+ * // the sink was not found
+ * }
+ * }
+ */
+ ApiFuture deleteSinkAsync(String sink);
+
+ /**
+ * Lists the log names. This method returns a {@link Page} object that can be used to consume
+ * paginated results. Use {@link ListOption} to specify the page size or the page token from which
+ * to start listing logs.
+ *
+ * Example of listing log names, specifying the page size.
+ *
+ *
{@code
+ * Page logNames = logging.listLogs(ListOption.pageSize(100));
+ * Iterator logIterator = logNames.iterateAll().iterator();
+ * while (logIterator.hasNext()) {
+ * String logName = logIterator.next();
+ * // do something with the log name
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ default Page listLogs(ListOption... options) {
+ throw new UnsupportedOperationException(
+ "method listLogs() does not have default implementation");
+ }
+
+ /**
+ * Sends a request for listing log names. This method returns a {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns an {@link AsyncPage} object that can be
+ * used to asynchronously handle paginated results. Use {@link ListOption} to specify the page
+ * size or the page token from which to start listing log names.
+ *
+ * Example of asynchronously listing log names, specifying the page size.
+ *
+ *
{@code
+ * ApiFuture> future = logging.listLogsAsync(ListOption.pageSize(100));
+ * // ...
+ * AsyncPage logNames = future.get();
+ * Iterator logIterator = logNames.iterateAll().iterator();
+ * while (logIterator.hasNext()) {
+ * String logName = logIterator.next();
+ * // do something with the log name
+ * }
+ * }
+ */
+ default ApiFuture> listLogsAsync(ListOption... options) {
+ throw new UnsupportedOperationException(
+ "method listLogsAsync() does not have default implementation");
+ }
+
+ /**
+ * Deletes a log and all its log entries. The log will reappear if new entries are written to it.
+ *
+ * Example of deleting a log.
+ *
+ *
{@code
+ * String logName = "my_log_name";
+ * boolean deleted = logging.deleteLog(logName);
+ * if (deleted) {
+ * // the log was deleted
+ * } else {
+ * // the log was not found
+ * }
+ * }
+ *
+ * @return {@code true} if the log was deleted, {@code false} if it was not found
+ */
+ boolean deleteLog(String log);
+
+ /**
+ * Deletes a log and all its log entries for given log destination (see 'logName' parameter in
+ * https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry). The log will reappear if
+ * new entries are written to it.
+ *
+ * Example of deleting a log by folder destination.
+ *
+ *
{@code
+ * String logName = "my_log_name";
+ * String folder = "my_folder";
+ * boolean deleted = logging.deleteLog(logName, LogDestinationName.folder(folder));
+ * if (deleted) {
+ * // the log was deleted
+ * } else {
+ * // the log was not found
+ * }
+ * }
+ *
+ * @return {@code true} if the log was deleted, {@code false} if it was not found
+ */
+ default boolean deleteLog(String log, LogDestinationName destination) {
+ throw new UnsupportedOperationException(
+ "method deleteLog() does not have default implementation");
+ }
+
+ /**
+ * Sends a request for deleting a log and all its log entries for given log destination (see
+ * 'logName' parameter in https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry).
+ * This method returns a {@code ApiFuture} object to consume the result. {@link ApiFuture#get()}
+ * returns {@code true} if the log was deleted, {@code false} if it was not found.
+ *
+ * Example of asynchronously deleting a log by folder destination.
+ *
+ *
{@code
+ * String logName = "my_log_name";
+ * String folder = "my_folder";
+ * ApiFuture future = logging.deleteLogAsync(logName, LogDestinationName.folder(folder));
+ * // ...
+ * boolean deleted = future.get();
+ * if (deleted) {
+ * // the log was deleted
+ * } else {
+ * // the log was not found
+ * }
+ * }
+ */
+ default ApiFuture deleteLogAsync(String log, LogDestinationName destination) {
+ throw new UnsupportedOperationException(
+ "method deleteLogAsync() does not have default implementation");
+ }
+
+ /**
+ * Sends a request for deleting a log and all its log entries. This method returns a {@code
+ * ApiFuture} object to consume the result. {@link ApiFuture#get()} returns {@code true} if the
+ * log was deleted, {@code false} if it was not found.
+ *
+ * Example of asynchronously deleting a log.
+ *
+ *
{@code
+ * String logName = "my_log_name";
+ * ApiFuture future = logging.deleteLogAsync(logName);
+ * // ...
+ * boolean deleted = future.get();
+ * if (deleted) {
+ * // the log was deleted
+ * } else {
+ * // the log was not found
+ * }
+ * }
+ */
+ ApiFuture deleteLogAsync(String log);
+
+ /**
+ * Lists the monitored resource descriptors used by Cloud Logging. This method returns a {@link
+ * Page} object that can be used to consume paginated results. Use {@link ListOption} to specify
+ * the page size or the page token from which to start listing resource descriptors.
+ *
+ * Example of listing monitored resource descriptors, specifying the page size.
+ *
+ *
{@code
+ * Page descriptors = logging
+ * .listMonitoredResourceDescriptors(ListOption.pageSize(100));
+ * Iterator descriptorIterator = descriptors.iterateAll().iterator();
+ * while (descriptorIterator.hasNext()) {
+ * MonitoredResourceDescriptor descriptor = descriptorIterator.next();
+ * // do something with the descriptor
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Page listMonitoredResourceDescriptors(ListOption... options);
+
+ /**
+ * Sends a request for listing monitored resource descriptors used by Cloud Logging. This method
+ * returns a {@code ApiFuture} object to consume the result. {@link ApiFuture#get()} returns an
+ * {@link AsyncPage} object that can be used to asynchronously handle paginated results. Use
+ * {@link ListOption} to specify the page size or the page token from which to start listing
+ * resource descriptors.
+ *
+ * Example of asynchronously listing monitored resource descriptors, specifying the page size.
+ *
+ *
{@code
+ * ApiFuture> future = logging
+ * .listMonitoredResourceDescriptorsAsync(ListOption.pageSize(100));
+ * // ...
+ * AsyncPage descriptors = future.get();
+ * Iterator descriptorIterator = descriptors.iterateAll().iterator();
+ * while (descriptorIterator.hasNext()) {
+ * MonitoredResourceDescriptor descriptor = descriptorIterator.next();
+ * // do something with the descriptor
+ * }
+ * }
+ */
+ ApiFuture> listMonitoredResourceDescriptorsAsync(
+ ListOption... options);
+
+ /**
+ * Returns the requested metric or {@code null} if not found.
+ *
+ * Example of getting a metric.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * Metric metric = logging.getMetric(metricName);
+ * if (metric == null) {
+ * // metric was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Metric getMetric(String metric);
+
+ /**
+ * Sends a request for getting a metric. This method returns a {@code ApiFuture} object to consume
+ * the result. {@link ApiFuture#get()} returns the requested metric or {@code null} if not found.
+ *
+ * Example of asynchronously getting a metric.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * ApiFuture future = logging.getMetricAsync(metricName);
+ * // ...
+ * Metric metric = future.get();
+ * if (metric == null) {
+ * // metric was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ ApiFuture getMetricAsync(String metric);
+
+ /**
+ * Lists the metrics. This method returns a {@link Page} object that can be used to consume
+ * paginated results. Use {@link ListOption} to specify the page size or the page token from which
+ * to start listing metrics.
+ *
+ * Example of listing metrics, specifying the page size.
+ *
+ *
{@code
+ * Page metrics = logging.listMetrics(ListOption.pageSize(100));
+ * Iterator metricIterator = metrics.iterateAll().iterator();
+ * while (metricIterator.hasNext()) {
+ * Metric metric = metricIterator.next();
+ * // do something with the metric
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Page listMetrics(ListOption... options);
+
+ /**
+ * Sends a request for listing metrics. This method returns a {@code ApiFuture} object to consume
+ * the result. {@link ApiFuture#get()} returns an {@link AsyncPage} object that can be used to
+ * asynchronously handle paginated results. Use {@link ListOption} to specify the page size or the
+ * page token from which to start listing metrics.
+ *
+ * Example of asynchronously listing metrics, specifying the page size.
+ *
+ *
{@code
+ * ApiFuture> future = logging.listMetricsAsync(ListOption.pageSize(100));
+ * // ...
+ * AsyncPage metrics = future.get();
+ * Iterator metricIterator = metrics.iterateAll().iterator();
+ * while (metricIterator.hasNext()) {
+ * Metric metric = metricIterator.next();
+ * // do something with the metric
+ * }
+ * }
+ */
+ ApiFuture> listMetricsAsync(ListOption... options);
+
+ /**
+ * Deletes the requested metric.
+ *
+ * Example of deleting a metric.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * boolean deleted = logging.deleteMetric(metricName);
+ * if (deleted) {
+ * // the metric was deleted
+ * } else {
+ * // the metric was not found
+ * }
+ * }
+ *
+ * @return {@code true} if the metric was deleted, {@code false} if it was not found
+ */
+ boolean deleteMetric(String metric);
+
+ /**
+ * Sends a request for deleting a metric. This method returns a {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns {@code true} if the metric was deleted,
+ * {@code false} if it was not found.
+ *
+ * Example of asynchronously deleting a metric.
+ *
+ *
{@code
+ * String metricName = "my_metric_name";
+ * ApiFuture future = logging.deleteMetricAsync(metricName);
+ * // ...
+ * boolean deleted = future.get();
+ * if (deleted) {
+ * // the metric was deleted
+ * } else {
+ * // the metric was not found
+ * }
+ * }
+ */
+ ApiFuture deleteMetricAsync(String metric);
+
+ /**
+ * Gets the description of an exclusion or {@code null} if not found.
+ *
+ * Example of getting the description of an exclusion:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * Exclusion exclusion = logging.getExclusion(exclusionName);
+ * if (exclusion == null) {
+ * // exclusion was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Exclusion getExclusion(String exclusion);
+
+ /**
+ * Sends a request to get the description of an exclusion . This method returns an {@code
+ * ApiFuture} object to consume the result. {@link ApiFuture#get()} returns the requested
+ * exclusion or {@code null} if not found.
+ *
+ * Example of asynchronously getting the exclusion:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * ApiFuture future = logging.getExclusionAsync(exclusionName);
+ * // ...
+ * Exclusion exclusion = future.get();
+ * if (exclusion == null) {
+ * // exclusion was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ ApiFuture getExclusionAsync(String exclusion);
+
+ /**
+ * Deletes the requested exclusion.
+ *
+ * Example of deleting the exclusion:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * boolean deleted = logging.deleteExclusion(exclusionName);
+ * if (deleted) {
+ * // the exclusion was deleted
+ * } else {
+ * // the exclusion was not found
+ * }
+ * }
+ *
+ * @return {@code true} if the exclusion was deleted, {@code false} if it was not found
+ */
+ boolean deleteExclusion(String exclusion);
+
+ /**
+ * Sends a request to delete an exclusion. This method returns an {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns {@code true} if the exclusion was deleted,
+ * {@code false} if it was not found.
+ *
+ * Example of asynchronously deleting the exclusion:
+ *
+ *
{@code
+ * String exclusionName = "my_exclusion_name";
+ * ApiFuture future = logging.deleteExclusionAsync(metricName);
+ * // ...
+ * boolean deleted = future.get();
+ * if (deleted) {
+ * // the exclusion was deleted
+ * } else {
+ * // the exclusion was not found
+ * }
+ * }
+ */
+ ApiFuture deleteExclusionAsync(String exclusion);
+
+ /**
+ * Lists the exclusion. This method returns a {@link Page} object that can be used to consume
+ * paginated results. Use {@link ListOption} to specify the page size or the page token from which
+ * to start listing exclusion.
+ *
+ * Example of listing exclusions, specifying the page size:
+ *
+ *
{@code
+ * Page exclusions = logging.listMetrics(ListOption.pageSize(100));
+ * Iterator exclusionIterator = exclusions.iterateAll().iterator();
+ * while (exclusionIterator.hasNext()) {
+ * Exclusion exclusion = exclusionIterator.next();
+ * // do something with the exclusion
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Page listExclusions(ListOption... options);
+
+ /**
+ * Sends a request for listing exclusions. This method returns an {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns an {@link AsyncPage} object that can be
+ * used to asynchronously handle paginated results. Use {@link ListOption} to specify the page
+ * size or the page token from which to start listing exclusions.
+ *
+ * Example of asynchronously listing exclusions, specifying the page size:
+ *
+ *
{@code
+ * ApiFuture> future = logging.listExclusionsAsync(ListOption.pageSize(100));
+ * // ...
+ * AsyncPage exclusions = future.get();
+ * Iterator exclusionIterator = exclusions.iterateAll().iterator();
+ * while (exclusionIterator.hasNext()) {
+ * Exclusion exclusion = exclusionIterator.next();
+ * // do something with the exclusion
+ * }
+ * }
+ */
+ ApiFuture> listExclusionsAsync(ListOption... options);
+
+ /**
+ * Flushes any pending asynchronous logging writes. Logs are automatically flushed based on time
+ * and message count that be configured via {@link com.google.api.gax.batching.BatchingSettings},
+ * Logs are also flushed if enabled, at or above flush severity, see {@link #setFlushSeverity}.
+ * Logging frameworks require support for an explicit flush. See usage in the java.util.logging
+ * handler{@link LoggingHandler}.
+ */
+ void flush();
+
+ /**
+ * Sends a request to log entries to Cloud Logging. Use {@link WriteOption#logName(String)} to
+ * provide a log name for those entries that do not specify one. Use {@link
+ * WriteOption#resource(MonitoredResource)} to provide a monitored resource for those entries that
+ * do not specify one. Use {@link WriteOption#labels(Map)} to provide some labels to be added to
+ * every entry in {@code logEntries}.
+ *
+ * Example of writing log entries and providing a default log name and monitored resource.
+ *
+ *
{@code
+ * String logName = "my_log_name";
+ * List entries = new ArrayList<>();
+ * entries.add(LogEntry.of(StringPayload.of("Entry payload")));
+ * Map jsonMap = new HashMap<>();
+ * jsonMap.put("key", "value");
+ * entries.add(LogEntry.of(JsonPayload.of(jsonMap)));
+ * logging.write(entries, WriteOption.logName(logName),
+ * WriteOption.resource(MonitoredResource.newBuilder("global").build()));
+ * }
+ */
+ void write(Iterable logEntries, WriteOption... options);
+
+ /**
+ * Lists log entries. This method returns a {@link Page} object that can be used to consume
+ * paginated results. Use {@link EntryListOption#pageSize(int)} to specify the page size. Use
+ * {@link EntryListOption#pageToken(String)} to specify the page token from which to start listing
+ * entries. Use {@link EntryListOption#sortOrder(SortingField, SortingOrder)} to sort log entries
+ * according to your preferred order (default is most-recent last). Use {@link
+ * EntryListOption#filter(String)} to filter listed log entries. By default a 24 hour filter is
+ * applied.
+ *
+ * Example of listing log entries for a specific log.
+ *
+ *
{@code
+ * String filter = "logName=projects/my_project_id/logs/my_log_name";
+ * Page entries = logging.listLogEntries(EntryListOption.filter(filter));
+ * Iterator entryIterator = entries.iterateAll().iterator();
+ * while (entryIterator.hasNext()) {
+ * LogEntry entry = entryIterator.next();
+ * // do something with the entry
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ Page listLogEntries(EntryListOption... options);
+
+ /**
+ * Sends a request for listing log entries. This method returns a {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns an {@link AsyncPage} object that can be
+ * used to asynchronously handle paginated results. Use {@link EntryListOption#pageSize(int)} to
+ * specify the page size. Use {@link EntryListOption#pageToken(String)} to specify the page token
+ * from which to start listing entries. Use {@link EntryListOption#sortOrder(SortingField,
+ * SortingOrder)} to sort log entries according to your preferred order (default is most-recent
+ * last). Use {@link EntryListOption#filter(String)} to filter listed log entries. By default a 24
+ * hour filter is applied.
+ *
+ * Example of asynchronously listing log entries for a specific log.
+ *
+ *
{@code
+ * String filter = "logName=projects/my_project_id/logs/my_log_name";
+ * ApiFuture> future = logging.listLogEntriesAsync(EntryListOption.filter(filter));
+ * // ...
+ * AsyncPage entries = future.get();
+ * Iterator entryIterator = entries.iterateAll().iterator();
+ * while (entryIterator.hasNext()) {
+ * LogEntry entry = entryIterator.next();
+ * // do something with the entry
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ ApiFuture> listLogEntriesAsync(EntryListOption... options);
+
+ /**
+ * Sends a request to stream fresh log entries. The method returns a {@code LogEntryServerStream}
+ * object to iterate through the returned stream of the log entries. Use
+ * EntryListOption#bufferWindow(String)} to specify amount of time to buffer log entries at the
+ * server before being returned. entries. Use {@link TailOption#filter(String)} to filter tailed
+ * log entries.
+ *
+ * Example of streaming log entries for a specific project.
+ *
+ *
{@code
+ * LogEntryServerStream stream = logging.tailLogEntries(TailOption.project("my_project_id"));
+ * Iterator it = stream.iterator();
+ * while (it.hasNext()) {
+ * // do something with entry
+ * // call stream.cancel(); to stop streaming
+ * }
+ * }
+ */
+ @BetaApi("The surface for the tail streaming is not stable yet and may change in the future.")
+ LogEntryServerStream tailLogEntries(TailOption... options);
+
+ /**
+ * Populates metadata fields of the immutable collection of {@link LogEntry} items. Only empty
+ * fields are populated. The {@link SourceLocation} is populated only for items with the severity
+ * set to {@link Severity#DEBUG}. The information about {@link HttpRequest}, trace and span Id is
+ * retrieved using {@link ContextHandler}.
+ *
+ * @param logEntries an immutable collection of {@link LogEntry} items.
+ * @param customResource a customized instance of the {@link MonitoredResource}. If this parameter
+ * is {@code null} then the new instance will be generated using {@link
+ * MonitoredResourceUtil#getResource(String, String)}.
+ * @param exclusionClassPaths a list of exclussion class path prefixes. If left empty then {@link
+ * SourceLocation} instance is built based on the caller's stack trace information. Otherwise,
+ * the information from the first {@link StackTraceElement} along the call stack which class
+ * name does not start with any not {@code null} exclusion class paths is used.
+ * @return A collection of {@link LogEntry} items composed from the {@code logEntries} parameter
+ * with populated metadata fields.
+ */
+ default Iterable populateMetadata(
+ Iterable logEntries,
+ MonitoredResource customResource,
+ String... exclusionClassPaths) {
+ throw new UnsupportedOperationException(
+ "method populateMetadata() does not have default implementation");
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingConfig.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingConfig.java
new file mode 100644
index 000000000000..b2cb946e4ab4
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingConfig.java
@@ -0,0 +1,186 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import static com.google.common.base.MoreObjects.firstNonNull;
+
+import com.google.cloud.MonitoredResource;
+import com.google.common.base.Splitter;
+import com.google.common.collect.ImmutableList;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.logging.Filter;
+import java.util.logging.Formatter;
+import java.util.logging.Level;
+import java.util.logging.LogManager;
+import java.util.logging.SimpleFormatter;
+
+class LoggingConfig {
+
+ private final LogManager manager = LogManager.getLogManager();
+ private final String className;
+ private static final String FLUSH_LEVEL_TAG = "flushLevel";
+ private static final String LOG_FILENAME_TAG = "log";
+ private static final String LOG_LEVEL_TAG = "level";
+ private static final String FILTER_TAG = "filter";
+ private static final String FORMATTER_TAG = "formatter";
+ private static final String SYNCHRONICITY_TAG = "synchronicity";
+ private static final String RESOURCE_TYPE_TAG = "resourceType";
+ private static final String ENHANCERS_TAG = "enhancers";
+ private static final String USE_INHERITED_CONTEXT = "useInheritedContext";
+ private static final String AUTO_POPULATE_METADATA = "autoPopulateMetadata";
+ private static final String REDIRECT_TO_STDOUT = "redirectToStdout";
+ private static final String LOG_TARGET = "logTarget";
+
+ public LoggingConfig(String className) {
+ this.className = className;
+ }
+
+ Level getFlushLevel() {
+ return getLevelProperty(FLUSH_LEVEL_TAG, LoggingLevel.ERROR);
+ }
+
+ String getLogName() {
+ return getProperty(LOG_FILENAME_TAG, "java.log");
+ }
+
+ Level getLogLevel() {
+ return getLevelProperty(LOG_LEVEL_TAG, LoggingLevel.INFO);
+ }
+
+ Filter getFilter() {
+ return getFilterProperty(FILTER_TAG, null);
+ }
+
+ Synchronicity getSynchronicity() {
+ String synchronicityStr = getProperty(SYNCHRONICITY_TAG);
+ try {
+ return Synchronicity.valueOf(synchronicityStr);
+ } catch (RuntimeException ex) {
+ // If we cannot create the Synchronicity we fall back to default value
+ }
+ return Synchronicity.ASYNC;
+ }
+
+ Formatter getFormatter() {
+ return getFormatterProperty(FORMATTER_TAG, new SimpleFormatter());
+ }
+
+ Boolean getAutoPopulateMetadata() {
+ return getBooleanProperty(AUTO_POPULATE_METADATA, null);
+ }
+
+ Boolean getRedirectToStdout() {
+ return getBooleanProperty(REDIRECT_TO_STDOUT, null);
+ }
+
+ Optional getLogTarget() {
+ return Optional.ofNullable(getProperty(LOG_TARGET)).map(LoggingHandler.LogTarget::valueOf);
+ }
+
+ MonitoredResource getMonitoredResource(String projectId) {
+ String resourceType = getProperty(RESOURCE_TYPE_TAG, "");
+ return MonitoredResourceUtil.getResource(projectId, resourceType);
+ }
+
+ List getEnhancers() {
+ String list = getProperty(ENHANCERS_TAG);
+ try {
+ List enhancers = new ArrayList<>();
+ if (list != null) {
+ Iterable items = Splitter.on(',').split(list);
+ for (String eName : items) {
+ Class clazz =
+ ClassLoader.getSystemClassLoader().loadClass(eName).asSubclass(LoggingEnhancer.class);
+ enhancers.add(clazz.getDeclaredConstructor().newInstance());
+ }
+ }
+ return ImmutableList.copyOf(enhancers);
+ } catch (Exception ex) {
+ // If we cannot create the enhancers we fall back to the default
+ }
+ return ImmutableList.of();
+ }
+
+ /**
+ * Returns boolean value of the property {@code
+ * com.google.cloud.logging.context.ContextHandler.useInheritedContext}. If no value is defined or
+ * the property does not represent a valid boolean value returns {@code false}.
+ *
+ * @return {@code true} or {@code false}
+ */
+ boolean getUseInheritedContext() {
+ String flag = getProperty(USE_INHERITED_CONTEXT, "FALSE");
+ return Boolean.parseBoolean(flag);
+ }
+
+ private String getProperty(String name, String defaultValue) {
+ return firstNonNull(getProperty(name), defaultValue);
+ }
+
+ private String getProperty(String propertyName) {
+ return manager.getProperty(className + "." + propertyName);
+ }
+
+ private Boolean getBooleanProperty(String name, Boolean defaultValue) {
+ String flag = getProperty(name);
+ if (flag != null) {
+ return Boolean.parseBoolean(flag);
+ }
+ return defaultValue;
+ }
+
+ private Level getLevelProperty(String name, Level defaultValue) {
+ String stringLevel = getProperty(name);
+ if (stringLevel == null) {
+ return defaultValue;
+ }
+ try {
+ return Level.parse(stringLevel);
+ } catch (IllegalArgumentException ex) {
+ // If the level does not exist we fall back to default value
+ }
+ return defaultValue;
+ }
+
+ private Filter getFilterProperty(String name, Filter defaultValue) {
+ String stringFilter = getProperty(name);
+ try {
+ if (stringFilter != null) {
+ Class clz = ClassLoader.getSystemClassLoader().loadClass(stringFilter);
+ return (Filter) clz.getDeclaredConstructor().newInstance();
+ }
+ } catch (Exception ex) {
+ // If we cannot create the filter we fall back to default value
+ }
+ return defaultValue;
+ }
+
+ private Formatter getFormatterProperty(String name, Formatter defaultValue) {
+ String stringFilter = getProperty(name);
+ try {
+ if (stringFilter != null) {
+ Class clz = ClassLoader.getSystemClassLoader().loadClass(stringFilter);
+ return (Formatter) clz.getDeclaredConstructor().newInstance();
+ }
+ } catch (Exception ex) {
+ // If we cannot create the filter we fall back to default value
+ }
+ return defaultValue;
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingEnhancer.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingEnhancer.java
new file mode 100644
index 000000000000..cc64ae119ab6
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingEnhancer.java
@@ -0,0 +1,22 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+/** An enhancer for log entries. Used to add custom labels to the {@link LogEntry.Builder} */
+public interface LoggingEnhancer {
+ void enhanceLogEntry(LogEntry.Builder builder);
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingException.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingException.java
new file mode 100644
index 000000000000..354baef23c40
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingException.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.api.core.BetaApi;
+import com.google.api.gax.rpc.ApiException;
+import com.google.cloud.grpc.BaseGrpcServiceException;
+import java.io.IOException;
+
+/** Logging service exception. */
+public final class LoggingException extends BaseGrpcServiceException {
+
+ private static final long serialVersionUID = 449689219311927047L;
+
+ public LoggingException(IOException ex, boolean idempotent) {
+ super(ex, idempotent);
+ }
+
+ @BetaApi
+ public LoggingException(ApiException apiException) {
+ super(apiException);
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingFactory.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingFactory.java
new file mode 100644
index 000000000000..e2b35f1e4130
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingFactory.java
@@ -0,0 +1,22 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.cloud.ServiceFactory;
+
+/** An interface for Logging factories. */
+public interface LoggingFactory extends ServiceFactory {}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingHandler.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingHandler.java
new file mode 100644
index 000000000000..14f1837cbc22
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingHandler.java
@@ -0,0 +1,521 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import static com.google.common.base.MoreObjects.firstNonNull;
+import static java.util.Arrays.stream;
+
+import com.google.cloud.MonitoredResource;
+import com.google.cloud.logging.Logging.WriteOption;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.Iterables;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.logging.ErrorManager;
+import java.util.logging.Filter;
+import java.util.logging.Formatter;
+import java.util.logging.Handler;
+import java.util.logging.Level;
+import java.util.logging.LogRecord;
+import java.util.logging.Logger;
+import java.util.logging.SimpleFormatter;
+
+/**
+ * A logging handler that outputs logs generated with {@link java.util.logging.Logger} to Cloud
+ * Logging.
+ *
+ * Java logging levels (see {@link java.util.logging.Level}) are mapped to the following Google
+ * Cloud Logging severities:
+ *
+ *
+ * Mapping of Java logging level to Cloud Logging severities
+ *
+ * | Java Level |
+ * Cloud Logging Severity |
+ *
+ *
+ * | SEVERE |
+ * ERROR |
+ *
+ *
+ * | WARNING |
+ * WARNING |
+ *
+ *
+ * | INFO |
+ * INFO |
+ *
+ *
+ * | CONFIG |
+ * INFO |
+ *
+ *
+ * | FINE |
+ * DEBUG |
+ *
+ *
+ * | FINER |
+ * DEBUG |
+ *
+ *
+ * | FINEST |
+ * DEBUG |
+ *
+ *
+ *
+ * Original Java logging levels are added as labels (with {@code levelName} and {@code
+ * levelValue} keys, respectively) to the corresponding Cloud Logging {@link LogEntry}. You can read
+ * entry labels using {@link LogEntry#getLabels()}. To use logging levels that correspond to Cloud
+ * Logging severities you can use {@link LoggingLevel}.
+ *
+ *
Configuration: By default each {@code LoggingHandler} is initialized using the
+ * following {@code LogManager} configuration properties (that you can set in the {@code
+ * logging.properties} file). If properties are not defined (or have invalid values) then the
+ * specified default values are used.
+ *
+ *
+ * - {@code com.google.cloud.logging.LoggingHandler.log} the log name (defaults to {@code
+ * java.log}).
+ *
- {@code com.google.cloud.logging.LoggingHandler.level} specifies the default level for the
+ * handler (defaults to {@code Level.INFO}).
+ *
- {@code com.google.cloud.logging.LoggingHandler.filter} specifies the name of a {@link
+ * Filter} class to use (defaults to no filter).
+ *
- {@code com.google.cloud.logging.LoggingHandler.formatter} specifies the name of a {@link
+ * Formatter} class to use (defaults to {@link SimpleFormatter}).
+ *
- {@code com.google.cloud.logging.LoggingHandler.flushLevel} specifies the flush log level.
+ * When a log with this level is published, logs are transmitted to the Cloud Logging service
+ * (defaults to {@link LoggingLevel#ERROR}).
+ *
- {@code com.google.cloud.logging.LoggingHandler.enhancers} specifies a comma separated list
+ * of {@link LoggingEnhancer} classes. This handler will call each enhancer list whenever it
+ * builds a {@link LogEntry} instance (defaults to empty list).
+ *
- {@code com.google.cloud.logging.LoggingHandler.resourceType} the type name to use when
+ * creating the default {@link MonitoredResource} (defaults to auto-detected resource type,
+ * else "global").
+ *
- {@code com.google.cloud.logging.Synchronicity} the synchronicity of the write method to use
+ * to write logs to the Cloud Logging service (defaults to {@link Synchronicity#ASYNC}).
+ *
- {@code com.google.cloud.logging.LoggingHandler.autoPopulateMetadata} is a boolean flag that
+ * opts-out the population of the log entries metadata before the logs are sent to Cloud
+ * Logging (defaults to {@code true}).
+ *
- {@code com.google.cloud.logging.LoggingHandler.redirectToStdout} is a boolean flag that
+ * opts-in redirecting the output of the handler to STDOUT instead of ingesting logs to Cloud
+ * Logging using Logging API (defaults to {@code false}). Redirecting logs can be used in
+ * Google Cloud environments with installed logging agent to delegate log ingestions to the
+ * agent. Redirected logs are formatted as one line Json string following the structured
+ * logging guidelines. This flag is deprecated; use {@code
+ * com.google.cloud.logging.LoggingHandler.logTarget} instead.
+ *
- {@code com.google.cloud.logging.LoggingHandler.logTarget} is an enumeration controlling log
+ * routing (defaults to {@code CLOUD_LOGGING}). If set to STDOUT or STDERR, logs will be
+ * printed to the corresponding stream in the Json format that can be parsed by the logging
+ * agent. If set to CLOUD_LOGGING, logs will be sent directly to the Google Cloud Logging API.
+ *
+ *
+ * To add a {@code LoggingHandler} to an existing {@link Logger} and be sure to avoid infinite
+ * recursion when logging, use the {@link #addHandler(Logger, LoggingHandler)} method. Alternatively
+ * you can add the handler via {@code logging.properties}. For example using the following line:
+ *
+ *
+ * {@code com.example.mypackage.handlers=com.google.cloud.logging.LoggingHandler}
+ *
+ *
+ * @see Structured logging
+ */
+public class LoggingHandler extends Handler {
+
+ private static final String LEVEL_NAME_KEY = "levelName";
+ private static final String LEVEL_VALUE_KEY = "levelValue";
+
+ /** Where to send logs. */
+ public enum LogTarget {
+ /** Sends logs to the Cloud Logging API. */
+ CLOUD_LOGGING,
+ /** Sends JSON-formatted logs to stdout, for use with the Google Cloud logging agent. */
+ STDOUT,
+ /** Sends JSON-formatted logs to stderr, for use with the Google Cloud logging agent. */
+ STDERR
+ }
+
+ private final List enhancers;
+ private final LoggingOptions loggingOptions;
+
+ private volatile Logging logging;
+
+ // Logs with the same severity with the base could be more efficiently sent to
+ // Cloud.
+ // Defaults to level of the handler or Level.FINEST if the handler is set to
+ // Level.ALL.
+ // Currently there is no way to modify the base level, see
+ // https://github.com/googleapis/google-cloud-java/issues/1740 .
+ private final Level baseLevel;
+
+ private volatile Level flushLevel;
+
+ private volatile Boolean autoPopulateMetadata;
+ private volatile LogTarget logTarget;
+
+ private final WriteOption[] defaultWriteOptions;
+
+ /** Creates a handler that publishes messages to Cloud Logging. */
+ public LoggingHandler() {
+ this(null, null, null);
+ }
+
+ /**
+ * Creates a handler that publishes messages to Cloud Logging.
+ *
+ * @param log the name of the log to which log entries are written
+ */
+ public LoggingHandler(String log) {
+ this(log, null, null);
+ }
+
+ /**
+ * Creates a handler that publishes messages to Cloud Logging.
+ *
+ * @param log the name of the log to which log entries are written
+ * @param options options for the Cloud Logging service
+ */
+ public LoggingHandler(String log, LoggingOptions options) {
+ this(log, options, null);
+ }
+
+ /**
+ * Creates a handler that publishes messages to Cloud Logging.
+ *
+ * @param log the name of the log to which log entries are written
+ * @param options options for the Cloud Logging service
+ * @param monitoredResource the monitored resource to which log entries refer. If it is null then
+ * a default resource is created based on the project ID and deployment environment.
+ */
+ public LoggingHandler(String log, LoggingOptions options, MonitoredResource monitoredResource) {
+ this(log, options, monitoredResource, null, null);
+ }
+
+ /**
+ * Creates a handler that publishes messages to Cloud Logging.
+ *
+ * @param log the name of the log to which log entries are written
+ * @param options options for the Cloud Logging service
+ * @param monitoredResource the monitored resource to which log entries refer. If it is null then
+ * a default resource is created based on the project ID and deployment environment.
+ * @param enhancers List of {@link LoggingEnhancer} instances used to enhance any{@link LogEntry}
+ * instances built by this handler.
+ */
+ public LoggingHandler(
+ String log,
+ LoggingOptions options,
+ MonitoredResource monitoredResource,
+ List enhancers) {
+ this(log, options, monitoredResource, enhancers, null);
+ }
+
+ /**
+ * Creates a handler that publishes messages to Cloud Logging. Auto-population of the logs
+ * metadata can be opted-out in {@code options} argument or in the configuration file. At least
+ * one flag {@link LoggingOptions} or {@link LoggingConfig} has to be explicitly set to {@code
+ * false} in order to opt out the metadata auto-population.
+ *
+ * @param log the name of the log to which log entries are written
+ * @param options options for the Cloud Logging service
+ * @param monitoredResource the monitored resource to which log entries refer. If it is null then
+ * a default resource is created based on the project ID and deployment environment.
+ * @param enhancers List of {@link LoggingEnhancer} instances used to enhance any{@link LogEntry}
+ * instances built by this handler.
+ * @param destination the log destination {@link LogDestinationName} (see 'logName' parameter in
+ * https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry)
+ */
+ public LoggingHandler(
+ String log,
+ LoggingOptions options,
+ MonitoredResource monitoredResource,
+ List enhancers,
+ LogDestinationName destination) {
+ try {
+ loggingOptions = options != null ? options : LoggingOptions.getDefaultInstance();
+ LoggingConfig config = new LoggingConfig(getClass().getName());
+ setFilter(config.getFilter());
+ setFormatter(config.getFormatter());
+ Level level = config.getLogLevel();
+ setLevel(level);
+ baseLevel = level.equals(Level.ALL) ? Level.FINEST : level;
+ flushLevel = config.getFlushLevel();
+ Boolean f1 = loggingOptions.getAutoPopulateMetadata();
+ Boolean f2 = config.getAutoPopulateMetadata();
+ autoPopulateMetadata = isTrueOrNull(f1) && isTrueOrNull(f2);
+ logTarget =
+ config
+ .getLogTarget()
+ .orElse(
+ firstNonNull(config.getRedirectToStdout(), Boolean.FALSE)
+ ? LogTarget.STDOUT
+ : LogTarget.CLOUD_LOGGING);
+ String logName = log != null ? log : config.getLogName();
+ MonitoredResource resource =
+ firstNonNull(
+ monitoredResource, config.getMonitoredResource(loggingOptions.getProjectId()));
+ List writeOptions = new ArrayList<>();
+ writeOptions.add(WriteOption.logName(logName));
+ if (resource != null) {
+ writeOptions.add(WriteOption.resource(resource));
+ }
+ writeOptions.add(
+ WriteOption.labels(
+ ImmutableMap.of(
+ LEVEL_NAME_KEY,
+ baseLevel.getName(),
+ LEVEL_VALUE_KEY,
+ String.valueOf(baseLevel.intValue()))));
+ if (destination != null) {
+ writeOptions.add(WriteOption.destination(destination));
+ }
+ defaultWriteOptions = Iterables.toArray(writeOptions, WriteOption.class);
+
+ logging = loggingOptions.getService();
+ logging.setFlushSeverity(severityFor(flushLevel));
+ logging.setWriteSynchronicity(config.getSynchronicity());
+
+ this.enhancers = new ArrayList<>();
+
+ List enhancersParam =
+ firstNonNull(enhancers, firstNonNull(config.getEnhancers(), ImmutableList.of()));
+
+ this.enhancers.addAll(enhancersParam);
+
+ // In the following line getResourceEnhancers() never returns null (@NotNull
+ // attribute)
+ List loggingEnhancers = MonitoredResourceUtil.getResourceEnhancers();
+ this.enhancers.addAll(loggingEnhancers);
+ } catch (RuntimeException ex) {
+ reportError(null, ex, ErrorManager.OPEN_FAILURE);
+ throw ex;
+ }
+ }
+
+ @Override
+ public void publish(LogRecord record) {
+ // check that the log record should be logged
+ if (!isLoggable(record)) {
+ return;
+ }
+ // HACK warning: this logger doesn't work like normal loggers; the log calls are
+ // issued
+ // from another class instead of by itself, so it can't be configured off like
+ // normal
+ // loggers. We have to check the source class name instead.
+ if ("io.netty.handler.codec.http2.Http2FrameLogger".equals(record.getSourceClassName())) {
+ return;
+ }
+ LogEntry logEntry;
+ try {
+ logEntry = logEntryFor(record).build();
+ } catch (RuntimeException ex) {
+ getErrorManager().error(null, ex, ErrorManager.FORMAT_FAILURE);
+ return;
+ }
+ if (logEntry != null) {
+ try {
+ Iterable logEntries =
+ logTarget == LogTarget.CLOUD_LOGGING
+ ? ImmutableList.of(logEntry)
+ : Instrumentation.populateInstrumentationInfo(ImmutableList.of(logEntry)).y();
+ if (autoPopulateMetadata) {
+ logEntries =
+ logging.populateMetadata(
+ logEntries, getMonitoredResource(), "com.google.cloud.logging", "java");
+ }
+ switch (logTarget) {
+ case STDOUT:
+ logEntries.forEach(log -> System.out.println(log.toStructuredJsonString()));
+ break;
+ case STDERR:
+ logEntries.forEach(log -> System.err.println(log.toStructuredJsonString()));
+ break;
+ case CLOUD_LOGGING:
+ logging.write(logEntries, defaultWriteOptions);
+ break;
+ }
+ } catch (RuntimeException ex) {
+ getErrorManager().error(null, ex, ErrorManager.WRITE_FAILURE);
+ }
+ }
+ }
+
+ private MonitoredResource getMonitoredResource() {
+ Optional resourceOption =
+ stream(defaultWriteOptions)
+ .filter(o -> o.getOptionType() == WriteOption.OptionType.RESOURCE)
+ .findFirst();
+ if (resourceOption.isPresent()) {
+ return (MonitoredResource) resourceOption.get().getValue();
+ }
+ return null;
+ }
+
+ protected LogEntry.Builder logEntryFor(LogRecord record) {
+ String payload = getFormatter().format(record);
+ Level level = record.getLevel();
+ LogEntry.Builder builder =
+ LogEntry.newBuilder(Payload.StringPayload.of(payload))
+ .setTimestamp(Instant.ofEpochMilli(record.getMillis()))
+ .setSeverity(severityFor(level));
+
+ if (!baseLevel.equals(level)) {
+ builder
+ .addLabel("levelName", level.getName())
+ .addLabel("levelValue", String.valueOf(level.intValue()));
+ }
+
+ for (LoggingEnhancer enhancer : enhancers) {
+ enhancer.enhanceLogEntry(builder);
+ }
+ return builder;
+ }
+
+ @Override
+ public void flush() {
+ try {
+ logging.flush();
+ } catch (RuntimeException ex) {
+ getErrorManager().error(null, ex, ErrorManager.FLUSH_FAILURE);
+ }
+ }
+
+ /** Closes the handler and the associated {@link Logging} object. */
+ @Override
+ public synchronized void close() {
+ if (logging != null) {
+ try {
+ logging.close();
+ } catch (Exception ex) {
+ // ignore
+ }
+ }
+ logging = null;
+ }
+
+ /** Get the flush log level. */
+ public Level getFlushLevel() {
+ return flushLevel;
+ }
+
+ /**
+ * Sets minimum logging level to log immediately and flush any pending writes.
+ *
+ * @param flushLevel minimum log level to trigger flush
+ */
+ public void setFlushLevel(Level flushLevel) {
+ this.flushLevel = flushLevel;
+ logging.setFlushSeverity(severityFor(flushLevel));
+ }
+
+ /**
+ * Sets synchronicity of logging writes. By default, writes are asynchronous.
+ *
+ * @param synchronicity {@link Synchronicity}
+ */
+ public void setSynchronicity(Synchronicity synchronicity) {
+ logging.setWriteSynchronicity(synchronicity);
+ }
+
+ /** Get the flush log level. */
+ public Synchronicity getSynchronicity() {
+ return logging.getWriteSynchronicity();
+ }
+
+ /** Sets the metadata auto population flag. */
+ public void setAutoPopulateMetadata(boolean value) {
+ this.autoPopulateMetadata = value;
+ }
+
+ /** Gets the metadata auto population flag. */
+ public Boolean getAutoPopulateMetadata() {
+ return this.autoPopulateMetadata;
+ }
+
+ /**
+ * Enable/disable redirection to STDOUT. If set to {@code true}, logs will be printed to STDOUT in
+ * the Json format that can be parsed by the logging agent. If set to {@code false}, logs will be
+ * ingested to Cloud Logging by calling Logging API.
+ *
+ * This method is mutually exclusive with {@link #setLogTarget(LogTarget)}.
+ *
+ * @deprecated Use {@link #setLogTarget(LogTarget)}.
+ */
+ @Deprecated
+ public void setRedirectToStdout(boolean value) {
+ this.logTarget = value ? LogTarget.STDOUT : LogTarget.CLOUD_LOGGING;
+ }
+
+ /*
+ * @deprecated Use {@link #getLogTarget()}.
+ */
+ @Deprecated
+ public Boolean getRedirectToStdout() {
+ return this.logTarget == LogTarget.STDOUT;
+ }
+
+ /**
+ * Configure the destination for ingested logs. If set to STDOUT or STDERR, logs will be printed
+ * to the corresponding stream in the Json format that can be parsed by the logging agent. If set
+ * to CLOUD_LOGGING, logs will be sent directly to the Google Cloud Logging API.
+ *
+ *
This method is mutually exclusive with {@link #setRedirectToStdout(boolean)}.
+ */
+ public void setLogTarget(LogTarget value) {
+ this.logTarget = value;
+ }
+
+ public LogTarget getLogTarget() {
+ return logTarget;
+ }
+
+ /**
+ * Adds the provided {@code LoggingHandler} to {@code logger}. Use this method to register Cloud
+ * Logging handlers instead of {@link Logger#addHandler(Handler)} to avoid infinite recursion when
+ * logging.
+ */
+ public static void addHandler(Logger logger, LoggingHandler handler) {
+ logger.addHandler(handler);
+ }
+
+ private static Severity severityFor(Level level) {
+ if (level instanceof LoggingLevel) {
+ return ((LoggingLevel) level).getSeverity();
+ }
+ // Choose the severity based on Level range.
+ // The assumption is that Level values below maintain same numeric value
+ int value = level.intValue();
+ if (value <= Level.FINE.intValue()) {
+ return Severity.DEBUG;
+ } else if (value <= Level.INFO.intValue()) {
+ return Severity.INFO;
+ } else if (value <= Level.WARNING.intValue()) {
+ return Severity.WARNING;
+ } else if (value <= Level.SEVERE.intValue()) {
+ return Severity.ERROR;
+ } else if (value == Level.OFF.intValue()) {
+ return Severity.NONE;
+ }
+ return Severity.DEFAULT;
+ }
+
+ private static boolean isTrueOrNull(Boolean b) {
+ return b == null || b.equals(Boolean.TRUE);
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingImpl.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingImpl.java
new file mode 100644
index 000000000000..55068e8705ed
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingImpl.java
@@ -0,0 +1,1174 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import static com.google.api.client.util.Preconditions.checkArgument;
+import static com.google.cloud.logging.Logging.EntryListOption.OptionType.ORDER_BY;
+import static com.google.cloud.logging.Logging.ListOption.OptionType.PAGE_SIZE;
+import static com.google.cloud.logging.Logging.ListOption.OptionType.PAGE_TOKEN;
+import static com.google.cloud.logging.Logging.WriteOption.OptionType.LABELS;
+import static com.google.cloud.logging.Logging.WriteOption.OptionType.LOG_DESTINATION;
+import static com.google.cloud.logging.Logging.WriteOption.OptionType.LOG_NAME;
+import static com.google.cloud.logging.Logging.WriteOption.OptionType.PARTIAL_SUCCESS;
+import static com.google.cloud.logging.Logging.WriteOption.OptionType.RESOURCE;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.api.client.util.Strings;
+import com.google.api.core.ApiFunction;
+import com.google.api.core.ApiFuture;
+import com.google.api.core.ApiFutureCallback;
+import com.google.api.core.ApiFutures;
+import com.google.api.gax.paging.AsyncPage;
+import com.google.api.gax.paging.Page;
+import com.google.api.gax.rpc.BidiStream;
+import com.google.cloud.AsyncPageImpl;
+import com.google.cloud.BaseService;
+import com.google.cloud.MonitoredResource;
+import com.google.cloud.MonitoredResourceDescriptor;
+import com.google.cloud.PageImpl;
+import com.google.cloud.Tuple;
+import com.google.cloud.logging.ContextHandler.ContextPriority;
+import com.google.cloud.logging.spi.v2.LoggingRpc;
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.Ascii;
+import com.google.common.base.Function;
+import com.google.common.base.Throwables;
+import com.google.common.base.VerifyException;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Iterables;
+import com.google.common.collect.Lists;
+import com.google.common.collect.Maps;
+import com.google.common.util.concurrent.MoreExecutors;
+import com.google.common.util.concurrent.Uninterruptibles;
+import com.google.logging.v2.CreateExclusionRequest;
+import com.google.logging.v2.CreateLogMetricRequest;
+import com.google.logging.v2.CreateSinkRequest;
+import com.google.logging.v2.DeleteExclusionRequest;
+import com.google.logging.v2.DeleteLogMetricRequest;
+import com.google.logging.v2.DeleteLogRequest;
+import com.google.logging.v2.DeleteSinkRequest;
+import com.google.logging.v2.GetExclusionRequest;
+import com.google.logging.v2.GetLogMetricRequest;
+import com.google.logging.v2.GetSinkRequest;
+import com.google.logging.v2.ListExclusionsRequest;
+import com.google.logging.v2.ListExclusionsResponse;
+import com.google.logging.v2.ListLogEntriesRequest;
+import com.google.logging.v2.ListLogEntriesResponse;
+import com.google.logging.v2.ListLogMetricsRequest;
+import com.google.logging.v2.ListLogMetricsResponse;
+import com.google.logging.v2.ListLogsRequest;
+import com.google.logging.v2.ListLogsResponse;
+import com.google.logging.v2.ListMonitoredResourceDescriptorsRequest;
+import com.google.logging.v2.ListMonitoredResourceDescriptorsResponse;
+import com.google.logging.v2.ListSinksRequest;
+import com.google.logging.v2.ListSinksResponse;
+import com.google.logging.v2.LogExclusionName;
+import com.google.logging.v2.LogMetricName;
+import com.google.logging.v2.LogName;
+import com.google.logging.v2.LogSinkName;
+import com.google.logging.v2.ProjectName;
+import com.google.logging.v2.TailLogEntriesRequest;
+import com.google.logging.v2.TailLogEntriesResponse;
+import com.google.logging.v2.UpdateExclusionRequest;
+import com.google.logging.v2.UpdateLogMetricRequest;
+import com.google.logging.v2.UpdateSinkRequest;
+import com.google.logging.v2.WriteLogEntriesRequest;
+import com.google.logging.v2.WriteLogEntriesResponse;
+import com.google.protobuf.Empty;
+import com.google.protobuf.util.Durations;
+import io.opentelemetry.api.trace.Span;
+import java.text.ParseException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+class LoggingImpl extends BaseService implements Logging {
+ protected static final String RESOURCE_NAME_FORMAT = "projects/%s/traces/%s";
+ private static final int FLUSH_WAIT_TIMEOUT_SECONDS = 6;
+ private final LoggingRpc rpc;
+ private final Map> pendingWrites = new ConcurrentHashMap<>();
+
+ private volatile Synchronicity writeSynchronicity = Synchronicity.ASYNC;
+ private volatile Severity flushSeverity = Severity.NONE;
+ private boolean closed;
+
+ private static Boolean emptyToBooleanFunction(Empty input) {
+ return input != null;
+ }
+
+ private static final Function WRITE_RESPONSE_TO_VOID_FUNCTION =
+ new Function() {
+ @Override
+ public Void apply(WriteLogEntriesResponse input) {
+ return null;
+ }
+ };
+ private static final ThreadLocal inWriteCall = new ThreadLocal<>();
+
+ @VisibleForTesting
+ static ITimestampDefaultFilter defaultTimestampFilterCreator = new TimestampDefaultFilter();
+
+ LoggingImpl(LoggingOptions options) {
+ super(options);
+ rpc = options.getLoggingRpcV2();
+ }
+
+ @Override
+ public void setWriteSynchronicity(Synchronicity writeSynchronicity) {
+ this.writeSynchronicity = writeSynchronicity;
+ }
+
+ @Override
+ public void setFlushSeverity(Severity flushSeverity) {
+ // For backward compatibility we treat null as Severity.NONE
+ if (flushSeverity == null) {
+ this.flushSeverity = Severity.NONE;
+ } else {
+ this.flushSeverity = flushSeverity;
+ }
+ }
+
+ @Override
+ public Synchronicity getWriteSynchronicity() {
+ return writeSynchronicity;
+ }
+
+ @Override
+ public Severity getFlushSeverity() {
+ return flushSeverity;
+ }
+
+ private static V get(ApiFuture future) {
+ try {
+ return Uninterruptibles.getUninterruptibly(future);
+ } catch (ExecutionException ex) {
+ Throwables.throwIfUnchecked(ex.getCause());
+ throw new VerifyException(ex);
+ }
+ }
+
+ private static ApiFuture transform(
+ ApiFuture future, final Function function) {
+ return ApiFutures.transform(
+ future,
+ new ApiFunction() {
+ @Override
+ public O apply(I i) {
+ return function.apply(i);
+ }
+ },
+ MoreExecutors.directExecutor());
+ }
+
+ private abstract static class BasePageFetcher implements AsyncPageImpl.NextPageFetcher {
+
+ private static final long serialVersionUID = 5095123855547444030L;
+
+ private final LoggingOptions serviceOptions;
+ private final Map requestOptions;
+
+ private BasePageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ this.serviceOptions = serviceOptions;
+ this.requestOptions = PageImpl.nextRequestOptions(PAGE_TOKEN, cursor, requestOptions);
+ }
+
+ LoggingOptions serviceOptions() {
+ return serviceOptions;
+ }
+
+ Map requestOptions() {
+ return requestOptions;
+ }
+ }
+
+ private static class SinkPageFetcher extends BasePageFetcher {
+
+ private static final long serialVersionUID = 4879364260060886875L;
+
+ SinkPageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ super(serviceOptions, cursor, requestOptions);
+ }
+
+ @Override
+ public ApiFuture> getNextPage() {
+ return listSinksAsync(serviceOptions(), requestOptions());
+ }
+ }
+
+ private static class LogNamePageFetcher extends BasePageFetcher {
+ private static final long serialVersionUID = 5308841362690185583L;
+
+ LogNamePageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ super(serviceOptions, cursor, requestOptions);
+ }
+
+ @Override
+ public ApiFuture> getNextPage() {
+ return listLogsAsync(serviceOptions(), requestOptions());
+ }
+ }
+
+ private static class MonitoredResourceDescriptorPageFetcher
+ extends BasePageFetcher {
+
+ private static final long serialVersionUID = -2346495771766629195L;
+
+ MonitoredResourceDescriptorPageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ super(serviceOptions, cursor, requestOptions);
+ }
+
+ @Override
+ public ApiFuture> getNextPage() {
+ return listMonitoredResourceDescriptorsAsync(serviceOptions(), requestOptions());
+ }
+ }
+
+ private static class MetricPageFetcher extends BasePageFetcher {
+
+ private static final long serialVersionUID = -316783549651771553L;
+
+ MetricPageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ super(serviceOptions, cursor, requestOptions);
+ }
+
+ @Override
+ public ApiFuture> getNextPage() {
+ return listMetricsAsync(serviceOptions(), requestOptions());
+ }
+ }
+
+ private static class ExclusionPageFetcher extends BasePageFetcher {
+ private static final long serialVersionUID = -1414118808031778916L;
+
+ ExclusionPageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ super(serviceOptions, cursor, requestOptions);
+ }
+
+ @Override
+ public ApiFuture> getNextPage() {
+ return listExclusionAsync(serviceOptions(), requestOptions());
+ }
+ }
+
+ private static class LogEntryPageFetcher extends BasePageFetcher {
+
+ private static final long serialVersionUID = 4001239712280747734L;
+
+ LogEntryPageFetcher(
+ LoggingOptions serviceOptions, String cursor, Map requestOptions) {
+ super(serviceOptions, cursor, requestOptions);
+ }
+
+ @Override
+ public ApiFuture> getNextPage() {
+ return listLogEntriesAsync(serviceOptions(), requestOptions());
+ }
+ }
+
+ @Override
+ public Sink create(SinkInfo sink) {
+ return get(createAsync(sink));
+ }
+
+ @Override
+ public Metric create(MetricInfo metric) {
+ return get(createAsync(metric));
+ }
+
+ @Override
+ public Exclusion create(Exclusion exclusion) {
+ return get(createAsync(exclusion));
+ }
+
+ @Override
+ public ApiFuture createAsync(SinkInfo sink) {
+ CreateSinkRequest request =
+ CreateSinkRequest.newBuilder()
+ .setParent(ProjectName.of(getOptions().getProjectId()).toString())
+ .setSink(sink.toPb(getOptions().getProjectId()))
+ .build();
+ return transform(rpc.create(request), Sink.fromPbFunction(this));
+ }
+
+ @Override
+ public ApiFuture createAsync(MetricInfo metric) {
+ CreateLogMetricRequest request =
+ CreateLogMetricRequest.newBuilder()
+ .setParent(ProjectName.of(getOptions().getProjectId()).toString())
+ .setMetric(metric.toPb())
+ .build();
+ return transform(rpc.create(request), Metric.fromPbFunction(this));
+ }
+
+ @Override
+ public ApiFuture createAsync(Exclusion exclusion) {
+ CreateExclusionRequest request =
+ CreateExclusionRequest.newBuilder()
+ .setParent(ProjectName.of(getOptions().getProjectId()).toString())
+ .setExclusion(exclusion.toProtobuf())
+ .build();
+ return transform(rpc.create(request), Exclusion.FROM_PROTOBUF_FUNCTION);
+ }
+
+ @Override
+ public Sink update(SinkInfo sink) {
+ return get(updateAsync(sink));
+ }
+
+ @Override
+ public Metric update(MetricInfo metric) {
+ return get(updateAsync(metric));
+ }
+
+ @Override
+ public Exclusion update(Exclusion exclusion) {
+ return get(updateAsync(exclusion));
+ }
+
+ @Override
+ public ApiFuture updateAsync(SinkInfo sink) {
+ UpdateSinkRequest request =
+ UpdateSinkRequest.newBuilder()
+ .setSinkName(
+ LogSinkName.ofProjectSinkName(getOptions().getProjectId(), sink.getName())
+ .toString())
+ .setSink(sink.toPb(getOptions().getProjectId()))
+ .build();
+ return transform(rpc.update(request), Sink.fromPbFunction(this));
+ }
+
+ @Override
+ public ApiFuture updateAsync(MetricInfo metric) {
+ UpdateLogMetricRequest request =
+ UpdateLogMetricRequest.newBuilder()
+ .setMetricName(
+ LogMetricName.of(getOptions().getProjectId(), metric.getName()).toString())
+ .setMetric(metric.toPb())
+ .build();
+ return transform(rpc.update(request), Metric.fromPbFunction(this));
+ }
+
+ @Override
+ public ApiFuture updateAsync(Exclusion exclusion) {
+ UpdateExclusionRequest request =
+ UpdateExclusionRequest.newBuilder()
+ .setName(
+ LogExclusionName.of(getOptions().getProjectId(), exclusion.getName()).toString())
+ .setExclusion(exclusion.toProtobuf())
+ .build();
+ return transform(rpc.update(request), Exclusion.FROM_PROTOBUF_FUNCTION);
+ }
+
+ @Override
+ public Sink getSink(String sink) {
+ return get(getSinkAsync(sink));
+ }
+
+ @Override
+ public ApiFuture getSinkAsync(String sink) {
+ GetSinkRequest request =
+ GetSinkRequest.newBuilder()
+ .setSinkName(
+ LogSinkName.ofProjectSinkName(getOptions().getProjectId(), sink).toString())
+ .build();
+ return transform(rpc.get(request), Sink.fromPbFunction(this));
+ }
+
+ private static ListSinksRequest listSinksRequest(
+ LoggingOptions serviceOptions, Map options) {
+ ListSinksRequest.Builder builder = ListSinksRequest.newBuilder();
+ builder.setParent(ProjectName.of(serviceOptions.getProjectId()).toString());
+ Integer pageSize = PAGE_SIZE.get(options);
+ String pageToken = PAGE_TOKEN.get(options);
+ if (pageSize != null) {
+ builder.setPageSize(pageSize);
+ }
+ if (pageToken != null) {
+ builder.setPageToken(pageToken);
+ }
+ return builder.build();
+ }
+
+ private static ApiFuture> listSinksAsync(
+ final LoggingOptions serviceOptions, final Map options) {
+ final ListSinksRequest request = listSinksRequest(serviceOptions, options);
+ ApiFuture list = serviceOptions.getLoggingRpcV2().list(request);
+ return transform(
+ list,
+ new Function>() {
+ @Override
+ public AsyncPage apply(ListSinksResponse listSinksResponse) {
+ List sinks =
+ listSinksResponse.getSinksList().isEmpty()
+ ? ImmutableList.of()
+ : Lists.transform(
+ listSinksResponse.getSinksList(),
+ Sink.fromPbFunction(serviceOptions.getService()));
+ String cursor =
+ listSinksResponse.getNextPageToken().isEmpty()
+ ? null
+ : listSinksResponse.getNextPageToken();
+ return new AsyncPageImpl<>(
+ new SinkPageFetcher(serviceOptions, cursor, options), cursor, sinks);
+ }
+ });
+ }
+
+ @Override
+ public ApiFuture> listSinksAsync(ListOption... options) {
+ return listSinksAsync(getOptions(), optionMap(options));
+ }
+
+ @Override
+ public Page listSinks(ListOption... options) {
+ return get(listSinksAsync(options));
+ }
+
+ @Override
+ public boolean deleteSink(String sink) {
+ return get(deleteSinkAsync(sink));
+ }
+
+ @Override
+ public ApiFuture deleteSinkAsync(String sink) {
+ DeleteSinkRequest request =
+ DeleteSinkRequest.newBuilder()
+ .setSinkName(
+ LogSinkName.ofProjectSinkName(getOptions().getProjectId(), sink).toString())
+ .build();
+ return transform(rpc.delete(request), LoggingImpl::emptyToBooleanFunction);
+ }
+
+ /**
+ * Creates a new {@code ListLogsRequest} object.
+ *
+ * Builds an instance of {@code ListLogsRequest} using page size, page token and project id
+ * from the {@code LoggingOptions}. The project id is used as the request's parent parameter.
+ *
+ * @see com.google.logging.v2.ListLogEntriesRequest
+ * @return the created {@code ListLogsRequest} object
+ */
+ private static ListLogsRequest listLogsRequest(
+ LoggingOptions serviceOptions, Map options) {
+ ListLogsRequest.Builder builder = ListLogsRequest.newBuilder();
+ builder.setParent(ProjectName.of(serviceOptions.getProjectId()).toString());
+ Integer pageSize = PAGE_SIZE.get(options);
+ String pageToken = PAGE_TOKEN.get(options);
+ if (pageSize != null) {
+ builder.setPageSize(pageSize);
+ }
+ if (pageToken != null) {
+ builder.setPageToken(pageToken);
+ }
+ return builder.build();
+ }
+
+ private static ApiFuture> listLogsAsync(
+ final LoggingOptions serviceOptions, final Map options) {
+ final ListLogsRequest request = listLogsRequest(serviceOptions, options);
+ ApiFuture list = serviceOptions.getLoggingRpcV2().listLogs(request);
+ return transform(
+ list,
+ new Function>() {
+ @Override
+ public AsyncPage apply(ListLogsResponse listLogsResponse) {
+ List logNames =
+ listLogsResponse.getLogNamesList().isEmpty()
+ ? ImmutableList.of()
+ : listLogsResponse.getLogNamesList();
+ String cursor =
+ listLogsResponse.getNextPageToken().isEmpty()
+ ? null
+ : listLogsResponse.getNextPageToken();
+ return new AsyncPageImpl<>(
+ new LogNamePageFetcher(serviceOptions, cursor, options), cursor, logNames);
+ }
+ });
+ }
+
+ @Override
+ public ApiFuture> listLogsAsync(ListOption... options) {
+ return listLogsAsync(getOptions(), optionMap(options));
+ }
+
+ @Override
+ public Page listLogs(ListOption... options) {
+ return get(listLogsAsync(options));
+ }
+
+ @Override
+ public boolean deleteLog(String log) {
+ return get(deleteLogAsync(log, null));
+ }
+
+ @Override
+ public boolean deleteLog(String log, LogDestinationName destination) {
+ return get(deleteLogAsync(log, destination));
+ }
+
+ @Override
+ public ApiFuture deleteLogAsync(String log) {
+ return deleteLogAsync(log, null);
+ }
+
+ @Override
+ public ApiFuture deleteLogAsync(String log, LogDestinationName destination) {
+ checkNotNull(log, "log parameter cannot be null");
+ String projectId = getOptions().getProjectId();
+ if (destination == null) {
+ checkNotNull(projectId, "projectId parameter cannot be null");
+ }
+ LogName name = getLogName(projectId, log, destination);
+ DeleteLogRequest request = DeleteLogRequest.newBuilder().setLogName(name.toString()).build();
+ return transform(rpc.delete(request), LoggingImpl::emptyToBooleanFunction);
+ }
+
+ private static ListMonitoredResourceDescriptorsRequest listMonitoredResourceDescriptorsRequest(
+ Map options) {
+ ListMonitoredResourceDescriptorsRequest.Builder builder =
+ ListMonitoredResourceDescriptorsRequest.newBuilder();
+ Integer pageSize = PAGE_SIZE.get(options);
+ String pageToken = PAGE_TOKEN.get(options);
+ if (pageSize != null) {
+ builder.setPageSize(pageSize);
+ }
+ if (pageToken != null) {
+ builder.setPageToken(pageToken);
+ }
+ return builder.build();
+ }
+
+ private static ApiFuture>
+ listMonitoredResourceDescriptorsAsync(
+ final LoggingOptions serviceOptions, final Map options) {
+ final ListMonitoredResourceDescriptorsRequest request =
+ listMonitoredResourceDescriptorsRequest(options);
+ ApiFuture list =
+ serviceOptions.getLoggingRpcV2().list(request);
+ return transform(
+ list,
+ new Function<
+ ListMonitoredResourceDescriptorsResponse, AsyncPage>() {
+ @Override
+ public AsyncPage apply(
+ ListMonitoredResourceDescriptorsResponse listDescriptorsResponse) {
+ List descriptors =
+ listDescriptorsResponse.getResourceDescriptorsList().isEmpty()
+ ? ImmutableList.of()
+ : Lists.transform(
+ listDescriptorsResponse.getResourceDescriptorsList(),
+ (com.google.api.MonitoredResourceDescriptor
+ monitoredResourceDescriptor) -> {
+ return MonitoredResourceDescriptor.FROM_PB_FUNCTION.apply(
+ monitoredResourceDescriptor);
+ });
+ String cursor =
+ listDescriptorsResponse.getNextPageToken().isEmpty()
+ ? null
+ : listDescriptorsResponse.getNextPageToken();
+ return new AsyncPageImpl<>(
+ new MonitoredResourceDescriptorPageFetcher(serviceOptions, cursor, options),
+ cursor,
+ descriptors);
+ }
+ });
+ }
+
+ @Override
+ public ApiFuture> listMonitoredResourceDescriptorsAsync(
+ ListOption... options) {
+ return listMonitoredResourceDescriptorsAsync(getOptions(), optionMap(options));
+ }
+
+ @Override
+ public Page listMonitoredResourceDescriptors(ListOption... options) {
+ return get(listMonitoredResourceDescriptorsAsync(options));
+ }
+
+ @Override
+ public Metric getMetric(String metric) {
+ return get(getMetricAsync(metric));
+ }
+
+ @Override
+ public ApiFuture getMetricAsync(String metric) {
+ GetLogMetricRequest request =
+ GetLogMetricRequest.newBuilder()
+ .setMetricName(LogMetricName.of(getOptions().getProjectId(), metric).toString())
+ .build();
+ return transform(rpc.get(request), Metric.fromPbFunction(this));
+ }
+
+ private static ListLogMetricsRequest listMetricsRequest(
+ LoggingOptions serviceOptions, Map options) {
+ ListLogMetricsRequest.Builder builder = ListLogMetricsRequest.newBuilder();
+ builder.setParent(ProjectName.of(serviceOptions.getProjectId()).toString());
+ Integer pageSize = PAGE_SIZE.get(options);
+ String pageToken = PAGE_TOKEN.get(options);
+ if (pageSize != null) {
+ builder.setPageSize(pageSize);
+ }
+ if (pageToken != null) {
+ builder.setPageToken(pageToken);
+ }
+ return builder.build();
+ }
+
+ private static ApiFuture> listMetricsAsync(
+ final LoggingOptions serviceOptions, final Map options) {
+ final ListLogMetricsRequest request = listMetricsRequest(serviceOptions, options);
+ ApiFuture list = serviceOptions.getLoggingRpcV2().list(request);
+ return transform(
+ list,
+ new Function>() {
+ @Override
+ public AsyncPage apply(ListLogMetricsResponse listMetricsResponse) {
+ List metrics =
+ listMetricsResponse.getMetricsList().isEmpty()
+ ? ImmutableList.of()
+ : Lists.transform(
+ listMetricsResponse.getMetricsList(),
+ Metric.fromPbFunction(serviceOptions.getService()));
+ String cursor =
+ listMetricsResponse.getNextPageToken().isEmpty()
+ ? null
+ : listMetricsResponse.getNextPageToken();
+ return new AsyncPageImpl<>(
+ new MetricPageFetcher(serviceOptions, cursor, options), cursor, metrics);
+ }
+ });
+ }
+
+ @Override
+ public ApiFuture> listMetricsAsync(ListOption... options) {
+ return listMetricsAsync(getOptions(), optionMap(options));
+ }
+
+ @Override
+ public Page listMetrics(ListOption... options) {
+ return get(listMetricsAsync(options));
+ }
+
+ @Override
+ public boolean deleteMetric(String metric) {
+ return get(deleteMetricAsync(metric));
+ }
+
+ @Override
+ public ApiFuture deleteMetricAsync(String metric) {
+ DeleteLogMetricRequest request =
+ DeleteLogMetricRequest.newBuilder()
+ .setMetricName(LogMetricName.of(getOptions().getProjectId(), metric).toString())
+ .build();
+ return transform(rpc.delete(request), LoggingImpl::emptyToBooleanFunction);
+ }
+
+ @Override
+ public Exclusion getExclusion(String exclusion) {
+ return get(getExclusionAsync(exclusion));
+ }
+
+ @Override
+ public ApiFuture getExclusionAsync(String exclusion) {
+ GetExclusionRequest request =
+ GetExclusionRequest.newBuilder()
+ .setName(LogExclusionName.of(getOptions().getProjectId(), exclusion).toString())
+ .build();
+ return transform(rpc.get(request), Exclusion.FROM_PROTOBUF_FUNCTION);
+ }
+
+ @Override
+ public boolean deleteExclusion(String exclusion) {
+ return get(deleteExclusionAsync(exclusion));
+ }
+
+ @Override
+ public ApiFuture deleteExclusionAsync(String exclusion) {
+ DeleteExclusionRequest request =
+ DeleteExclusionRequest.newBuilder()
+ .setName(LogExclusionName.of(getOptions().getProjectId(), exclusion).toString())
+ .build();
+ return transform(rpc.delete(request), LoggingImpl::emptyToBooleanFunction);
+ }
+
+ @Override
+ public Page listExclusions(ListOption... options) {
+ return get(listExclusionsAsync(options));
+ }
+
+ @Override
+ public ApiFuture> listExclusionsAsync(ListOption... options) {
+ return listExclusionAsync(getOptions(), optionMap(options));
+ }
+
+ private static ListExclusionsRequest listExclusionsRequest(
+ LoggingOptions serviceOptions, Map options) {
+ ListExclusionsRequest.Builder builder = ListExclusionsRequest.newBuilder();
+ builder.setParent(ProjectName.of(serviceOptions.getProjectId()).toString());
+ Integer pageSize = PAGE_SIZE.get(options);
+ String pageToken = PAGE_TOKEN.get(options);
+ if (pageSize != null) {
+ builder.setPageSize(pageSize);
+ }
+ if (pageToken != null) {
+ builder.setPageToken(pageToken);
+ }
+ return builder.build();
+ }
+
+ private static ApiFuture> listExclusionAsync(
+ final LoggingOptions serviceOptions, final Map options) {
+ final ListExclusionsRequest request = listExclusionsRequest(serviceOptions, options);
+ ApiFuture list = serviceOptions.getLoggingRpcV2().list(request);
+ return transform(
+ list,
+ new Function>() {
+ @Override
+ public AsyncPage apply(ListExclusionsResponse listExclusionsResponse) {
+ List exclusions =
+ listExclusionsResponse.getExclusionsList().isEmpty()
+ ? ImmutableList.of()
+ : Lists.transform(
+ listExclusionsResponse.getExclusionsList(),
+ Exclusion.FROM_PROTOBUF_FUNCTION);
+ String cursor =
+ listExclusionsResponse.getNextPageToken().isEmpty()
+ ? null
+ : listExclusionsResponse.getNextPageToken();
+ return new AsyncPageImpl<>(
+ new ExclusionPageFetcher(serviceOptions, cursor, options), cursor, exclusions);
+ }
+ });
+ }
+
+ private static WriteLogEntriesRequest writeLogEntriesRequest(
+ LoggingOptions serviceOptions,
+ Iterable logEntries,
+ Map options) {
+ WriteLogEntriesRequest.Builder builder = WriteLogEntriesRequest.newBuilder();
+ String projectId = serviceOptions.getProjectId();
+
+ LogName logName = getLogName(projectId, LOG_NAME.get(options), LOG_DESTINATION.get(options));
+
+ if (logName != null) {
+ builder.setLogName(logName.toString());
+ }
+ MonitoredResource resource = RESOURCE.get(options);
+ if (resource != null) {
+ builder.setResource(resource.toPb());
+ }
+ Map labels = LABELS.get(options);
+ if (labels != null) {
+ builder.putAllLabels(labels);
+ }
+
+ builder.setPartialSuccess(Boolean.TRUE.equals(PARTIAL_SUCCESS.get(options)));
+ builder.addAllEntries(Iterables.transform(logEntries, LogEntry.toPbFunction(projectId)));
+ return builder.build();
+ }
+
+ private static LogName getLogName(
+ String projectId, String logName, LogDestinationName destination) {
+ if (logName == null) {
+ return null;
+ }
+
+ // If no destination specified, fallback to project based log name
+ if (destination == null) {
+ return LogName.ofProjectLogName(projectId, logName);
+ }
+
+ return destination.toLogName(logName);
+ }
+
+ @Override
+ public Iterable populateMetadata(
+ Iterable logEntries,
+ MonitoredResource customResource,
+ String... exclusionClassPaths) {
+ checkNotNull(logEntries);
+ final boolean needDebugInfo =
+ Iterables.any(
+ logEntries,
+ log -> log.getSeverity() == Severity.DEBUG && log.getSourceLocation() == null);
+ final SourceLocation sourceLocation =
+ needDebugInfo ? SourceLocation.fromCurrentContext(exclusionClassPaths) : null;
+ // populate monitored resource metadata by prioritizing the one set via
+ // WriteOption
+ final MonitoredResource resourceMetadata =
+ customResource == null
+ ? MonitoredResourceUtil.getResource(getOptions().getProjectId(), null)
+ : customResource;
+
+ final ArrayList populatedLogEntries = Lists.newArrayList();
+
+ // populate empty metadata fields of log entries before calling write API
+ for (LogEntry entry : logEntries) {
+ if (entry == null) {
+ continue;
+ }
+ LogEntry.Builder entityBuilder = entry.toBuilder();
+ if (resourceMetadata != null && entry.getResource() == null) {
+ entityBuilder.setResource(resourceMetadata);
+ }
+
+ ContextHandler contextHandler = new ContextHandler();
+ // Populate trace/span ID from OpenTelemetry span context to logging context.
+ if (Span.current().getSpanContext().isValid()) {
+ Context.Builder contextBuilder = Context.newBuilder().loadOpenTelemetryContext();
+ contextHandler.setCurrentContext(contextBuilder.build(), ContextPriority.OTEL_EXTRACTED);
+ }
+
+ Context context = contextHandler.getCurrentContext();
+ if (context != null && entry.getHttpRequest() == null) {
+ entityBuilder.setHttpRequest(context.getHttpRequest());
+ }
+ if (context != null && Strings.isNullOrEmpty(entry.getTrace())) {
+ MonitoredResource resource =
+ entry.getResource() != null ? entry.getResource() : resourceMetadata;
+ entityBuilder.setTrace(getFormattedTrace(context.getTraceId(), resource));
+ entityBuilder.setTraceSampled(context.getTraceSampled());
+ }
+ if (context != null && Strings.isNullOrEmpty(entry.getSpanId())) {
+ entityBuilder.setSpanId(context.getSpanId());
+ }
+ if (entry.getSeverity() == Severity.DEBUG && entry.getSourceLocation() == null) {
+ entityBuilder.setSourceLocation(sourceLocation);
+ }
+ populatedLogEntries.add(entityBuilder.build());
+ }
+ return populatedLogEntries;
+ }
+
+ @Override
+ public void write(Iterable logEntries, WriteOption... options) {
+ if (inWriteCall.get() != null) {
+ return;
+ }
+ inWriteCall.set(true);
+
+ try {
+ final Map writeOptions = optionMap(options);
+ final Boolean loggingOptionsPopulateFlag = getOptions().getAutoPopulateMetadata();
+ final Boolean writeOptionPartialSuccessFlag =
+ WriteOption.OptionType.PARTIAL_SUCCESS.get(writeOptions);
+ final Boolean writeOptionPopulateFlag =
+ WriteOption.OptionType.AUTO_POPULATE_METADATA.get(writeOptions);
+ Tuple> pair =
+ Instrumentation.populateInstrumentationInfo(logEntries);
+ logEntries = pair.y();
+
+ if (Objects.equals(writeOptionPopulateFlag, Boolean.TRUE)
+ || (writeOptionPopulateFlag == null
+ && Objects.equals(loggingOptionsPopulateFlag, Boolean.TRUE))) {
+ final MonitoredResource sharedResourceMetadata = RESOURCE.get(writeOptions);
+ logEntries =
+ populateMetadata(logEntries, sharedResourceMetadata, this.getClass().getName());
+ }
+ // Add partialSuccess = true option always for request which does not have
+ // it set explicitly in options.
+ // For request containing instrumentation data (e.g. when pair.x() == true),
+ // always set or override partialSuccess with true.
+ if (pair.x() || writeOptionPartialSuccessFlag == null) {
+ options = Instrumentation.addPartialSuccessOption(options);
+ }
+ writeLogEntries(logEntries, options);
+ if (flushSeverity != Severity.NONE) {
+ for (LogEntry logEntry : logEntries) {
+ // flush pending writes if log severity at or above flush severity
+ if (logEntry.getSeverity().compareTo(flushSeverity) >= 0) {
+ flush();
+ break;
+ }
+ }
+ }
+ } finally {
+ inWriteCall.remove();
+ }
+ }
+
+ @Override
+ public void flush() {
+ // BUG(1795): We should force batcher to issue RPC call for buffered messages,
+ // so the code below doesn't wait uselessly.
+ ArrayList> writesToFlush = new ArrayList<>(pendingWrites.values());
+
+ try {
+ ApiFutures.allAsList(writesToFlush).get(FLUSH_WAIT_TIMEOUT_SECONDS, TimeUnit.SECONDS);
+ } catch (InterruptedException | ExecutionException | TimeoutException e) {
+ throw new VerifyException(e);
+ }
+ }
+
+ /**
+ * Formats trace following resource name template if the resource metadata has project id.
+ *
+ * @param traceId A trace id string or {@code null} if trace info is missing.
+ * @param resource A {@see MonitoredResource} describing environment metadata.
+ * @return A formatted trace id string.
+ */
+ private String getFormattedTrace(String traceId, MonitoredResource resource) {
+ if (traceId == null) {
+ return null;
+ }
+ String projectId = null;
+ if (resource != null) {
+ projectId = resource.getLabels().getOrDefault(MonitoredResourceUtil.PORJECTID_LABEL, null);
+ }
+ if (projectId != null) {
+ return String.format(RESOURCE_NAME_FORMAT, projectId, traceId);
+ }
+ return traceId;
+ }
+
+ /*
+ * Write logs synchronously or asynchronously based on writeSynchronicity
+ * setting.
+ */
+ private void writeLogEntries(Iterable logEntries, WriteOption... writeOptions) {
+ if (closed) {
+ return;
+ }
+
+ switch (this.writeSynchronicity) {
+ case SYNC:
+ get(writeAsync(logEntries, writeOptions));
+ break;
+
+ case ASYNC:
+ final ApiFuture writeFuture = writeAsync(logEntries, writeOptions);
+ final Object pendingKey = new Object();
+ pendingWrites.put(pendingKey, writeFuture);
+ ApiFutures.addCallback(
+ writeFuture,
+ new ApiFutureCallback() {
+ private void removeFromPending() {
+ pendingWrites.remove(pendingKey);
+ }
+
+ @Override
+ public void onSuccess(Void v) {
+ removeFromPending();
+ }
+
+ @Override
+ public void onFailure(Throwable t) {
+ try {
+ Exception ex = t instanceof Exception ? (Exception) t : new Exception(t);
+ System.err.println("ERROR: onFailure exception: " + ex);
+ } finally {
+ removeFromPending();
+ }
+ }
+ },
+ MoreExecutors.directExecutor());
+ break;
+ }
+ }
+
+ private ApiFuture writeAsync(Iterable logEntries, WriteOption... options) {
+ return transform(
+ rpc.write(writeLogEntriesRequest(getOptions(), logEntries, optionMap(options))),
+ WRITE_RESPONSE_TO_VOID_FUNCTION);
+ }
+
+ static ListLogEntriesRequest listLogEntriesRequest(
+ String projectId, Map options) {
+ ListLogEntriesRequest.Builder builder = ListLogEntriesRequest.newBuilder();
+ builder.addResourceNames("projects/" + projectId);
+ String organization = EntryListOption.OptionType.ORGANIZATION.get(options);
+ if (organization != null) {
+ builder.addResourceNames("organizations/" + organization);
+ }
+ String billingAccount = EntryListOption.OptionType.BILLINGACCOUNT.get(options);
+ if (billingAccount != null) {
+ builder.addResourceNames("billingAccounts/" + billingAccount);
+ }
+ String folder = EntryListOption.OptionType.FOLDER.get(options);
+ if (folder != null) {
+ builder.addResourceNames("folders/" + folder);
+ }
+ Integer pageSize = PAGE_SIZE.get(options);
+ if (pageSize != null) {
+ builder.setPageSize(pageSize);
+ }
+ String pageToken = PAGE_TOKEN.get(options);
+ if (pageToken != null) {
+ builder.setPageToken(pageToken);
+ }
+ String orderBy = ORDER_BY.get(options);
+ if (orderBy != null) {
+ builder.setOrderBy(orderBy);
+ }
+ String filter = generateFilter(EntryListOption.OptionType.FILTER.get(options));
+ if (filter != null) {
+ builder.setFilter(filter);
+ }
+ return builder.build();
+ }
+
+ private static ApiFuture> listLogEntriesAsync(
+ final LoggingOptions serviceOptions, final Map options) {
+ // Make sure to set a filter option which later can be reused in subsequent calls
+ final Map updatedOptions = updateFilter(options);
+ final ListLogEntriesRequest request =
+ listLogEntriesRequest(serviceOptions.getProjectId(), updatedOptions);
+ ApiFuture list = serviceOptions.getLoggingRpcV2().list(request);
+ return transform(
+ list,
+ new Function>() {
+ @Override
+ public AsyncPage apply(ListLogEntriesResponse listLogEntriesResponse) {
+ List entries =
+ listLogEntriesResponse.getEntriesList().isEmpty()
+ ? ImmutableList.of()
+ : Lists.transform(
+ listLogEntriesResponse.getEntriesList(), LogEntry.FROM_PB_FUNCTION);
+ String cursor =
+ listLogEntriesResponse.getNextPageToken().isEmpty()
+ ? null
+ : listLogEntriesResponse.getNextPageToken();
+ return new AsyncPageImpl<>(
+ new LogEntryPageFetcher(serviceOptions, cursor, updatedOptions), cursor, entries);
+ }
+ });
+ }
+
+ @Override
+ public ApiFuture> listLogEntriesAsync(EntryListOption... options) {
+ return listLogEntriesAsync(getOptions(), optionMap(options));
+ }
+
+ @Override
+ public Page listLogEntries(EntryListOption... options) {
+ return get(listLogEntriesAsync(options));
+ }
+
+ static TailLogEntriesRequest buildTailLogEntriesRequest(
+ Map options, String defaultProjectId) {
+ TailLogEntriesRequest.Builder builder = TailLogEntriesRequest.newBuilder();
+
+ String organization = TailOption.OptionType.ORGANIZATION.get(options);
+ if (organization != null) {
+ builder.addResourceNames("organizations/" + organization);
+ }
+ String billingAccount = TailOption.OptionType.BILLINGACCOUNT.get(options);
+ if (billingAccount != null) {
+ builder.addResourceNames("billingAccounts/" + billingAccount);
+ }
+ String folder = TailOption.OptionType.FOLDER.get(options);
+ if (folder != null) {
+ builder.addResourceNames("folders/" + folder);
+ }
+ String project = TailOption.OptionType.PROJECT.get(options);
+ if (project != null) {
+ builder.addResourceNames("projects/" + project);
+ } else if (defaultProjectId != null) {
+ builder.addResourceNames("projects/" + defaultProjectId);
+ }
+ String filter = TailOption.OptionType.FILTER.get(options);
+ if (filter != null) {
+ builder.setFilter(filter);
+ }
+ String bufferWindow = TailOption.OptionType.BUFFERWINDOW.get(options);
+ if (bufferWindow != null) {
+ try {
+ builder.setBufferWindow(Durations.parse(bufferWindow));
+ } catch (ParseException err) {
+ System.err.println("ERROR: invalid duration format: " + bufferWindow);
+ }
+ }
+ return builder.build();
+ }
+
+ @Override
+ public LogEntryServerStream tailLogEntries(TailOption... options) {
+ LoggingOptions serviceOptions = getOptions();
+ BidiStream bidiStream =
+ serviceOptions.getLoggingRpcV2().getTailLogEntriesStream();
+ final TailLogEntriesRequest request =
+ buildTailLogEntriesRequest(optionMap(options), serviceOptions.getProjectId());
+ bidiStream.send(request);
+ return new LogEntryServerStream(bidiStream);
+ }
+
+ @Override
+ public void close() throws Exception {
+ if (closed) {
+ return;
+ }
+ closed = true;
+ flush();
+ rpc.close();
+ }
+
+ static Map optionMap(Option... options) {
+ Map optionMap = Maps.newHashMap();
+ for (Option option : options) {
+ Object prev = optionMap.put(option.getOptionType(), option.getValue());
+ checkArgument(prev == null, "Duplicate option %s", option);
+ }
+ return optionMap;
+ }
+
+ static Map updateFilter(final Map options) {
+ // We should see if filter provided in otiopns have a timestamp parameter
+ // and if not, it should be added with further update of options map.
+ String existingFilter = EntryListOption.OptionType.FILTER.get(options);
+ String newFilter = generateFilter(existingFilter);
+ if (newFilter.equals(existingFilter)) {
+ return options;
+ }
+ // Update
+ Map optionsCopy = Maps.newHashMap(options);
+ optionsCopy.put(EntryListOption.OptionType.FILTER, newFilter);
+ return optionsCopy;
+ }
+
+ static String generateFilter(String filter) {
+ String newFilter = filter;
+ // Make sure timestamp filter is either explicitly specified or we add a default
+ // time filter of 24 hours back to be inline with gcloud behavior for the same API
+ if (newFilter != null) {
+ if (!Ascii.toLowerCase(filter).contains("timestamp")) {
+ newFilter =
+ String.format(
+ "%s AND %s",
+ newFilter, defaultTimestampFilterCreator.createDefaultTimestampFilter());
+ }
+ } else {
+ newFilter = defaultTimestampFilterCreator.createDefaultTimestampFilter();
+ }
+ return newFilter;
+ }
+
+ @VisibleForTesting
+ int getNumPendingWrites() {
+ return pendingWrites.size();
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingLevel.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingLevel.java
new file mode 100644
index 000000000000..23c5d19d8d53
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingLevel.java
@@ -0,0 +1,93 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import java.util.logging.Level;
+
+/**
+ * This class adds some additional Java logging levels for Cloud Logging. Added levels fill in the
+ * gap between Java logging levels and Cloud Logging severities.
+ *
+ * Added levels in descending order are (between parenthesis the relation with Java logging
+ * levels):
+ *
+ *
+ * - EMERGENCY
+ *
- ALERT
+ *
- CRITICAL
+ *
- ERROR ({@code WARNING < ERROR < SEVERE})
+ *
- NOTICE ({@code INFO < NOTICE < WARNING})
+ *
- DEBUG ({@code ALL < DEBUG < FINES}T
+ *
+ *
+ * Notice that {@code ERROR} is lower than {@link java.util.logging.Level#SEVERE} but higher than
+ * {@link java.util.logging.Level#WARNING}. {@code DEBUG} instead is lower than {@link
+ * java.util.logging.Level#FINEST} but higher than {@link java.util.logging.Level#ALL}.
+ */
+@SuppressWarnings("ShouldNotSubclass")
+public final class LoggingLevel extends Level {
+
+ private static final long serialVersionUID = -6455416241709366337L;
+
+ /**
+ * A level to be used for debug or trace information. This level is initialized to {@code 250}.
+ */
+ public static final LoggingLevel DEBUG = new LoggingLevel("DEBUG", 250, Severity.DEBUG);
+
+ /**
+ * A level to be used when normal events occur, such as start up and shut down. This level is
+ * initialized to {@code 850}.
+ */
+ public static final LoggingLevel NOTICE = new LoggingLevel("NOTICE", 850, Severity.NOTICE);
+
+ /**
+ * A level to be used when events occur that are likely to cause problems. This level is
+ * initialized to {@code 950}.
+ */
+ public static final LoggingLevel ERROR = new LoggingLevel("ERROR", 950, Severity.ERROR);
+
+ /**
+ * A level to be used when critical events cause more severe problems or brief outages. This level
+ * is initialized to {@code 1050}.
+ */
+ public static final LoggingLevel CRITICAL = new LoggingLevel("CRITICAL", 1050, Severity.CRITICAL);
+
+ /**
+ * A level to be used when a person must take an action immediately. This level is initialized to
+ * {@code 1100}.
+ */
+ public static final LoggingLevel ALERT = new LoggingLevel("ALERT", 1100, Severity.ALERT);
+
+ /**
+ * A levet to be used when one or more systems are unusable. This level is initialized to {@code
+ * 1150}.
+ */
+ public static final LoggingLevel EMERGENCY =
+ new LoggingLevel("EMERGENCY", 1150, Severity.EMERGENCY);
+
+ private final Severity severity;
+
+ private LoggingLevel(String name, int value, Severity severity) {
+ super(name, value);
+ this.severity = severity;
+ }
+
+ /** Returns the Cloud Logging severity associated with this logging level. */
+ public Severity getSeverity() {
+ return severity;
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingOptions.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingOptions.java
new file mode 100644
index 000000000000..690f9312494f
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingOptions.java
@@ -0,0 +1,183 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.api.core.InternalApi;
+import com.google.api.gax.batching.BatchingSettings;
+import com.google.cloud.ServiceDefaults;
+import com.google.cloud.ServiceOptions;
+import com.google.cloud.ServiceRpc;
+import com.google.cloud.TransportOptions;
+import com.google.cloud.grpc.GrpcTransportOptions;
+import com.google.cloud.logging.spi.LoggingRpcFactory;
+import com.google.cloud.logging.spi.v2.GrpcLoggingRpc;
+import com.google.cloud.logging.spi.v2.LoggingRpc;
+import com.google.cloud.logging.v2.LoggingSettings;
+import com.google.common.collect.ImmutableSet;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import java.io.IOException;
+import java.util.Set;
+
+public class LoggingOptions extends ServiceOptions {
+
+ private static final String API_SHORT_NAME = "Logging";
+ private static final String LOGGING_SCOPE = "https://www.googleapis.com/auth/logging.admin";
+ private static final ImmutableSet SCOPES = ImmutableSet.of(LOGGING_SCOPE);
+ private static final String DEFAULT_HOST = LoggingSettings.getDefaultEndpoint();
+ private static final long serialVersionUID = 5753499510627426717L;
+
+ private Boolean autoPopulateMetadataOnWrite = null;
+ private BatchingSettings batchingSettings = null;
+
+ public static class DefaultLoggingFactory implements LoggingFactory {
+ private static final LoggingFactory INSTANCE = new DefaultLoggingFactory();
+
+ @Override
+ public Logging create(LoggingOptions options) {
+ return new LoggingImpl(options);
+ }
+ }
+
+ /** Returns a default {@code LoggingOptions} instance. */
+ public static LoggingOptions getDefaultInstance() {
+ return newBuilder().build();
+ }
+
+ public static class DefaultLoggingRpcFactory implements LoggingRpcFactory {
+ private static final LoggingRpcFactory INSTANCE = new DefaultLoggingRpcFactory();
+
+ @Override
+ public ServiceRpc create(LoggingOptions options) {
+ try {
+ return new GrpcLoggingRpc(options);
+ } catch (IOException e) {
+ throw new LoggingException(e, true);
+ }
+ }
+ }
+
+ @Override
+ protected String getDefaultHost() {
+ return DEFAULT_HOST;
+ }
+
+ public static class Builder extends ServiceOptions.Builder {
+
+ private Boolean autoPopulateMetadataOnWrite = true;
+ private BatchingSettings batchingSettings = null;
+
+ private Builder() {}
+
+ private Builder(LoggingOptions options) {
+ super(options);
+ }
+
+ @Override
+ public Builder setTransportOptions(TransportOptions transportOptions) {
+ if (!(transportOptions instanceof GrpcTransportOptions)) {
+ throw new IllegalArgumentException(
+ "Only grpc transport is allowed for " + API_SHORT_NAME + ".");
+ }
+ return super.setTransportOptions(transportOptions);
+ }
+
+ @CanIgnoreReturnValue
+ public Builder setAutoPopulateMetadata(boolean autoPopulateMetadataOnWrite) {
+ this.autoPopulateMetadataOnWrite = autoPopulateMetadataOnWrite;
+ return this;
+ }
+
+ @CanIgnoreReturnValue
+ public Builder setBatchingSettings(BatchingSettings batchingSettings) {
+ this.batchingSettings = batchingSettings;
+ return this;
+ }
+
+ @Override
+ public LoggingOptions build() {
+ return new LoggingOptions(this);
+ }
+ }
+
+ @InternalApi("This class should only be extended within google-cloud-java")
+ protected LoggingOptions(Builder builder) {
+ super(LoggingFactory.class, LoggingRpcFactory.class, builder, new LoggingDefaults());
+ this.autoPopulateMetadataOnWrite = builder.autoPopulateMetadataOnWrite;
+ this.batchingSettings =
+ builder.batchingSettings == null ? null : builder.batchingSettings.toBuilder().build();
+ }
+
+ @SuppressWarnings("serial")
+ private static class LoggingDefaults implements ServiceDefaults {
+
+ @Override
+ public LoggingFactory getDefaultServiceFactory() {
+ return DefaultLoggingFactory.INSTANCE;
+ }
+
+ @Override
+ public LoggingRpcFactory getDefaultRpcFactory() {
+ return DefaultLoggingRpcFactory.INSTANCE;
+ }
+
+ @Override
+ public TransportOptions getDefaultTransportOptions() {
+ return getDefaultGrpcTransportOptions();
+ }
+ }
+
+ public static GrpcTransportOptions getDefaultGrpcTransportOptions() {
+ return GrpcTransportOptions.newBuilder().build();
+ }
+
+ @Override
+ protected Set getScopes() {
+ return SCOPES;
+ }
+
+ protected LoggingRpc getLoggingRpcV2() {
+ return (LoggingRpc) getRpc();
+ }
+
+ public Boolean getAutoPopulateMetadata() {
+ return this.autoPopulateMetadataOnWrite;
+ }
+
+ public BatchingSettings getBatchingSettings() {
+ return this.batchingSettings;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ return obj instanceof LoggingOptions && baseEquals((LoggingOptions) obj);
+ }
+
+ @Override
+ public int hashCode() {
+ return baseHashCode();
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public Builder toBuilder() {
+ return new Builder(this);
+ }
+
+ public static Builder newBuilder() {
+ return new Builder();
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MetadataLoader.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MetadataLoader.java
new file mode 100644
index 000000000000..0841fa2e2f44
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MetadataLoader.java
@@ -0,0 +1,233 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.google.cloud.logging.MonitoredResourceUtil.Label;
+import com.google.common.collect.ImmutableMap;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.util.function.Supplier;
+
+public final class MetadataLoader {
+ public static final String ENV_FLEXIBLE = "flex";
+ public static final String ENV_STANDARD = "standard";
+
+ private final ResourceTypeEnvironmentGetter getter;
+
+ private final ImmutableMap> labelResolvers =
+ ImmutableMap.>builder()
+ .put(Label.ClusterName, this::getClusterName)
+ .put(Label.ConfigurationName, this::getConfigName)
+ .put(Label.ContainerName, this::getContainerName)
+ .put(Label.Env, this::getEnv)
+ .put(Label.FunctionName, this::getFunctionName)
+ .put(Label.InstanceId, this::getInstanceId)
+ .put(Label.InstanceName, this::getInstanceName)
+ .put(Label.CloudRunJobName, this::getCloudRunJobName)
+ .put(Label.CloudRunJobExecutionName, this::getCloudRunJobExecutionName)
+ .put(Label.CloudRunJobTaskIndex, this::getCloudRunJobTaskIndex)
+ .put(Label.CloudRunJobTaskAttempt, this::getCloudRunJobTaskAttempt)
+ .put(Label.CloudRunLocation, this::getCloudRunLocation)
+ .put(Label.GKELocation, this::getGKELocation)
+ .put(Label.ModuleId, this::getModuleId)
+ .put(Label.NamespaceName, this::getNamespaceName)
+ .put(Label.PodName, this::getPodName)
+ .put(Label.ProjectId, this::getProjectId)
+ .put(Label.Region, this::getRegion)
+ .put(Label.RevisionName, this::getRevisionName)
+ .put(Label.ServiceName, this::getServiceName)
+ .put(Label.VersionId, this::getVersionId)
+ .put(Label.Zone, this::getZone)
+ .buildOrThrow();
+
+ public MetadataLoader(ResourceTypeEnvironmentGetter getter) {
+ this.getter = getter;
+ }
+
+ /**
+ * Loads metadata value for the {@code label} argument.
+ *
+ * @param label A resource metadata label of type {@see MonitoredResourceUtil.Label}
+ * @return A string with metadata value or {@code null} if the label is not supported.
+ */
+ public String getValue(MonitoredResourceUtil.Label label) {
+ Supplier lambda = labelResolvers.get(label);
+ if (lambda != null) {
+ return lambda.get();
+ }
+ return null;
+ }
+
+ private String getClusterName() {
+ return getter.getAttribute("instance/attributes/cluster-name");
+ }
+
+ private String getConfigName() {
+ return getter.getEnv("K_CONFIGURATION");
+ }
+
+ // due to lack of options to discover container name from within process
+ // allow users to provide the container name via environment variable
+ private String getContainerName() {
+ return getter.getEnv("CONTAINER_NAME");
+ }
+
+ /**
+ * Distinguish between Standard and Flexible GAE environments. There is no indicator of the
+ * environment. The path to the startup-script in the metadata attribute was selected as one of
+ * the new values that explicitly mentioning "flex" and cannot be altered by user (e.g.
+ * environment variable). The method assumes that the resource type is already identified as
+ * {@link Resource.AppEngine}.
+ *
+ * @return {@link MetadataLoader.ENV_FLEXIBLE} for the Flexible environment and {@link
+ * MetadataLoader.ENV_STANDARD} for the Standard environment.
+ */
+ private String getEnv() {
+ String value = getter.getAttribute("instance/attributes/startup-script");
+ if ("/var/lib/flex/startup_script.sh".equals(value)) {
+ return ENV_FLEXIBLE;
+ }
+ return ENV_STANDARD;
+ }
+
+ private String getFunctionName() {
+ String value = getter.getEnv("K_SERVICE");
+ if (value == null) {
+ // keep supporting custom function name if is not provided by default
+ // for backward compatibility only; reconsider removing it after Gen2
+ // environment is enrolled for Cloud Function
+ value = getter.getEnv("FUNCTION_NAME");
+ }
+ return value;
+ }
+
+ private String getInstanceId() {
+ return getter.getAttribute("instance/id");
+ }
+
+ private String getInstanceName() {
+ return getter.getAttribute("instance/name");
+ }
+
+ private String getCloudRunJobName() {
+ return getter.getEnv("CLOUD_RUN_JOB");
+ }
+
+ private String getCloudRunJobExecutionName() {
+ return getter.getEnv("CLOUD_RUN_EXECUTION");
+ }
+
+ private String getCloudRunJobTaskIndex() {
+ return getter.getEnv("CLOUD_RUN_TASK_INDEX");
+ }
+
+ private String getCloudRunJobTaskAttempt() {
+ return getter.getEnv("CLOUD_RUN_TASK_ATTEMPT");
+ }
+
+ private String getCloudRunLocation() {
+ return getRegion();
+ }
+
+ private String getGKELocation() {
+ return getZone();
+ }
+
+ private String getModuleId() {
+ return getter.getEnv("GAE_SERVICE");
+ }
+
+ /**
+ * Heuristic to discover the namespace name of the current environment. There is no deterministic
+ * way to discover the namespace name of the process. The name is read from the {@link
+ * K8S_POD_NAMESPACE_PATH} when available or read from a user defined environment variable
+ * "NAMESPACE_NAME"
+ *
+ * @return Namespace string or null if the name could not be discovered
+ */
+ private String getNamespaceName() {
+ String value = null;
+ try {
+ value =
+ new String(
+ Files.readAllBytes(
+ Paths.get("/var/run/secrets/kubernetes.io/serviceaccount/namespace")),
+ UTF_8);
+ } catch (IOException e) {
+ // if SA token is not shared the info about namespace is unavailable
+ // allow users to define the namespace name explicitly
+ value = getter.getEnv("NAMESPACE_NAME");
+ }
+ return value;
+ }
+
+ // Kubernetes set hostname of the pod to the pod name by default, however hostname can be override
+ // in manifest
+ // allow users to provide the container name via environment variable
+ private String getPodName() {
+ String value = getter.getEnv("POD_NAME");
+ if (value != null) {
+ return value;
+ }
+ return getter.getEnv("HOSTNAME");
+ }
+
+ private String getProjectId() {
+ return getter.getAttribute("project/project-id");
+ }
+
+ /**
+ * Retrieves a region from the qualified region of 'projects/[PROJECT_NUMBER]/regions/[REGION]'
+ *
+ * @return region string id
+ */
+ private String getRegion() {
+ String loc = getter.getAttribute("instance/region");
+ if (loc != null) {
+ return loc.substring(loc.lastIndexOf('/') + 1);
+ }
+ return null;
+ }
+
+ private String getRevisionName() {
+ return getter.getEnv("K_REVISION");
+ }
+
+ private String getServiceName() {
+ return getter.getEnv("K_SERVICE");
+ }
+
+ private String getVersionId() {
+ return getter.getEnv("GAE_VERSION");
+ }
+
+ /**
+ * Retrieves a zone from the qualified zone of 'projects/[PROJECT_NUMBER]/zones/[ZONE]'
+ *
+ * @return zone string id
+ */
+ private String getZone() {
+ String loc = getter.getAttribute("instance/zone");
+ if (loc != null) {
+ return loc.substring(loc.lastIndexOf('/') + 1);
+ }
+ return null;
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
new file mode 100644
index 000000000000..5ce4fc3d182f
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/Metric.java
@@ -0,0 +1,260 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.api.core.ApiFuture;
+import com.google.common.base.Function;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.logging.v2.LogMetric;
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.util.Objects;
+
+/**
+ * Cloud Logging metrics describe logs-based metric. The value of the metric is the number of log
+ * entries that match a logs filter (see {@link #getFilter()}).
+ *
+ * {@code Metric} adds a layer of service-related functionality over {@link MetricInfo}. Objects
+ * of this class are immutable. To get a {@code Metric} object with the most recent information use
+ * {@link #reload} or {@link #reloadAsync}.
+ *
+ * @see Logs-based Metrics
+ *
+ */
+public class Metric extends MetricInfo {
+
+ private static final long serialVersionUID = -1549310461066853001L;
+
+ private final LoggingOptions options;
+ private transient Logging logging;
+
+ /** A builder for {@code Metric} objects. */
+ public static final class Builder extends MetricInfo.Builder {
+
+ private final Logging logging;
+ private final BuilderImpl delegate;
+
+ private Builder(Metric metric) {
+ logging = metric.logging;
+ delegate = new BuilderImpl(metric);
+ }
+
+ @Override
+ @CanIgnoreReturnValue
+ public Builder setName(String name) {
+ delegate.setName(name);
+ return this;
+ }
+
+ @Override
+ @CanIgnoreReturnValue
+ public Builder setDescription(String description) {
+ delegate.setDescription(description);
+ return this;
+ }
+
+ @Override
+ @CanIgnoreReturnValue
+ public Builder setFilter(String filter) {
+ delegate.setFilter(filter);
+ return this;
+ }
+
+ @Override
+ public Metric build() {
+ return new Metric(this.logging, this.delegate);
+ }
+ }
+
+ Metric(Logging logging, BuilderImpl builder) {
+ super(builder);
+ this.logging = checkNotNull(logging);
+ options = logging.getOptions();
+ }
+
+ @Override
+ public Builder toBuilder() {
+ return new Builder(this);
+ }
+
+ @Override
+ public final int hashCode() {
+ return Objects.hash(options, super.hashCode());
+ }
+
+ @Override
+ public final boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+ if (!(obj instanceof Metric)) {
+ return false;
+ }
+ Metric other = (Metric) obj;
+ return baseEquals(other) && Objects.equals(options, other.options);
+ }
+
+ /** Returns the metrics's {@code Logging} object used to issue requests. */
+ public Logging getLogging() {
+ return logging;
+ }
+
+ /**
+ * Deletes this metric.
+ *
+ *
Example of deleting the metric.
+ *
+ *
{@code
+ * boolean deleted = metric.delete();
+ * if (deleted) {
+ * // the metric was deleted
+ * } else {
+ * // the metric was not found
+ * }
+ * }
+ *
+ * @return {@code true} if the metric was deleted, {@code false} if it was not found
+ * @throws LoggingException upon failure
+ */
+ public boolean delete() {
+ return logging.deleteMetric(getName());
+ }
+
+ /**
+ * Sends a request for deleting this metric. This method returns a {@code ApiFuture} object to
+ * consume the result. {@link ApiFuture#get()} returns {@code true} if the metric was deleted,
+ * {@code false} if it was not found.
+ *
+ * Example of asynchronously deleting the metric.
+ *
+ *
{@code
+ * ApiFuture future = metric.deleteAsync();
+ * // ...
+ * boolean deleted = future.get();
+ * if (deleted) {
+ * // the metric was deleted
+ * } else {
+ * // the metric was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ public ApiFuture deleteAsync() {
+ return logging.deleteMetricAsync(getName());
+ }
+
+ /**
+ * Fetches current metric's latest information. Returns {@code null} if the metric does not exist.
+ *
+ * Example of getting the metric's latest information.
+ *
+ *
{@code
+ * Metric latestMetric = metric.reload();
+ * if (latestMetric == null) {
+ * // the metric was not found
+ * }
+ * }
+ *
+ * @return a {@code Metric} object with latest information or {@code null} if not found
+ * @throws LoggingException upon failure
+ */
+ public Metric reload() {
+ return logging.getMetric(getName());
+ }
+
+ /**
+ * Sends a request to fetch current metric's latest information. This method returns a {@code
+ * ApiFuture} object to consume the result. {@link ApiFuture#get()} returns a {@code Metric}
+ * object with latest information or {@code null} if not found.
+ *
+ * Example of asynchronously getting the metric's latest information.
+ *
+ *
{@code
+ * ApiFuture future = metric.reloadAsync();
+ * // ...
+ * Metric latestMetric = future.get();
+ * if (latestMetric == null) {
+ * // the metric was not found
+ * }
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ public ApiFuture reloadAsync() {
+ return logging.getMetricAsync(getName());
+ }
+
+ /**
+ * Updates current metric. If the metric does not exist, it is created.
+ *
+ * Example of updating the metric's information.
+ *
+ *
{@code
+ * Metric updatedMetric = metric.toBuilder()
+ * .setDescription("A more detailed description")
+ * .build()
+ * .update();
+ * }
+ *
+ * @return a {@code Metric} object with updated information
+ * @throws LoggingException upon failure
+ */
+ public Metric update() {
+ return logging.update(this);
+ }
+
+ /**
+ * Sends a request to update current metric. If the metric does not exist, it is created. This
+ * method returns a {@code ApiFuture} object to consume the result. {@link ApiFuture#get()}
+ * returns a {@code Metric} object with updated information.
+ *
+ * Example of asynchronously updating the metric's information.
+ *
+ *
{@code
+ * ApiFuture future = metric.toBuilder()
+ * .setDescription("A more detailed description")
+ * .build()
+ * .updateAsync();
+ * // ...
+ * Metric updatedMetric = future.get();
+ * }
+ *
+ * @throws LoggingException upon failure
+ */
+ public ApiFuture updateAsync() {
+ return logging.updateAsync(this);
+ }
+
+ private void readObject(ObjectInputStream input) throws IOException, ClassNotFoundException {
+ input.defaultReadObject();
+ this.logging = options.getService();
+ }
+
+ static Metric fromPb(Logging logging, LogMetric metricPb) {
+ MetricInfo metricInfo = MetricInfo.fromPb(metricPb);
+ return new Metric(logging, new BuilderImpl(metricInfo));
+ }
+
+ static Function fromPbFunction(final Logging logging) {
+ return (LogMetric metricPb) -> {
+ return metricPb != null ? fromPb(logging, metricPb) : null;
+ };
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MetricInfo.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MetricInfo.java
new file mode 100644
index 000000000000..0ab8d5d0d98e
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MetricInfo.java
@@ -0,0 +1,213 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.base.MoreObjects;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.logging.v2.LogMetric;
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * Cloud Logging metrics describe logs-based metric. The value of the metric is the number of log
+ * entries that match a logs filter (see {@link #getFilter()}).
+ *
+ * @see Logs-based Metrics
+ *
+ */
+public class MetricInfo implements Serializable {
+
+ private static final long serialVersionUID = 666208243838820325L;
+
+ private final String name;
+ private final String description;
+ private final String filter;
+
+ /** A builder for {@code MetricInfo} objects. */
+ public abstract static class Builder {
+
+ Builder() {}
+
+ /**
+ * Sets the name of the metric. Example: {@code severe-errors}. Metric identifiers are limited
+ * to 1000 characters and can include only the following characters: {@code A-Z}, {@code a-z},
+ * {@code 0-9}, and the special characters {@code _-.,+!*',()%/\}. The forward-slash character
+ * ({@code /}) denotes a hierarchy of name pieces, and it cannot be the first character of the
+ * name.
+ */
+ public abstract Builder setName(String name);
+
+ /** Sets an optional description for this metric. Used for documentation purpose. */
+ public abstract Builder setDescription(String description);
+
+ /**
+ * Sets an advanced logs filter. The value of the metric is the number of log entries that match
+ * this filter. Example: {@code logName=projects/my-projectid/logs/syslog AND severity>=ERROR}.
+ *
+ * @see Advanced Log
+ * Filters
+ */
+ public abstract Builder setFilter(String filter);
+
+ /** Creates a {@code MetricInfo} object for this builder. */
+ public abstract MetricInfo build();
+ }
+
+ static final class BuilderImpl extends Builder {
+
+ private String name;
+ private String description;
+ private String filter;
+
+ BuilderImpl(String name, String filter) {
+ this.name = name;
+ this.filter = filter;
+ }
+
+ BuilderImpl(MetricInfo metric) {
+ this.name = metric.name;
+ this.description = metric.description;
+ this.filter = metric.filter;
+ }
+
+ @CanIgnoreReturnValue
+ @Override
+ public Builder setName(String name) {
+ this.name = name;
+ return this;
+ }
+
+ @CanIgnoreReturnValue
+ @Override
+ public Builder setDescription(String description) {
+ this.description = description;
+ return this;
+ }
+
+ @CanIgnoreReturnValue
+ @Override
+ public Builder setFilter(String filter) {
+ this.filter = filter;
+ return this;
+ }
+
+ @Override
+ public MetricInfo build() {
+ return new MetricInfo(this);
+ }
+ }
+
+ MetricInfo(BuilderImpl builder) {
+ this.name = checkNotNull(builder.name);
+ this.filter = checkNotNull(builder.filter);
+ this.description = builder.description;
+ }
+
+ /**
+ * Returns the name of the metric. Example: {@code severe-errors}. Metric identifiers are limited
+ * to 1000 characters and can include only the following characters: {@code A-Z}, {@code a-z},
+ * {@code 0-9}, and the special characters {@code _-.,+!*',()%/\}. The forward-slash character
+ * ({@code /}) denotes a hierarchy of name pieces, and it cannot be the first character of the
+ * name.
+ */
+ public String getName() {
+ return name;
+ }
+
+ /** Returns an optional description for this metric. Used for documentation purpose. */
+ public String getDescription() {
+ return description;
+ }
+
+ /**
+ * Returns an advanced logs filter. The value of the metric is the number of log entries that
+ * match this filter. Example: {@code logName=projects/my-projectid/logs/syslog AND
+ * severity>=ERROR}.
+ *
+ * @see Advanced Log
+ * Filters
+ */
+ public String getFilter() {
+ return filter;
+ }
+
+ @Override
+ public String toString() {
+ return MoreObjects.toStringHelper(this)
+ .add("name", name)
+ .add("description", description)
+ .add("filter", filter)
+ .toString();
+ }
+
+ final boolean baseEquals(MetricInfo metricInfo) {
+ return Objects.equals(name, metricInfo.name)
+ && Objects.equals(description, metricInfo.description)
+ && Objects.equals(filter, metricInfo.filter);
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+ if (!(obj instanceof MetricInfo)) {
+ return false;
+ }
+ return baseEquals((MetricInfo) obj);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(name, description, filter);
+ }
+
+ /** Returns a builder for this {@code MetricInfo} object. */
+ public Builder toBuilder() {
+ return new BuilderImpl(this);
+ }
+
+ /**
+ * Returns a builder for {@code MetricInfo} objects given the name of the metric and its filter.
+ */
+ public static Builder newBuilder(String name, String filter) {
+ return new BuilderImpl(name, filter);
+ }
+
+ /** Creates a {@code MetricInfo} object given the name of the metric and its filter. */
+ public static MetricInfo of(String name, String filter) {
+ return new BuilderImpl(name, filter).build();
+ }
+
+ LogMetric toPb() {
+ LogMetric.Builder builder = LogMetric.newBuilder().setName(name).setFilter(filter);
+ if (description != null) {
+ builder.setDescription(description);
+ }
+ return builder.build();
+ }
+
+ static MetricInfo fromPb(LogMetric metricPb) {
+ Builder builder = newBuilder(metricPb.getName(), metricPb.getFilter());
+ if (!metricPb.getDescription().isEmpty()) {
+ builder.setDescription(metricPb.getDescription());
+ }
+ return builder.build();
+ }
+}
diff --git a/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MonitoredResourceUtil.java b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MonitoredResourceUtil.java
new file mode 100644
index 000000000000..eded19e4ced6
--- /dev/null
+++ b/java-logging/google-cloud-logging/src/main/java/com/google/cloud/logging/MonitoredResourceUtil.java
@@ -0,0 +1,272 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.cloud.MonitoredResource;
+import com.google.common.base.Strings;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMultimap;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Monitored resource construction utilities to detect resource type and add labels. Used by logging
+ * framework adapters to configure default resource. See usage in {@link LoggingHandler}.
+ */
+public class MonitoredResourceUtil {
+
+ private static final String APPENGINE_LABEL_PREFIX = "appengine.googleapis.com/";
+ private static final String CLOUD_RUN_JOB_LABEL_PREFIX = "run.googleapis.com/";
+ protected static final String PORJECTID_LABEL = Label.ProjectId.getKey();
+
+ protected enum Label {
+ ClusterName("cluster_name"),
+ ConfigurationName("configuration_name"),
+ ContainerName("container_name"),
+ Env("env"),
+ FunctionName("function_name"),
+ InstanceId("instance_id"),
+ InstanceName("instance_name"),
+ CloudRunJobName("job_name"),
+ CloudRunJobExecutionName("execution_name"),
+ CloudRunJobTaskIndex("task_index"),
+ CloudRunJobTaskAttempt("task_attempt"),
+ CloudRunLocation("location"),
+ GKELocation("location"),
+ ModuleId("module_id"),
+ NamespaceName("namespace_name"),
+ PodName("pod_name"),
+ ProjectId("project_id"),
+ Region("region"),
+ RevisionName("revision_name"),
+ ServiceName("service_name"),
+ VersionId("version_id"),
+ Zone("zone");
+
+ private final String key;
+
+ Label(String key) {
+ this.key = key;
+ }
+
+ String getKey() {
+ return key;
+ }
+ }
+
+ private enum Resource {
+ CLOUD_RUN("cloud_run_revision"),
+ CLOUD_RUN_JOB("cloud_run_job"),
+ CLOUD_FUNCTION("cloud_function"),
+ APP_ENGINE("gae_app"),
+ GCE_INSTANCE("gce_instance"),
+ K8S_CONTAINER("k8s_container"),
+ GLOBAL("global");
+
+ private final String key;
+
+ Resource(String key) {
+ this.key = key;
+ }
+
+ String getKey() {
+ return key;
+ }
+ }
+
+ private static final ImmutableMultimap RESOURCE_TYPE_WITH_LABELS =
+ ImmutableMultimap.builder()
+ .putAll(Resource.CLOUD_FUNCTION.getKey(), Label.FunctionName, Label.Region)
+ .putAll(
+ Resource.CLOUD_RUN.getKey(),
+ Label.RevisionName,
+ Label.ServiceName,
+ Label.CloudRunLocation,
+ Label.ConfigurationName)
+ .putAll(Resource.CLOUD_RUN_JOB.getKey(), Label.CloudRunJobName, Label.CloudRunLocation)
+ .putAll(
+ Resource.APP_ENGINE.getKey(), Label.ModuleId, Label.VersionId, Label.Zone, Label.Env)
+ .putAll(Resource.GCE_INSTANCE.getKey(), Label.InstanceId, Label.Zone)
+ .putAll(
+ Resource.K8S_CONTAINER.getKey(),
+ Label.GKELocation,
+ Label.ClusterName,
+ Label.NamespaceName,
+ Label.PodName,
+ Label.ContainerName)
+ .build();
+
+ private static final Map cachedMonitoredResources = new HashMap<>();
+ private static ResourceTypeEnvironmentGetter getter = new ResourceTypeEnvironmentGetterImpl();
+ private static MetadataLoader metadataLoader = new MetadataLoader(getter);
+
+ private MonitoredResourceUtil() {}
+
+ /**
+ * Method is intended to assist in testing MonitoredResourceUtil class only.
+ *
+ * @param getter A mocked environment getter for simulated test environments.
+ */
+ protected static void setEnvironmentGetter(ResourceTypeEnvironmentGetter getter) {
+ MonitoredResourceUtil.getter = getter;
+ MonitoredResourceUtil.metadataLoader = new MetadataLoader(getter);
+ }
+
+ /**
+ * Build {@link MonitoredResource} based on detected resource type and populate it with labels
+ * following Monitored Resource Types documentation.
+ *
+ * @param projectId A string defining the project id
+ * @param resourceType A custom resource type
+ * @return the created {@link MonitoredResource}
+ * @see Monitored resource Types
+ */
+ public static MonitoredResource getResource(String projectId, String resourceType) {
+ if (projectId == null || projectId.trim().isEmpty()) {
+ projectId = metadataLoader.getValue(Label.ProjectId);
+ }
+
+ MonitoredResource result = cachedMonitoredResources.get(projectId + "/" + resourceType);
+ if (result != null) {
+ return result;
+ }
+
+ if (Strings.isNullOrEmpty(resourceType)) {
+ Resource detectedResourceType = detectResourceType();
+ resourceType = detectedResourceType.getKey();
+ }
+ MonitoredResource.Builder builder =
+ MonitoredResource.newBuilder(resourceType).addLabel(Label.ProjectId.getKey(), projectId);
+
+ for (Label label : RESOURCE_TYPE_WITH_LABELS.get(resourceType)) {
+ String value = metadataLoader.getValue(label);
+ if (value != null) {
+ builder.addLabel(label.getKey(), value);
+ }
+ }
+ result = builder.build();
+ cachedMonitoredResources.put(projectId + "/" + resourceType, result);
+ return result;
+ }
+
+ /**
+ * Detect monitored Resource type using the following heuristic rules based on the environment and
+ * metadata server.
+ */
+ private static Resource detectResourceType() {
+ // expects supported Google Cloud resource to have access to metadata server
+ if (getter.getAttribute("") == null) {
+ return Resource.GLOBAL;
+ }
+
+ if (getter.getEnv("FUNCTION_SIGNATURE_TYPE") != null
+ && getter.getEnv("FUNCTION_TARGET") != null) {
+ return Resource.CLOUD_FUNCTION;
+ }
+ if (getter.getEnv("K_SERVICE") != null
+ && getter.getEnv("K_REVISION") != null
+ && getter.getEnv("K_CONFIGURATION") != null) {
+ return Resource.CLOUD_RUN;
+ }
+ if (getter.getEnv("CLOUD_RUN_JOB") != null
+ && getter.getEnv("CLOUD_RUN_EXECUTION") != null
+ && getter.getEnv("CLOUD_RUN_TASK_INDEX") != null
+ && getter.getEnv("CLOUD_RUN_TASK_ATTEMPT") != null) {
+ return Resource.CLOUD_RUN_JOB;
+ }
+ if (getter.getEnv("GAE_INSTANCE") != null
+ && getter.getEnv("GAE_SERVICE") != null
+ && getter.getEnv("GAE_VERSION") != null) {
+ return Resource.APP_ENGINE;
+ }
+ if (getter.getAttribute("instance/attributes/cluster-name") != null) {
+ return Resource.K8S_CONTAINER;
+ }
+ if (getter.getAttribute("instance/preempted") != null
+ && getter.getAttribute("instance/cpu-platform") != null
+ && getter.getAttribute("instance/attributes/gae_app_bucket") == null) {
+ return Resource.GCE_INSTANCE;
+ }
+ // other Google Cloud resources (e.g. CloudBuild) might be misdetected
+ return Resource.GLOBAL;
+ }
+
+ /**
+ * Returns custom log entry enhancers (if available) for resource type.
+ *
+ * @return custom log entry enhancers
+ */
+ public static List getResourceEnhancers() {
+ Resource resourceType = detectResourceType();
+ return createEnhancers(resourceType);
+ }
+
+ private static List createEnhancers(Resource resourceType) {
+ List enhancers = new ArrayList<>(2);
+ if (resourceType == Resource.APP_ENGINE) {
+ enhancers.add(new TraceLoggingEnhancer(APPENGINE_LABEL_PREFIX));
+ if (MetadataLoader.ENV_FLEXIBLE.equals(metadataLoader.getValue(Label.Env))) {
+ enhancers.add(
+ new LabelLoggingEnhancer(APPENGINE_LABEL_PREFIX, ImmutableList.of(Label.InstanceName)));
+ }
+ } else if (resourceType == Resource.CLOUD_RUN_JOB) {
+ enhancers.add(
+ new LabelLoggingEnhancer(
+ CLOUD_RUN_JOB_LABEL_PREFIX,
+ ImmutableList.of(
+ Label.CloudRunJobExecutionName,
+ Label.CloudRunJobTaskIndex,
+ Label.CloudRunJobTaskAttempt)));
+ }
+ return enhancers;
+ }
+
+ /**
+ * Adds additional resource-based labels to log entries. Labels that can be provided with {@link
+ * MonitoredResource.Builder#addLabel(String, String)} are restricted to a supported set per
+ * resource.
+ *
+ * @see