google.appengine.api.logservice.logservice module

Summary

LogService API.

This module allows apps to flush logs, provide status messages, and programmatically access their request and application logs.

Contents

class google.appengine.api.logservice.logservice.AppLog(time=None, level=None, message=None, source_location=None)source

Bases: object

Application log line emitted while processing a request.

level

Level or severity of log, as an int.

message

Application-provided log message, as a string.

source_location

Source source_location of the log statement, or None if not supported.

time

Time log entry was made, in seconds since the Unix epoch, as a float.

exception google.appengine.api.logservice.logservice.Errorsource

Bases: exceptions.Exception

Base error class for this module.

exception google.appengine.api.logservice.logservice.InvalidArgumentErrorsource

Bases: google.appengine.api.logservice.logservice.Error

Function argument has invalid value.

google.appengine.api.logservice.logservice.LogsBuffer(stream=None, stderr=False)source
class google.appengine.api.logservice.logservice.RequestLog(request_log=None)source

Bases: object

Complete log information about a single request to an application.

api_mcycles

Number of machine cycles spent in API calls while processing request.

Deprecated. This value is no longer meaningful.

Returns

Number of API machine cycles used as a long, or None if not available.

app_engine_release

App Engine Infrastructure release that served this request.

Returns

A string containing App Engine version that served this request, or None if not available.

app_id

Application id that handled this request, as a string.

app_logs

Logs emitted by the application while serving this request.

Returns

A list of AppLog objects representing the log lines for this request, or an empty list if none were emitted or the query did not request them.

combined

Apache combined log entry for request.

The information in this field can be constructed from the rest of this message, however, this field is included for convenience.

Returns

A string containing an Apache-style log line in the form documented at https://httpd.apache.org/docs/2.4/logs.html.

cost

The estimated cost of this request, in fractional dollars.

Returns

A float representing an estimated fractional dollar cost of this request, or None if not available.

end_time

Time at which request was known to have completed.

Returns

A float representing the request completion time in seconds since the Unix epoch.

finished

Whether or not this log represents a finished request, as a bool.

host

The Internet host and port number of the resource being requested.

Returns

A string representing the host and port receiving the request, or None if not available.

http_version

HTTP version of request, as a string.

instance_key

Mostly-unique identifier for the instance that handled the request.

Returns

A string encoding of an instance key if available, or None.

ip

The origin IP address of the request, as a string.

latency

Time required to process request in seconds, as a float.

mcycles

Number of machine cycles used to process request, as an integer.

method

Request method (GET, PUT, POST, etc), as a string.

module_id

Module id that handled this request, as a string.

nickname

Nickname of the user that made the request if known and logged in.

Returns

A string representation of the logged in user’s nickname, or None.

offset

Binary offset indicating current position in the result stream.

May be submitted to future Log read requests to continue immediately after this request.

Returns

A byte string representing an offset into the active result stream.

pending_time

Time this request spent in the pending request queue.

Returns

A float representing the time in seconds that this request was pending.

referrer

Referrer URL of request as a string, or None.

replica_index

The module replica that handled the request as an integer, or None.

request_id

Globally unique identifier for a request, based on request start time.

Request ids for requests which started later will compare greater as binary strings than those for requests which started earlier.

Returns

A byte string containing a unique identifier for this request.

resource

Resource path on server requested by client.

For example, http://nowhere.com/app would have a resource string of ‘/app’.

Returns

A string containing the path component of the request URL.

response_size

Size in bytes sent back to client by request, as a long.

start_time

Time at which request was known to have begun processing.

Returns

A float representing the time this request began processing in seconds since the Unix epoch.

status

Response status of request, as an int.

task_name

The request’s task name, if generated via the Task Queue API.

Returns

A string containing the request’s task name if relevant, or None.

task_queue_name

The request’s queue name, if generated via the Task Queue API.

Returns

A string containing the request’s queue name if relevant, or None.

url_map_entry

File or class within URL mapping used for request.

Useful for tracking down the source code which was responsible for managing request, especially for multiply mapped handlers.

Returns

A string containing a file or class name.

user_agent

User agent used to make the request as a string, or None.

version_id

Version of the application that handled this request, as a string.

was_loading_request

Returns whether this request was a loading request for an instance.

Returns

A bool indicating whether this request was a loading request.

exception google.appengine.api.logservice.logservice.TimeoutError(msg, offset, last_end_time)source

Bases: google.appengine.api.logservice.logservice.Error

