Class LogQuery (2.0.0)

public final class LogQuery implements Cloneable, Serializable

Allows users to customize the behavior of LogService#fetch(LogQuery).

startTime is the earliest request completion or last-update time that results should be fetched for, in seconds since the Unix epoch. If null then no requests will be excluded for ending too long ago.

endTime is the latest request completion or last-update time that results should be fetched for, in seconds since the Unix epoch. If null then no requests will be excluded for ending too recently.

offset is a cursor into the log stream retrieved from a previously emitted RequestLogs#getOffset. This iterator will begin returning logs immediately after the record from which the offset came. If null, the query will begin at startTime.

minLogLevel is a LogService.LogLevel which serves as a filter on the requests returned. Requests with no application logs at or above the specified level will be omitted. Works even if includeAppLogs is not True.

includeIncomplete selects whether requests that have started but not yet finished should be included in the query. Defaults to False.

includeAppLogs specifies whether or not to include application logs in the query results. Defaults to False.

majorVersionIds specifies versions of the application's default module for which logs records should retrieved.

versions specifies module versions of the application for which logs should be retrieved.

requestIds, if not empty(), indicates that instead of a time-based scan, logs for the specified requests should be returned. See the Request IDs section of the Java Servlet Environment documentation for how to retrieve these IDs at runtime. Malformed request IDs cause an exception and unrecognized request IDs are ignored. This option may not be combined with other filtering options such as startTime, endTime, offset, or minLogLevel. When requestIds is not empty(), majorVersionIds are ignored. Logs are returned in the order requested.

batchSize specifies the internal batching strategy of the returned Iterable < RequestLogs >. Has no impact on the result of the query.

Notes on usage:
The recommended way to instantiate a LogQuery object is to statically import Builder.* and invoke a static creation method followed by an instance mutator (if needed):


 import static com.google.appengine.api.log.LogQuery.Builder.*;

 ...

 // All requests, including application logs.
 iter = logService.fetch(withIncludeAppLogs(true));

 // All requests ending in the past day (or still running) with an info log or higher.
 Calendar cal = Calendar.getInstance();
 cal.add(Calendar.DAY_OF_MONTH, -1);
 iter = logService.fetch(withEndTimeMillis(cal.time())
     .includeIncomplete(true).minimumLogLevel(LogService.INFO));
 

There are a couple of ways to configure LogQuery to limit LogService#fetch(LogQuery) to only return log records for specific module versions.

  1. #versions(List)(Builder#withVersions(List)) - Includes designated module versions for the application.
  2. #majorVersionIds(List) (Builder#withMajorVersionIds(List)) - Includes designated versions of the default module for the application.
For a particular LogQuery only one of these methods may be used. If neither is used, LogService#fetch(LogQuery) results may include any module version.

It is not allowed to call both #versions(List) (Builder#withVersions(List)) and #requestIds(List)(Builder#withRequestIds(List) for the same LogQuery.

Inheritance

java.lang.Object > LogQuery

Implements

Cloneable, Serializable

Constructors

LogQuery()

public LogQuery()

Methods

batchSize(int batchSize)

public LogQuery batchSize(int batchSize)

Sets the batch size. Please read the class javadoc for an explanation of how batch size is used.

Parameter
Name Description
batchSize int

The batch size to set. Must be greater than 0.

Returns
Type Description
LogQuery

this (for chaining)

clone()

public LogQuery clone()

Makes a copy of a provided LogQuery.

Returns
Type Description
LogQuery

A new LogQuery whose fields are copied from the given LogQuery.

Overrides

endTimeMillis(long endTimeMillis)

public LogQuery endTimeMillis(long endTimeMillis)

Sets the end time to a value in milliseconds. Please read the class javadoc for an explanation of how end time is used.

Parameter
Name Description
endTimeMillis long

The end time to set, in milliseconds.

Returns
Type Description
LogQuery

this (for chaining)

endTimeUsec(long endTimeUsec)

public LogQuery endTimeUsec(long endTimeUsec)

Sets the end time to a value in microseconds. Please read the class javadoc for an explanation of how end time is used.

Parameter
Name Description
endTimeUsec long

The end time to set, in microseconds.

Returns
Type Description
LogQuery

this (for chaining)

getBatchSize()

public @Nullable Integer getBatchSize()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.Integer

The batch size, or null if none was provided.

getEndTimeMillis()

public @Nullable Long getEndTimeMillis()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.Long

