0
# Google Cloud App Engine Logging
1

2
A Python protocol buffer library providing message classes for Google Cloud App Engine Logging API. This package defines data structures for App Engine request logs, log lines, and source references without providing service clients for making API calls.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-appengine-logging
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install google-cloud-appengine-logging`
10

11
## Core Imports
12

13
```python
14
from google.cloud.appengine_logging import (
15
    LogLine,
16
    RequestLog,
17
    SourceLocation,
18
    SourceReference,
19
    __version__
20
)
21
```
22

23
Alternative import from versioned module:
24

25
```python
26
from google.cloud.appengine_logging_v1 import (
27
    LogLine,
28
    RequestLog,
29
    SourceLocation,
30
    SourceReference,
31
    __version__
32
)
33
```
34

35
## Basic Usage
36

37
```python
38
from google.cloud.appengine_logging import LogLine, RequestLog, SourceLocation, SourceReference
39
from google.protobuf.timestamp_pb2 import Timestamp
40
from google.logging.type.log_severity_pb2 import LogSeverity
41

42
# Create a log line with source location
43
source_location = SourceLocation(
44
    file="main.py",
45
    line=42,
46
    function_name="process_request"
47
)
48

49
log_line = LogLine(
50
    time=Timestamp(),
51
    severity=LogSeverity.INFO,
52
    log_message="Processing user request",
53
    source_location=source_location
54
)
55

56
# Create a source reference for deployment tracking
57
source_ref = SourceReference(
58
    repository="https://github.com/myorg/myapp.git",
59
    revision_id="abc123def456789"
60
)
61

62
# Create a comprehensive request log
63
request_log = RequestLog(
64
    app_id="my-app",
65
    module_id="default",
66
    version_id="v1.0.0",
67
    request_id="req_12345",
68
    ip="192.168.1.1",
69
    method="GET",
70
    resource="/api/users",
71
    http_version="HTTP/1.1",
72
    status=200,
73
    response_size=1024,
74
    user_agent="Mozilla/5.0",
75
    line=[log_line],
76
    source_reference=[source_ref]
77
)
78

79
# Access request log properties
80
print(f"Request {request_log.request_id} to {request_log.resource}")
81
print(f"Status: {request_log.status}, Size: {request_log.response_size} bytes")
82
```
83

84
## Capabilities
85

86
### LogLine Message
87

88
Application log line emitted while processing a request, containing timestamp, severity, message, and source location information.
89

90
```python { .api }
91
class LogLine(proto.Message):
92
    """Application log line emitted while processing a request.
93
    
94
    Attributes:
95
        time (google.protobuf.timestamp_pb2.Timestamp): Approximate time when this log entry was made
96
        severity (google.logging.type.log_severity_pb2.LogSeverity): Severity of this log entry
97
        log_message (str): App-provided log message
98
        source_location (SourceLocation): Where in the source code this log message was written
99
    """
100
    time: "google.protobuf.timestamp_pb2.Timestamp"
101
    severity: "google.logging.type.log_severity_pb2.LogSeverity"
102
    log_message: str
103
    source_location: "SourceLocation"
104
```
105

106
### SourceLocation Message
107

108
Specifies a location in a source code file with file name, line number, and function context.
109

110
```python { .api }
111
class SourceLocation(proto.Message):
112
    """Specifies a location in a source code file.
113
    
114
    Attributes:
115
        file (str): Source file name. Depending on the runtime environment, this might be a simple name or a fully-qualified name
116
        line (int): Line within the source file
117
        function_name (str): Human-readable name of the function or method being invoked, with optional context such as the class or package name
118
    """
119
    file: str
120
    line: int
121
    function_name: str
122
```
123

124
### SourceReference Message
125

126
Reference to a particular snapshot of the source tree used to build and deploy an application.
127

128
```python { .api }
129
class SourceReference(proto.Message):
130
    """A reference to a particular snapshot of the source tree used to build and deploy an application.
131
    
132
    Attributes:
133
        repository (str): Optional. A URI string identifying the repository. Example: "https://github.com/GoogleCloudPlatform/kubernetes.git"
134
        revision_id (str): The canonical and persistent identifier of the deployed revision. Example (git): "0035781c50ec7aa23385dc841529ce8a4b70db1b"
135
    """
136
    repository: str
137
    revision_id: str
