Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2# Copyright 2025 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from __future__ import annotations
18from typing import MutableMapping, MutableSequence
20import proto # type: ignore
22from google.api import monitored_resource_pb2 # type: ignore
23from google.logging.type import http_request_pb2 # type: ignore
24from google.logging.type import log_severity_pb2 # type: ignore
25from google.protobuf import any_pb2 # type: ignore
26from google.protobuf import struct_pb2 # type: ignore
27from google.protobuf import timestamp_pb2 # type: ignore
30__protobuf__ = proto.module(
31 package="google.logging.v2",
32 manifest={
33 "LogEntry",
34 "LogEntryOperation",
35 "LogEntrySourceLocation",
36 "LogSplit",
37 },
38)
41class LogEntry(proto.Message):
42 r"""An individual entry in a log.
44 This message has `oneof`_ fields (mutually exclusive fields).
45 For each oneof, at most one member field can be set at the same time.
46 Setting any member of the oneof automatically clears all other
47 members.
49 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
51 Attributes:
52 log_name (str):
53 Required. The resource name of the log to which this log
54 entry belongs:
56 ::
58 "projects/[PROJECT_ID]/logs/[LOG_ID]"
59 "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
60 "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]"
61 "folders/[FOLDER_ID]/logs/[LOG_ID]"
63 A project number may be used in place of PROJECT_ID. The
64 project number is translated to its corresponding PROJECT_ID
65 internally and the ``log_name`` field will contain
66 PROJECT_ID in queries and exports.
68 ``[LOG_ID]`` must be URL-encoded within ``log_name``.
69 Example:
70 ``"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"``.
72 ``[LOG_ID]`` must be less than 512 characters long and can
73 only include the following characters: upper and lower case
74 alphanumeric characters, forward-slash, underscore, hyphen,
75 and period.
77 For backward compatibility, if ``log_name`` begins with a
78 forward-slash, such as ``/projects/...``, then the log entry
79 is ingested as usual, but the forward-slash is removed.
80 Listing the log entry will not show the leading slash and
81 filtering for a log name with a leading slash will never
82 return any results.
83 resource (google.api.monitored_resource_pb2.MonitoredResource):
84 Required. The monitored resource that
85 produced this log entry.
86 Example: a log entry that reports a database
87 error would be associated with the monitored
88 resource designating the particular database
89 that reported the error.
90 proto_payload (google.protobuf.any_pb2.Any):
91 The log entry payload, represented as a
92 protocol buffer. Some Google Cloud Platform
93 services use this field for their log entry
94 payloads.
96 The following protocol buffer types are
97 supported; user-defined types are not supported:
99 "type.googleapis.com/google.cloud.audit.AuditLog"
100 "type.googleapis.com/google.appengine.logging.v1.RequestLog".
102 This field is a member of `oneof`_ ``payload``.
103 text_payload (str):
104 The log entry payload, represented as a
105 Unicode string (UTF-8).
107 This field is a member of `oneof`_ ``payload``.
108 json_payload (google.protobuf.struct_pb2.Struct):
109 The log entry payload, represented as a
110 structure that is expressed as a JSON object.
112 This field is a member of `oneof`_ ``payload``.
113 timestamp (google.protobuf.timestamp_pb2.Timestamp):
114 Optional. The time the event described by the log entry
115 occurred. This time is used to compute the log entry's age
116 and to enforce the logs retention period. If this field is
117 omitted in a new log entry, then Logging assigns it the
118 current time. Timestamps have nanosecond accuracy, but
119 trailing zeros in the fractional seconds might be omitted
120 when the timestamp is displayed.
122 Incoming log entries must have timestamps that don't exceed
123 the `logs retention
124 period <https://cloud.google.com/logging/quotas#logs_retention_periods>`__
125 in the past, and that don't exceed 24 hours in the future.
126 Log entries outside those time boundaries aren't ingested by
127 Logging.
128 receive_timestamp (google.protobuf.timestamp_pb2.Timestamp):
129 Output only. The time the log entry was
130 received by Logging.
131 severity (google.logging.type.log_severity_pb2.LogSeverity):
132 Optional. The severity of the log entry. The default value
133 is ``LogSeverity.DEFAULT``.
134 insert_id (str):
135 Optional. A unique identifier for the log entry. If you
136 provide a value, then Logging considers other log entries in
137 the same project, with the same ``timestamp``, and with the
138 same ``insert_id`` to be duplicates which are removed in a
139 single query result. However, there are no guarantees of
140 de-duplication in the export of logs.
142 If the ``insert_id`` is omitted when writing a log entry,
143 the Logging API assigns its own unique identifier in this
144 field.
146 In queries, the ``insert_id`` is also used to order log
147 entries that have the same ``log_name`` and ``timestamp``
148 values.
149 http_request (google.logging.type.http_request_pb2.HttpRequest):
150 Optional. Information about the HTTP request
151 associated with this log entry, if applicable.
152 labels (MutableMapping[str, str]):
153 Optional. A map of key, value pairs that provides additional
154 information about the log entry. The labels can be
155 user-defined or system-defined.
157 User-defined labels are arbitrary key, value pairs that you
158 can use to classify logs.
160 System-defined labels are defined by GCP services for
161 platform logs. They have two components - a service
162 namespace component and the attribute name. For example:
163 ``compute.googleapis.com/resource_name``.
165 Cloud Logging truncates label keys that exceed 512 B and
166 label values that exceed 64 KB upon their associated log
167 entry being written. The truncation is indicated by an
168 ellipsis at the end of the character string.
169 operation (google.cloud.logging_v2.types.LogEntryOperation):
170 Optional. Information about an operation
171 associated with the log entry, if applicable.
172 trace (str):
173 Optional. The REST resource name of the trace being written
174 to `Cloud Trace <https://cloud.google.com/trace>`__ in
175 association with this log entry. For example, if your trace
176 data is stored in the Cloud project "my-trace-project" and
177 if the service that is creating the log entry receives a
178 trace header that includes the trace ID "12345", then the
179 service should use
180 "projects/my-tracing-project/traces/12345".
182 The ``trace`` field provides the link between logs and
183 traces. By using this field, you can navigate from a log
184 entry to a trace.
185 span_id (str):
186 Optional. The ID of the `Cloud
187 Trace <https://cloud.google.com/trace>`__ span associated
188 with the current operation in which the log is being
189 written. For example, if a span has the REST resource name
190 of
191 "projects/some-project/traces/some-trace/spans/some-span-id",
192 then the ``span_id`` field is "some-span-id".
194 A
195 `Span <https://cloud.google.com/trace/docs/reference/v2/rest/v2/projects.traces/batchWrite#Span>`__
196 represents a single operation within a trace. Whereas a
197 trace may involve multiple different microservices running
198 on multiple different machines, a span generally corresponds
199 to a single logical operation being performed in a single
200 instance of a microservice on one specific machine. Spans
201 are the nodes within the tree that is a trace.
203 Applications that are `instrumented for
204 tracing <https://cloud.google.com/trace/docs/setup>`__ will
205 generally assign a new, unique span ID on each incoming
206 request. It is also common to create and record additional
207 spans corresponding to internal processing elements as well
208 as issuing requests to dependencies.
210 The span ID is expected to be a 16-character, hexadecimal
211 encoding of an 8-byte array and should not be zero. It
212 should be unique within the trace and should, ideally, be
213 generated in a manner that is uniformly random.
215 Example values:
217 - ``000000000000004a``
218 - ``7a2190356c3fc94b``
219 - ``0000f00300090021``
220 - ``d39223e101960076``
221 trace_sampled (bool):
222 Optional. The sampling decision of the trace associated with
223 the log entry.
225 True means that the trace resource name in the ``trace``
226 field was sampled for storage in a trace backend. False
227 means that the trace was not sampled for storage when this
228 log entry was written, or the sampling decision was unknown
229 at the time. A non-sampled ``trace`` value is still useful
230 as a request correlation identifier. The default is False.
231 source_location (google.cloud.logging_v2.types.LogEntrySourceLocation):
232 Optional. Source code location information
233 associated with the log entry, if any.
234 split (google.cloud.logging_v2.types.LogSplit):
235 Optional. Information indicating this
236 LogEntry is part of a sequence of multiple log
237 entries split from a single LogEntry.
238 """
240 log_name: str = proto.Field(
241 proto.STRING,
242 number=12,
243 )
244 resource: monitored_resource_pb2.MonitoredResource = proto.Field(
245 proto.MESSAGE,
246 number=8,
247 message=monitored_resource_pb2.MonitoredResource,
248 )
249 proto_payload: any_pb2.Any = proto.Field(
250 proto.MESSAGE,
251 number=2,
252 oneof="payload",
253 message=any_pb2.Any,
254 )
255 text_payload: str = proto.Field(
256 proto.STRING,
257 number=3,
258 oneof="payload",
259 )
260 json_payload: struct_pb2.Struct = proto.Field(
261 proto.MESSAGE,
262 number=6,
263 oneof="payload",
264 message=struct_pb2.Struct,
265 )
266 timestamp: timestamp_pb2.Timestamp = proto.Field(
267 proto.MESSAGE,
268 number=9,
269 message=timestamp_pb2.Timestamp,
270 )
271 receive_timestamp: timestamp_pb2.Timestamp = proto.Field(
272 proto.MESSAGE,
273 number=24,
274 message=timestamp_pb2.Timestamp,
275 )
276 severity: log_severity_pb2.LogSeverity = proto.Field(
277 proto.ENUM,
278 number=10,
279 enum=log_severity_pb2.LogSeverity,
280 )
281 insert_id: str = proto.Field(
282 proto.STRING,
283 number=4,
284 )
285 http_request: http_request_pb2.HttpRequest = proto.Field(
286 proto.MESSAGE,
287 number=7,
288 message=http_request_pb2.HttpRequest,
289 )
290 labels: MutableMapping[str, str] = proto.MapField(
291 proto.STRING,
292 proto.STRING,
293 number=11,
294 )
295 operation: "LogEntryOperation" = proto.Field(
296 proto.MESSAGE,
297 number=15,
298 message="LogEntryOperation",
299 )
300 trace: str = proto.Field(
301 proto.STRING,
302 number=22,
303 )
304 span_id: str = proto.Field(
305 proto.STRING,
306 number=27,
307 )
308 trace_sampled: bool = proto.Field(
309 proto.BOOL,
310 number=30,
311 )
312 source_location: "LogEntrySourceLocation" = proto.Field(
313 proto.MESSAGE,
314 number=23,
315 message="LogEntrySourceLocation",
316 )
317 split: "LogSplit" = proto.Field(
318 proto.MESSAGE,
319 number=35,
320 message="LogSplit",
321 )
324class LogEntryOperation(proto.Message):
325 r"""Additional information about a potentially long-running
326 operation with which a log entry is associated.
328 Attributes:
329 id (str):
330 Optional. An arbitrary operation identifier.
331 Log entries with the same identifier are assumed
332 to be part of the same operation.
333 producer (str):
334 Optional. An arbitrary producer identifier. The combination
335 of ``id`` and ``producer`` must be globally unique. Examples
336 for ``producer``: ``"MyDivision.MyBigCompany.com"``,
337 ``"github.com/MyProject/MyApplication"``.
338 first (bool):
339 Optional. Set this to True if this is the
340 first log entry in the operation.
341 last (bool):
342 Optional. Set this to True if this is the
343 last log entry in the operation.
344 """
346 id: str = proto.Field(
347 proto.STRING,
348 number=1,
349 )
350 producer: str = proto.Field(
351 proto.STRING,
352 number=2,
353 )
354 first: bool = proto.Field(
355 proto.BOOL,
356 number=3,
357 )
358 last: bool = proto.Field(
359 proto.BOOL,
360 number=4,
361 )
364class LogEntrySourceLocation(proto.Message):
365 r"""Additional information about the source code location that
366 produced the log entry.
368 Attributes:
369 file (str):
370 Optional. Source file name. Depending on the
371 runtime environment, this might be a simple name
372 or a fully-qualified name.
373 line (int):
374 Optional. Line within the source file.
375 1-based; 0 indicates no line number available.
376 function (str):
377 Optional. Human-readable name of the function or method
378 being invoked, with optional context such as the class or
379 package name. This information may be used in contexts such
380 as the logs viewer, where a file and line number are less
381 meaningful. The format can vary by language. For example:
382 ``qual.if.ied.Class.method`` (Java), ``dir/package.func``
383 (Go), ``function`` (Python).
384 """
386 file: str = proto.Field(
387 proto.STRING,
388 number=1,
389 )
390 line: int = proto.Field(
391 proto.INT64,
392 number=2,
393 )
394 function: str = proto.Field(
395 proto.STRING,
396 number=3,
397 )
400class LogSplit(proto.Message):
401 r"""Additional information used to correlate multiple log
402 entries. Used when a single LogEntry would exceed the Google
403 Cloud Logging size limit and is split across multiple log
404 entries.
406 Attributes:
407 uid (str):
408 A globally unique identifier for all log entries in a
409 sequence of split log entries. All log entries with the same
410 \|LogSplit.uid\| are assumed to be part of the same sequence
411 of split log entries.
412 index (int):
413 The index of this LogEntry in the sequence of split log
414 entries. Log entries are given \|index\| values 0, 1, ...,
415 n-1 for a sequence of n log entries.
416 total_splits (int):
417 The total number of log entries that the
418 original LogEntry was split into.
419 """
421 uid: str = proto.Field(
422 proto.STRING,
423 number=1,
424 )
425 index: int = proto.Field(
426 proto.INT32,
427 number=2,
428 )
429 total_splits: int = proto.Field(
430 proto.INT32,
431 number=3,
432 )
435__all__ = tuple(sorted(__protobuf__.manifest))