Requested timeout for fetch() call has expired while iterating results.

last_end_time

End time of the last request examined prior to the timeout, or None.

Returns

A float representing the completion time in seconds since the Unix epoch of the last request examined.

offset

Binary offset indicating the current position in the result stream.

May be submitted to future Log read requests to continue iterating logs starting exactly where this iterator left off.

Returns

A byte string representing an offset into the log stream, or None.

google.appengine.api.logservice.logservice.autoflush()source

If AUTOFLUSH conditions have been met, performs a Flush API call.

google.appengine.api.logservice.logservice.cleanup_message(message)source
google.appengine.api.logservice.logservice.clear()source

Clear the logs buffer and reset the autoflush state.

google.appengine.api.logservice.logservice.fetch(*args, **kwds)source

Returns an iterator yielding an application’s request and application logs.

Logs will be returned by the iterator in reverse chronological order by request end time, or by last flush time for requests still in progress (if requested). The items yielded are RequestLog objects, the contents of which are accessible via method calls.

All parameters are optional.

Parameters
  • start_time – The earliest request completion or last-update time that results should be fetched for, in seconds since the Unix epoch.

  • end_time – The latest request completion or last-update time that results should be fetched for, in seconds since the Unix epoch.

  • offset – A byte string representing an offset into the log stream, extracted from a previously emitted RequestLog. This iterator will begin immediately after the record from which the offset came.

  • minimum_log_level – An application log level which serves as a filter on the requests returned–requests with no application log at or above the specified level will be omitted. Works even if include_app_logs is not True. In ascending order, the available log levels are: logservice.LOG_LEVEL_DEBUG, logservice.LOG_LEVEL_INFO, logservice.LOG_LEVEL_WARNING, logservice.LOG_LEVEL_ERROR, and logservice.LOG_LEVEL_CRITICAL.

  • include_incomplete – Whether or not to include requests that have started but not yet finished, as a boolean. Defaults to False.

  • include_app_logs – Whether or not to include application level logs in the results, as a boolean. Defaults to False.

  • module_versions – A list of tuples of the form (module, version), that indicate that the logs for the given module/version combination should be fetched. Duplicate tuples will be ignored. This kwarg may not be used in conjunction with the ‘version_ids’ kwarg.

  • version_ids – A list of version ids whose logs should be queried against. Defaults to the application’s current version id only. This kwarg may not be used in conjunction with the ‘module_versions’ kwarg.

  • request_ids – If not None, indicates that instead of a time-based scan, logs for the specified requests should be returned. Malformed request IDs will cause the entire request to be rejected, while any requests that are unknown will be ignored. This option may not be combined with any filtering options such as start_time, end_time, offset, or minimum_log_level. version_ids is ignored. IDs that do not correspond to a request log will be ignored. Logs will be returned in the order requested.

  • **kwargs – See _FETCH_KWARGS for possible values.

Returns

An iterable object containing the logs that the user has queried for.

Raises

InvalidArgumentError – Raised if any of the input parameters are not of the correct type.

google.appengine.api.logservice.logservice.flush()source

Flushes log lines that are currently buffered.

google.appengine.api.logservice.logservice.flush_time()source

Returns last time that the logs buffer was flushed.

google.appengine.api.logservice.logservice.log_buffer_age()source

Returns the number of seconds since the logs buffer was flushed.

google.appengine.api.logservice.logservice.log_buffer_bytes()source

Returns the size of the logs buffer, in bytes.

google.appengine.api.logservice.logservice.log_buffer_contents()source

Returns the contents of the logs buffer.

google.appengine.api.logservice.logservice.log_buffer_lines()source

Returns the number of log lines currently buffered.

google.appengine.api.logservice.logservice.logs_buffer()source

Returns the LogsBuffer used by the current request.

google.appengine.api.logservice.logservice.source_location_to_tuple(locpb)source

Converts a SourceLocation proto into a tuple of primitive types.

google.appengine.api.logservice.logservice.write(message)source

Adds ‘message’ to the logs buffer, and checks for autoflush.

Parameters

message – A message (string) to be written to application logs.

google.appengine.api.logservice.logservice.write_record(level, created, message, source_location=None)source

Add a ‘record’ to the logs buffer, and checks for autoflush.

Parameters
  • level – the logging level of the record. From 0 to 4 inclusive.

  • created – the time in seconds the record was created.

  • message – the formatted message.

  • source_location – the source location.