The end time in milliseconds, or null if none was provided.

getEndTimeUsec()

public @Nullable Long getEndTimeUsec()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.Long

The end time in microseconds, or null if none was provided.

getIncludeAppLogs()

public Boolean getIncludeAppLogs()
Returns
Type Description
Boolean

Whether or not application logs should be returned.

getIncludeIncomplete()

public Boolean getIncludeIncomplete()
Returns
Type Description
Boolean

Whether or not incomplete request logs should be returned.

getMajorVersionIds()

public List<String> getMajorVersionIds()
Returns
Type Description
List<String>

The list of major app versions that should be queried over, or an empty list if none were set.

getMinLogLevel()

public @Nullable LogService.LogLevel getMinLogLevel()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable com.google.appengine.api.log.LogService.LogLevel

The minimum log level, or null if none was provided.

getOffset()

public @Nullable String getOffset()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.String

The offset, or null if none was provided.

getRequestIds()

public List<String> getRequestIds()
Returns
Type Description
List<String>

The list of request ids that should be queried over, or null if none were set.

getStartTimeMillis()

public @Nullable Long getStartTimeMillis()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.Long

The start time in milliseconds, or null if none was provided.

getStartTimeUsec()

public @Nullable Long getStartTimeUsec()
Returns
Type Description
@org.checkerframework.checker.nullness.qual.Nullable java.lang.Long

The start time in microseconds, or null if none was provided.

getVersions()

public List<LogQuery.Version> getVersions()
Returns
Type Description
List<Version>

The list possibly empty list of module versions that should be queried over.

includeAppLogs(boolean includeAppLogs)

public LogQuery includeAppLogs(boolean includeAppLogs)

Sets include application logs. Please read the class javadoc for an explanation of how include application logs is used.

Parameter
Name Description
includeAppLogs boolean

The value to set.

Returns
Type Description
LogQuery

this (for chaining)

includeIncomplete(boolean includeIncomplete)

public LogQuery includeIncomplete(boolean includeIncomplete)

Sets include incomplete. Please read the class javadoc for an explanation of how include incomplete is used.

Parameter
Name Description
includeIncomplete boolean

The value to set.

Returns
Type Description
LogQuery

this (for chaining)

majorVersionIds(List<String> versionIds)

public LogQuery majorVersionIds(List<String> versionIds)

Sets the major version identifiers to query. Please read the class javadoc for an explanation of how major versions are used.

Parameter
Name Description
versionIds List<String>

The major version identifier list to set.

Returns
Type Description
LogQuery

this (for chaining)

minLogLevel(LogService.LogLevel minLogLevel)

public LogQuery minLogLevel(LogService.LogLevel minLogLevel)

Sets the minimum log level. Please read the class javadoc for an explanation of how minimum log level is used.

Parameter
Name Description
minLogLevel LogService.LogLevel

The minimum log level to set.

Returns
Type Description
LogQuery

this (for chaining)

offset(String offset)

public LogQuery offset(String offset)

Sets the offset. Please read the class javadoc for an explanation of how offset is used.

Parameter
Name Description
offset String

The offset to set.

Returns
Type Description
LogQuery

this (for chaining)

requestIds(List<String> requestIds)

public LogQuery requestIds(List<String> requestIds)

Sets the list of request ids to query. See the class javadoc for an explanation of how request ids are used.

Parameter
Name Description
requestIds List<String>

The request id list to set.

Returns
Type Description
LogQuery

this (for chaining)

startTimeMillis(long startTimeMillis)

public LogQuery startTimeMillis(long startTimeMillis)

Sets the start time to a value in milliseconds. Please read the class javadoc for an explanation of how start time is used.

Parameter
Name Description
startTimeMillis long

The start time to set, in milliseconds.

Returns
Type Description
LogQuery

this (for chaining)

startTimeUsec(long startTimeUsec)

public LogQuery startTimeUsec(long startTimeUsec)

Sets the start time to a value in microseconds. Please read the class javadoc for an explanation of how start time is used.

Parameter
Name Description
startTimeUsec long

The start time to set, in microseconds.

Returns
Type Description
LogQuery

this (for chaining)

versions(List<LogQuery.Version> versions)

public LogQuery versions(List<LogQuery.Version> versions)

Restricts the query to log records for the specified module versions.

Please read the class javadoc for usage information.

Parameter
Name Description
versions List<Version>

The list of module versions to query.

Returns
Type Description
LogQuery

this (for chaining)