Logging (Google Cloud Logging 1.7.0 API)

All Superinterfaces:: AutoCloseable, Service<LoggingOptions>

public interface Logging
extends AutoCloseable, Service<LoggingOptions>

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Logging.EntryListOption` Class for specifying options for listing log entries.
`static class`	`Logging.ListOption` Class for specifying options for listing sinks, monitored resources and monitored resource descriptors.
`static class`	`Logging.SortingField` Fields according to which log entries can be sorted.
`static class`	`Logging.SortingOrder` Sorting orders available when listing log entries.
`static class`	`Logging.WriteOption` Class for specifying options for writing log entries.

Method Summary

Methods
Modifier and Type	Method and Description
`Metric`	`create(MetricInfo metric)` Creates a new metric.
`Sink`	`create(SinkInfo sink)` Creates a new sink.
`com.google.api.core.ApiFuture<Metric>`	`createAsync(MetricInfo metric)` Sends a request for creating a metric.
`com.google.api.core.ApiFuture<Sink>`	`createAsync(SinkInfo sink)` Sends a request for creating a sink.
`boolean`	`deleteLog(String log)` Deletes a log and all its log entries.
`com.google.api.core.ApiFuture<Boolean>`	`deleteLogAsync(String log)` Sends a request for deleting a log and all its log entries.
`boolean`	`deleteMetric(String metric)` Deletes the requested metric.
`com.google.api.core.ApiFuture<Boolean>`	`deleteMetricAsync(String metric)` Sends a request for deleting a metric.
`boolean`	`deleteSink(String sink)` Deletes the requested sink.
`com.google.api.core.ApiFuture<Boolean>`	`deleteSinkAsync(String sink)` Sends a request for deleting a sink.
`void`	`flush()` Flushes any pending asynchronous logging writes.
`Severity`	`getFlushSeverity()`
`Metric`	`getMetric(String metric)` Returns the requested metric or `null` if not found.
`com.google.api.core.ApiFuture<Metric>`	`getMetricAsync(String metric)` Sends a request for getting a metric.
`Sink`	`getSink(String sink)` Returns the requested sink or `null` if not found.
`com.google.api.core.ApiFuture<Sink>`	`getSinkAsync(String sink)` Sends a request for getting a sink.
`Synchronicity`	`getWriteSynchronicity()`
`com.google.api.gax.paging.Page<LogEntry>`	`listLogEntries(Logging.EntryListOption... options)` Lists log entries.
`com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<LogEntry>>`	`listLogEntriesAsync(Logging.EntryListOption... options)` Sends a request for listing log entries.
`com.google.api.gax.paging.Page<Metric>`	`listMetrics(Logging.ListOption... options)` Lists the metrics.
`com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<Metric>>`	`listMetricsAsync(Logging.ListOption... options)` Sends a request for listing metrics.
`com.google.api.gax.paging.Page<MonitoredResourceDescriptor>`	`listMonitoredResourceDescriptors(Logging.ListOption... options)` Lists the monitored resource descriptors used by Stackdriver Logging.
`com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<MonitoredResourceDescriptor>>`	`listMonitoredResourceDescriptorsAsync(Logging.ListOption... options)` Sends a request for listing monitored resource descriptors used by Stackdriver Logging.
`com.google.api.gax.paging.Page<Sink>`	`listSinks(Logging.ListOption... options)` Lists the sinks.
`com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<Sink>>`	`listSinksAsync(Logging.ListOption... options)` Sends a request for listing sinks.
`void`	`setFlushSeverity(Severity flushSeverity)` Sets flush severity for asynchronous logging writes.
`void`	`setWriteSynchronicity(Synchronicity synchronicity)`
`Metric`	`update(MetricInfo metric)` Updates a metric or creates one if it does not exist.
`Sink`	`update(SinkInfo sink)` Updates a sink or creates one if it does not exist.
`com.google.api.core.ApiFuture<Metric>`	`updateAsync(MetricInfo metric)` Sends a request for updating a metric (or creating it, if it does not exist).
`com.google.api.core.ApiFuture<Sink>`	`updateAsync(SinkInfo sink)` Sends a request for updating a sink (or creating it, if it does not exist).
`void`	`write(Iterable<LogEntry> logEntries, Logging.WriteOption... options)` Sends a request to log entries to Stackdriver Logging.

Methods inherited from interface java.lang.AutoCloseable
close

Methods inherited from interface com.google.cloud.Service
getOptions

Method Detail

setWriteSynchronicity

void setWriteSynchronicity(Synchronicity synchronicity)

getWriteSynchronicity
```
Synchronicity getWriteSynchronicity()
```

setFlushSeverity
```
void setFlushSeverity(Severity flushSeverity)
```
Sets flush severity for asynchronous logging writes. Default is ERROR. Logs will be immediately written out for entries at or higher than flush severity.

getFlushSeverity
```
Severity getFlushSeverity()
```

create

Sink create(SinkInfo sink)

Creates a new sink.

Example of creating a sink to export logs to a BigQuery dataset (in the ServiceOptions.getProjectId() project).

 String sinkName = "my_sink_name";
 String datasetName = "my_dataset";
 SinkInfo sinkInfo = SinkInfo.of(sinkName, DatasetDestination.of(datasetName));
 Sink sink = logging.create(sinkInfo);

Returns:: the created sink
Throws:: LoggingException - upon failure

createAsync

com.google.api.core.ApiFuture<Sink> createAsync(SinkInfo sink)

Sends a request for creating a sink. This method returns a ApiFuture object to consume the result. Future.get() returns the created sink.

Example of asynchronously creating a sink to export logs to a BigQuery dataset (in the ServiceOptions.getProjectId() project).

 String sinkName = "my_sink_name";
 String datasetName = "my_dataset";
 SinkInfo sinkInfo = SinkInfo.of(sinkName, DatasetDestination.of(datasetName));
 ApiFuture<Sink> future = logging.createAsync(sinkInfo);
 // ...
 Sink sink = future.get();

update

Sink update(SinkInfo sink)

Updates a sink or creates one if it does not exist.

Example of updating a sink.

 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);

Returns:: the created sink
Throws:: LoggingException - upon failure

updateAsync

com.google.api.core.ApiFuture<Sink> updateAsync(SinkInfo sink)

Sends a request for updating a sink (or creating it, if it does not exist). This method returns a ApiFuture object to consume the result. Future.get() returns the updated/created sink or null if not found.

Example of asynchronously updating a sink.

 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<Sink> future = logging.updateAsync(sinkInfo);
 // ...
 Sink sink = future.get();

getSink

Sink getSink(String sink)

Returns the requested sink or null if not found.

Example of getting a sink.

 String sinkName = "my_sink_name";
 Sink sink = logging.getSink(sinkName);
 if (sink == null) {
   // sink was not found
 }

Throws:: LoggingException - upon failure

getSinkAsync

com.google.api.core.ApiFuture<Sink> getSinkAsync(String sink)

Sends a request for getting a sink. This method returns a ApiFuture object to consume the result. Future.get() returns the requested sink or null if not found.

Example of asynchronously getting a sink.

 String sinkName = "my_sink_name";
 ApiFuture<Sink> future = logging.getSinkAsync(sinkName);
 // ...
 Sink sink = future.get();
 if (sink == null) {
   // sink was not found
 }

Throws:: LoggingException - upon failure

listSinks

com.google.api.gax.paging.Page<Sink> listSinks(Logging.ListOption... options)

Lists the sinks. This method returns a Page object that can be used to consume paginated results. Use Logging.ListOption to specify the page size or the page token from which to start listing sinks.

Example of listing sinks, specifying the page size.

 Page<Sink> sinks = logging.listSinks(ListOption.pageSize(100));
 Iterator<Sink> sinkIterator = sinks.iterateAll();
 while (sinkIterator.hasNext()) {
   Sink sink = sinkIterator.next();
   // do something with the sink
 }

Throws:: LoggingException - upon failure

listSinksAsync

com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<Sink>> listSinksAsync(Logging.ListOption... options)

Sends a request for listing sinks. This method returns a ApiFuture object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use Logging.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.

 ApiFuture<AsyncPage<Sink>> future = logging.listSinksAsync(ListOption.pageSize(100));
 // ...
 AsyncPage<Sink> sinks = future.get();
 Iterator<Sink> sinkIterator = sinks.iterateAll();
 while (sinkIterator.hasNext()) {
   Sink sink = sinkIterator.next();
   // do something with the sink
 }

deleteSink

boolean deleteSink(String sink)

Deletes the requested sink.

Example of deleting a sink.

 String sinkName = "my_sink_name";
 boolean deleted = logging.deleteSink(sinkName);
 if (deleted) {
   // the sink was deleted
 } else {
   // the sink was not found
 }

Returns:: true if the sink was deleted, false if it was not found

deleteSinkAsync

com.google.api.core.ApiFuture<Boolean> deleteSinkAsync(String sink)

Sends a request for deleting a sink. This method returns a ApiFuture object to consume the result. Future.get() returns true if the sink was deleted, false if it was not found.

Example of asynchronously deleting a sink.

 String sinkName = "my_sink_name";
 ApiFuture<Boolean> future = logging.deleteSinkAsync(sinkName);
 // ...
 boolean deleted = future.get();
 if (deleted) {
   // the sink was deleted
 } else {
   // the sink was not found
 }

deleteLog

boolean deleteLog(String log)

Deletes a log and all its log entries. The log will reappear if new entries are written to it.

Example of deleting a log.

 String logName = "my_log_name";
 boolean deleted = logging.deleteLog(logName);
 if (deleted) {
   // the log was deleted
 } else {
   // the log was not found
 }

Returns:: true if the log was deleted, false if it was not found

deleteLogAsync

com.google.api.core.ApiFuture<Boolean> deleteLogAsync(String log)

Sends a request for deleting a log and all its log entries. This method returns a ApiFuture object to consume the result. Future.get() returns true if the log was deleted, false if it was not found.

Example of asynchronously deleting a log.

 String logName = "my_log_name";
 ApiFuture<Boolean> future = logging.deleteLogAsync(logName);
 // ...
 boolean deleted = future.get();
 if (deleted) {
   // the log was deleted
 } else {
   // the log was not found
 }

listMonitoredResourceDescriptors

com.google.api.gax.paging.Page<MonitoredResourceDescriptor> listMonitoredResourceDescriptors(Logging.ListOption... options)

Lists the monitored resource descriptors used by Stackdriver Logging. This method returns a Page object that can be used to consume paginated results. Use Logging.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.

 Page<MonitoredResourceDescriptor> descriptors =
     logging.listMonitoredResourceDescriptors(ListOption.pageSize(100));
 Iterator<MonitoredResourceDescriptor> descriptorIterator = descriptors.iterateAll();
 while (descriptorIterator.hasNext()) {
   MonitoredResourceDescriptor descriptor = descriptorIterator.next();
   // do something with the descriptor
 }

Throws:: LoggingException - upon failure

listMonitoredResourceDescriptorsAsync

com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<MonitoredResourceDescriptor>> listMonitoredResourceDescriptorsAsync(Logging.ListOption... options)

Sends a request for listing monitored resource descriptors used by Stackdriver Logging. This method returns a ApiFuture object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use Logging.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.

 ApiFuture<AsyncPage<MonitoredResourceDescriptor>> future =
     logging.listMonitoredResourceDescriptorsAsync(ListOption.pageSize(100));
 // ...
 AsyncPage<MonitoredResourceDescriptor> descriptors = future.get();
 Iterator<MonitoredResourceDescriptor> descriptorIterator = descriptors.iterateAll();
 while (descriptorIterator.hasNext()) {
   MonitoredResourceDescriptor descriptor = descriptorIterator.next();
   // do something with the descriptor
 }

create

Metric create(MetricInfo metric)

Creates a new metric.

Example of creating a metric for logs with severity higher or equal to ERROR.

 String metricName = "my_metric_name";
 MetricInfo metricInfo = MetricInfo.of(metricName, "severity>=ERROR");
 Metric metric = logging.create(metricInfo);

Returns:: the created metric
Throws:: LoggingException - upon failure

createAsync

com.google.api.core.ApiFuture<Metric> createAsync(MetricInfo metric)

Sends a request for creating a metric. This method returns a ApiFuture object to consume the result. Future.get() returns the created metric.

Example of asynchronously creating a metric for logs with severity higher or equal to ERROR.

 String metricName = "my_metric_name";
 MetricInfo metricInfo = MetricInfo.of(metricName, "severity>=ERROR");
 ApiFuture<Metric> future = logging.createAsync(metricInfo);
 // ...
 Metric metric = future.get();

update

Metric update(MetricInfo metric)

Updates a metric or creates one if it does not exist.

Example of updating a metric.

 String metricName = "my_metric_name";
 MetricInfo metricInfo = MetricInfo.newBuilder(metricName, "severity>=ERROR")
     .setDescription("new description")
     .build();
 Metric metric = logging.update(metricInfo);

Returns:: the created metric
Throws:: LoggingException - upon failure

updateAsync

com.google.api.core.ApiFuture<Metric> updateAsync(MetricInfo metric)

Sends a request for updating a metric (or creating it, if it does not exist). This method returns a ApiFuture object to consume the result. Future.get() returns the updated/created metric or null if not found.

Example of asynchronously updating a metric.

 String metricName = "my_metric_name";
 MetricInfo metricInfo = MetricInfo.newBuilder(metricName, "severity>=ERROR")
     .setDescription("new description")
     .build();
 ApiFuture<Metric> future = logging.updateAsync(metricInfo);
 // ...
 Metric metric = future.get();

getMetric

Metric getMetric(String metric)

Returns the requested metric or null if not found.

Example of getting a metric.

 String metricName = "my_metric_name";
 Metric metric = logging.getMetric(metricName);
 if (metric == null) {
   // metric was not found
 }

Throws:: LoggingException - upon failure

getMetricAsync

com.google.api.core.ApiFuture<Metric> getMetricAsync(String metric)

Sends a request for getting a metric. This method returns a ApiFuture object to consume the result. Future.get() returns the requested metric or null if not found.

Example of asynchronously getting a metric.

 String metricName = "my_metric_name";
 ApiFuture<Metric> future = logging.getMetricAsync(metricName);
 // ...
 Metric metric = future.get();
 if (metric == null) {
   // metric was not found
 }

Throws:: LoggingException - upon failure

listMetrics

com.google.api.gax.paging.Page<Metric> listMetrics(Logging.ListOption... options)

Lists the metrics. This method returns a Page object that can be used to consume paginated results. Use Logging.ListOption to specify the page size or the page token from which to start listing metrics.

Example of listing metrics, specifying the page size.

 Page<Metric> metrics = logging.listMetrics(ListOption.pageSize(100));
 Iterator<Metric> metricIterator = metrics.iterateAll();
 while (metricIterator.hasNext()) {
   Metric metric = metricIterator.next();
   // do something with the metric
 }

Throws:: LoggingException - upon failure

listMetricsAsync

com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<Metric>> listMetricsAsync(Logging.ListOption... options)

Sends a request for listing metrics. This method returns a ApiFuture object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use Logging.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.

 ApiFuture<AsyncPage<Metric>> future = logging.listMetricsAsync(ListOption.pageSize(100));
 // ...
 AsyncPage<Metric> metrics = future.get();
 Iterator<Metric> metricIterator = metrics.iterateAll();
 while (metricIterator.hasNext()) {
   Metric metric = metricIterator.next();
   // do something with the metric
 }

deleteMetric

boolean deleteMetric(String metric)

Deletes the requested metric.

Example of deleting a metric.

 String metricName = "my_metric_name";
 boolean deleted = logging.deleteMetric(metricName);
 if (deleted) {
   // the metric was deleted
 } else {
   // the metric was not found
 }

Returns:: true if the metric was deleted, false if it was not found

deleteMetricAsync

com.google.api.core.ApiFuture<Boolean> deleteMetricAsync(String metric)

Sends a request for deleting a metric. This method returns a ApiFuture object to consume the result. Future.get() returns true if the metric was deleted, false if it was not found.

Example of asynchronously deleting a metric.

 String metricName = "my_metric_name";
 ApiFuture<Boolean> future = logging.deleteMetricAsync(metricName);
 // ...
 boolean deleted = future.get();
 if (deleted) {
   // the metric was deleted
 } else {
   // the metric was not found
 }

flush
```
void flush()
```
Flushes any pending asynchronous logging writes. Logs are automatically flushed based on time and message count that be configured via BatchingSettings, Logs are also flushed if at or above flush severity, see setFlushSeverity(com.google.cloud.logging.Severity). Logging frameworks require support for an explicit flush. See usage in the java.util.logging handlerLoggingHandler.

write

void write(Iterable<LogEntry> logEntries,
         Logging.WriteOption... options)

Sends a request to log entries to Stackdriver Logging. Use Logging.WriteOption.logName(String) to provide a log name for those entries that do not specify one. Use Logging.WriteOption.resource(MonitoredResource) to provide a monitored resource for those entries that do not specify one. Use Logging.WriteOption.labels(Map) to provide some labels to be added to every entry in logEntries.

Example of writing log entries and providing a default log name and monitored resource.

 String logName = "my_log_name";
 List<LogEntry> entries = new ArrayList<>();
 entries.add(LogEntry.of(StringPayload.of("Entry payload")));
 Map<String, Object> 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()));

listLogEntries
```
com.google.api.gax.paging.Page<LogEntry> listLogEntries(Logging.EntryListOption... options)
```
Lists log entries. This method returns a Page object that can be used to consume paginated results. Use Logging.EntryListOption.pageSize(int) to specify the page size. Use Logging.EntryListOption.pageToken(String) to specify the page token from which to start listing entries. Use EntryListOption#sortOrder(SortingField, SortingOrder) to sort log entries according to your preferred order (default is most-recent last). Use Logging.EntryListOption.filter(String) to filter listed log entries.
Example of listing log entries for a specific log.
```
 String filter = "logName=projects/my_project_id/logs/my_log_name";
 Page<LogEntry> entries = logging.listLogEntries(EntryListOption.filter(filter));
 Iterator<LogEntry> entryIterator = entries.iterateAll();
 while (entryIterator.hasNext()) {
   LogEntry entry = entryIterator.next();
   // do something with the entry
 }
 
