com.google.apphosting.runtime

Class AppLogsWriter

java.lang.Object

com.google.apphosting.runtime.AppLogsWriter

public class AppLogsWriter
extends Object

AppsLogWriter is responsible for batching application logs for a single request and sending them back to the AppServer via the LogService.Flush API call and the final return from the request RPC.

The current algorithm used to send logs is as follows:

• Log messages are always appended to the current RuntimePb.UPResponse, which is returned back to the AppServer when the request completes.
• The code never allows more than byteCountBeforeFlush bytes of log data to accumulate in the RuntimePb.UPResponse. If adding a new log line would exceed that limit, the current set of logs are removed from it and an asynchronous API call is started to flush the logs before buffering the new line.
• If another flush occurs while a previous flush is still pending, the caller will block synchronously until the previous call completed.
• When the overall request completes, the request will block until any pending flush is completed (RequestManager#waitForPendingAsyncFutures(java.util.Collection>)) and then return the final set of logs in RuntimePb.UPResponse.

This class is also responsible for splitting large log entries into smaller fragments, which is unrelated to the batching mechanism described above but is necessary to prevent the AppServer from truncating individual log entries.

TODO: In the future we may wish to initiate flushes from a scheduled future which would happen in a background thread. In this case, we must pass the ApiProxy.Environment in explicitly so API calls can be made on behalf of the original thread.

Constructor Summary

Constructors

Constructor and Description
AppLogsWriter(MutableUpResponse upResponse, long maxBytesToFlush, int maxLogMessageLength, int maxFlushSeconds) Construct an AppLogsWriter instance.

Method Summary

Modifier and Type	Method and Description
void	addLogRecordAndMaybeFlush(com.google.apphosting.api.ApiProxy.LogRecord fullRecord) Add the specified LogRecord for the current request.
static com.google.apphosting.api.ApiProxy.LogRecord.Level	convertLogLevel(Level level) Converts from a Java Logging level to an App Engine logging level.
void	flushAndWait() Initiates a synchronous flush.
static StackTraceElement	getTopUserStackFrame(List<StackTraceElement> stack) Analyzes a stack trace and returns the topmost frame that contains user code, so as to filter out App Engine logging and servlet infrastructure and just return frames relevant to user code.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AppLogsWriter

public AppLogsWriter(MutableUpResponse upResponse,
                     long maxBytesToFlush,
                     int maxLogMessageLength,
                     int maxFlushSeconds)

Construct an AppLogsWriter instance.

Parameters:

upResponse - The protobuf response instance that holds the return value for EvaluationRuntime.HandleRequest. This is used to return any logs that were not sent to the appserver with an intermediate flush when the request ends.

maxBytesToFlush - The maximum number of bytes of log message to allow in a single flush. The code flushes any cached logs before reaching this limit. If this is 0, AppLogsWriter will not start an intermediate flush based on size.

maxLogMessageLength - The maximum length of an individual log line. A single log line longer than this will be written as multiple log entries (with the continuation prefix/suffixes added to indicate this).

maxFlushSeconds - The amount of time to allow a log line to sit cached before flushing. Once a log line has been sitting for more than the specified time, all currently cached logs are flushed. If this is 0, no time based flushing occurs. N.B. because we only check the time on a log call, it is possible for a log to stay cached long after the specified time has been reached. Consider this example (assume maxFlushSeconds=60): the app logs a message when the handler starts but then does not log another message for 10 minutes. The initial log will stay cached until the second message is logged.

Method Detail

addLogRecordAndMaybeFlush

public void addLogRecordAndMaybeFlush(com.google.apphosting.api.ApiProxy.LogRecord fullRecord)

Add the specified LogRecord for the current request. If enough space (or in the future, time) has accumulated, an asynchronous flush may be started. If flushes are backed up, this method may block.

flushAndWait

public void flushAndWait()

Initiates a synchronous flush. This method will always block until any pending flushes and its own flush completes.

convertLogLevel

public static com.google.apphosting.api.ApiProxy.LogRecord.Level convertLogLevel(Level level)

Converts from a Java Logging level to an App Engine logging level. SEVERE maps to error, WARNING to warn, INFO to info, and all lower levels to debug. We reserve the fatal level for exceptions that propagated outside of user code and forced us to kill the request.

getTopUserStackFrame

public static StackTraceElement getTopUserStackFrame(List<StackTraceElement> stack)

Analyzes a stack trace and returns the topmost frame that contains user code, so as to filter out App Engine logging and servlet infrastructure and just return frames relevant to user code.