138
```
139

140
### RequestLog Message
141

142
Complete log information about a single HTTP request to an App Engine application, containing comprehensive request and response metadata.
143

144
```python { .api }
145
class RequestLog(proto.Message):
146
    """Complete log information about a single HTTP request to an App Engine application.
147
    
148
    Attributes:
149
        app_id (str): Application that handled this request
150
        module_id (str): Module of the application that handled this request
151
        version_id (str): Version of the application that handled this request
152
        request_id (str): Globally unique identifier for a request, which is based on the request start time
153
        ip (str): Origin IP address
154
        start_time (google.protobuf.timestamp_pb2.Timestamp): Time when the request started
155
        end_time (google.protobuf.timestamp_pb2.Timestamp): Time when the request finished
156
        latency (google.protobuf.duration_pb2.Duration): Latency of the request
157
        mega_cycles (int): Number of CPU megacycles used to process request
158
        method (str): Request method. Example: "GET", "HEAD", "PUT", "POST", "DELETE"
159
        resource (str): Contains the path and query portion of the URL that was requested
160
        http_version (str): HTTP version of request. Example: "HTTP/1.1"
161
        status (int): HTTP response status code. Example: 200, 404
162
        response_size (int): Size in bytes sent back to client by request
163
        referrer (str): Referrer URL of request
164
        user_agent (str): User agent that made the request
165
        nickname (str): The logged-in user who made the request
166
        url_map_entry (str): File or class that handled the request
167
        host (str): Internet host and port number of the resource being requested
168
        cost (float): An indication of the relative cost of serving this request
169
        task_queue_name (str): Queue name of the request, in the case of an offline request
170
        task_name (str): Task name of the request, in the case of an offline request
171
        was_loading_request (bool): Whether this was a loading request for the instance
172
        pending_time (google.protobuf.duration_pb2.Duration): Time this request spent in the pending request queue
173
        instance_index (int): If the instance processing this request belongs to a manually scaled module, then this is the 0-based index of the instance. Otherwise, this value is -1
174
        finished (bool): Whether this request is finished or active
175
        first (bool): Whether this is the first RequestLog entry for this request
176
        instance_id (str): An identifier for the instance that handled the request
177
        line (MutableSequence[LogLine]): A list of log lines emitted by the application while serving this request
178
        app_engine_release (str): App Engine release version
179
        trace_id (str): Stackdriver Trace identifier for this request
180
        trace_sampled (bool): If true, the value in the 'trace_id' field was sampled for storage in a trace backend
181
        source_reference (MutableSequence[SourceReference]): Source code for the application that handled this request. There can be more than one source reference per deployed application if source code is distributed among multiple repositories
182
    """
183
    app_id: str
184
    module_id: str
185
    version_id: str
186
    request_id: str
187
    ip: str
188
    start_time: "google.protobuf.timestamp_pb2.Timestamp"
189
    end_time: "google.protobuf.timestamp_pb2.Timestamp"
190
    latency: "google.protobuf.duration_pb2.Duration"
191
    mega_cycles: int
192
    method: str
193
    resource: str
194
    http_version: str
195
    status: int
196
    response_size: int
197
    referrer: str
198
    user_agent: str
199
    nickname: str
200
    url_map_entry: str
201
    host: str
202
    cost: float
203
    task_queue_name: str
204
    task_name: str
205
    was_loading_request: bool
206
    pending_time: "google.protobuf.duration_pb2.Duration"
207
    instance_index: int
208
    finished: bool
209
    first: bool
210
    instance_id: str
211
    line: "MutableSequence[LogLine]"
212
    app_engine_release: str
213
    trace_id: str
214
    trace_sampled: bool
215
    source_reference: "MutableSequence[SourceReference]"
216
```
217

218
### Version Information
219

220
Package version information for compatibility checking and debugging.
221

222
```python { .api }
223
__version__: str = "1.6.2"
224
```
225

226
## Types
227

228
### External Dependencies
229

230
This package uses the following external protobuf types that must be imported separately:
231

232
```python { .api }
233
# From google.protobuf
234
from google.protobuf.timestamp_pb2 import Timestamp
235
from google.protobuf.duration_pb2 import Duration
236

237
# From google.logging.type
238
from google.logging.type.log_severity_pb2 import LogSeverity
239

240
# Protocol buffer framework
241
import proto
242

243
# For type annotations
244
from typing import MutableSequence
245
```
246

247
### LogSeverity Enum Values
248

249
The LogSeverity enum from google.logging.type.log_severity_pb2 includes:
250
- `DEFAULT` (0): The log entry has no assigned severity level
251
- `DEBUG` (100): Debug or trace information
252
- `INFO` (200): Routine information
253
- `NOTICE` (300): Notice information
254
- `WARNING` (400): Warning information
255
- `ERROR` (500): Error information
256
- `CRITICAL` (600): Critical information
257
- `ALERT` (700): Alert information
258
- `EMERGENCY` (800): Emergency information