```
Throws:

LoggingException - upon failure

listLogEntriesAsync
```
com.google.api.core.ApiFuture<com.google.api.gax.paging.AsyncPage<LogEntry>> listLogEntriesAsync(Logging.EntryListOption... options)
```
Sends a request for listing log entries. This method returns a ApiFuture object to consume the result. Future.get() returns an AsyncPage object that can be used to asynchronously handle paginated results. Use Logging.EntryListOption.pageSize(int) to specify the page size. Use Logging.EntryListOption.pageToken(String) to specify the page token from which to start listing entries. Use EntryListOption#sortOrder(SortingField, SortingOrder) to sort log entries according to your preferred order (default is most-recent last). Use Logging.EntryListOption.filter(String) to filter listed log entries.
Example of asynchronously listing log entries for a specific log.
```
 String filter = "logName=projects/my_project_id/logs/my_log_name";
 ApiFuture<AsyncPage<LogEntry>> future =
     logging.listLogEntriesAsync(EntryListOption.filter(filter));
 // ...
 AsyncPage<LogEntry> entries = future.get();
 Iterator<LogEntry> entryIterator = entries.iterateAll();
 while (entryIterator.hasNext()) {
   LogEntry entry = entryIterator.next();
   // do something with the entry
 }
 
```
Throws:

LoggingException - upon failure

Interface Logging

Nested Class Summary

Method Summary

Methods inherited from interface java.lang.AutoCloseable

Methods inherited from interface com.google.cloud.Service

Method Detail

setWriteSynchronicity

getWriteSynchronicity

setFlushSeverity

getFlushSeverity

create

createAsync

update

updateAsync

getSink

getSinkAsync

listSinks

listSinksAsync

deleteSink

deleteSinkAsync

deleteLog

deleteLogAsync

listMonitoredResourceDescriptors

listMonitoredResourceDescriptorsAsync

create

createAsync

update

updateAsync

getMetric

getMetricAsync

listMetrics

listMetricsAsync

deleteMetric

deleteMetricAsync

flush

write

listLogEntries

listLogEntriesAsync