Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/logging_v2/types/logging_metrics.py: 98%
44 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-08 06:45 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2023 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 distribution_pb2 # type: ignore
23from google.api import metric_pb2 # type: ignore
24from google.protobuf import timestamp_pb2 # type: ignore
27__protobuf__ = proto.module(
28 package="google.logging.v2",
29 manifest={
30 "LogMetric",
31 "ListLogMetricsRequest",
32 "ListLogMetricsResponse",
33 "GetLogMetricRequest",
34 "CreateLogMetricRequest",
35 "UpdateLogMetricRequest",
36 "DeleteLogMetricRequest",
37 },
38)
41class LogMetric(proto.Message):
42 r"""Describes a logs-based metric. The value of the metric is the
43 number of log entries that match a logs filter in a given time
44 interval.
46 Logs-based metrics can also be used to extract values from logs
47 and create a distribution of the values. The distribution
48 records the statistics of the extracted values along with an
49 optional histogram of the values as specified by the bucket
50 options.
52 Attributes:
53 name (str):
54 Required. The client-assigned metric identifier. Examples:
55 ``"error_count"``, ``"nginx/requests"``.
57 Metric identifiers are limited to 100 characters and can
58 include only the following characters: ``A-Z``, ``a-z``,
59 ``0-9``, and the special characters ``_-.,+!*',()%/``. The
60 forward-slash character (``/``) denotes a hierarchy of name
61 pieces, and it cannot be the first character of the name.
63 This field is the ``[METRIC_ID]`` part of a metric resource
64 name in the format
65 "projects/[PROJECT_ID]/metrics/[METRIC_ID]". Example: If the
66 resource name of a metric is
67 ``"projects/my-project/metrics/nginx%2Frequests"``, this
68 field's value is ``"nginx/requests"``.
69 description (str):
70 Optional. A description of this metric, which
71 is used in documentation. The maximum length of
72 the description is 8000 characters.
73 filter (str):
74 Required. An `advanced logs
75 filter <https://cloud.google.com/logging/docs/view/advanced_filters>`__
76 which is used to match log entries. Example:
78 ::
80 "resource.type=gae_app AND severity>=ERROR"
82 The maximum length of the filter is 20000 characters.
83 bucket_name (str):
84 Optional. The resource name of the Log Bucket that owns the
85 Log Metric. Only Log Buckets in projects are supported. The
86 bucket has to be in the same project as the metric.
88 For example:
90 ``projects/my-project/locations/global/buckets/my-bucket``
92 If empty, then the Log Metric is considered a non-Bucket Log
93 Metric.
94 disabled (bool):
95 Optional. If set to True, then this metric is
96 disabled and it does not generate any points.
97 metric_descriptor (google.api.metric_pb2.MetricDescriptor):
98 Optional. The metric descriptor associated with the
99 logs-based metric. If unspecified, it uses a default metric
100 descriptor with a DELTA metric kind, INT64 value type, with
101 no labels and a unit of "1". Such a metric counts the number
102 of log entries matching the ``filter`` expression.
104 The ``name``, ``type``, and ``description`` fields in the
105 ``metric_descriptor`` are output only, and is constructed
106 using the ``name`` and ``description`` field in the
107 LogMetric.
109 To create a logs-based metric that records a distribution of
110 log values, a DELTA metric kind with a DISTRIBUTION value
111 type must be used along with a ``value_extractor``
112 expression in the LogMetric.
114 Each label in the metric descriptor must have a matching
115 label name as the key and an extractor expression as the
116 value in the ``label_extractors`` map.
118 The ``metric_kind`` and ``value_type`` fields in the
119 ``metric_descriptor`` cannot be updated once initially
120 configured. New labels can be added in the
121 ``metric_descriptor``, but existing labels cannot be
122 modified except for their description.
123 value_extractor (str):
124 Optional. A ``value_extractor`` is required when using a
125 distribution logs-based metric to extract the values to
126 record from a log entry. Two functions are supported for
127 value extraction: ``EXTRACT(field)`` or
128 ``REGEXP_EXTRACT(field, regex)``. The arguments are:
130 1. field: The name of the log entry field from which the
131 value is to be extracted.
132 2. regex: A regular expression using the Google RE2 syntax
133 (https://github.com/google/re2/wiki/Syntax) with a single
134 capture group to extract data from the specified log
135 entry field. The value of the field is converted to a
136 string before applying the regex. It is an error to
137 specify a regex that does not include exactly one capture
138 group.
140 The result of the extraction must be convertible to a double
141 type, as the distribution always records double values. If
142 either the extraction or the conversion to double fails,
143 then those values are not recorded in the distribution.
145 Example:
146 ``REGEXP_EXTRACT(jsonPayload.request, ".*quantity=(\d+).*")``
147 label_extractors (MutableMapping[str, str]):
148 Optional. A map from a label key string to an extractor
149 expression which is used to extract data from a log entry
150 field and assign as the label value. Each label key
151 specified in the LabelDescriptor must have an associated
152 extractor expression in this map. The syntax of the
153 extractor expression is the same as for the
154 ``value_extractor`` field.
156 The extracted value is converted to the type defined in the
157 label descriptor. If either the extraction or the type
158 conversion fails, the label will have a default value. The
159 default value for a string label is an empty string, for an
160 integer label its 0, and for a boolean label its ``false``.
162 Note that there are upper bounds on the maximum number of
163 labels and the number of active time series that are allowed
164 in a project.
165 bucket_options (google.api.distribution_pb2.BucketOptions):
166 Optional. The ``bucket_options`` are required when the
167 logs-based metric is using a DISTRIBUTION value type and it
168 describes the bucket boundaries used to create a histogram
169 of the extracted values.
170 create_time (google.protobuf.timestamp_pb2.Timestamp):
171 Output only. The creation timestamp of the
172 metric.
173 This field may not be present for older metrics.
174 update_time (google.protobuf.timestamp_pb2.Timestamp):
175 Output only. The last update timestamp of the
176 metric.
177 This field may not be present for older metrics.
178 version (google.cloud.logging_v2.types.LogMetric.ApiVersion):
179 Deprecated. The API version that created or
180 updated this metric. The v2 format is used by
181 default and cannot be changed.
182 """
184 class ApiVersion(proto.Enum):
185 r"""Logging API version.
187 Values:
188 V2 (0):
189 Logging API v2.
190 V1 (1):
191 Logging API v1.
192 """
193 V2 = 0
194 V1 = 1
196 name: str = proto.Field(
197 proto.STRING,
198 number=1,
199 )
200 description: str = proto.Field(
201 proto.STRING,
202 number=2,
203 )
204 filter: str = proto.Field(
205 proto.STRING,
206 number=3,
207 )
208 bucket_name: str = proto.Field(
209 proto.STRING,
210 number=13,
211 )
212 disabled: bool = proto.Field(
213 proto.BOOL,
214 number=12,
215 )
216 metric_descriptor: metric_pb2.MetricDescriptor = proto.Field(
217 proto.MESSAGE,
218 number=5,
219 message=metric_pb2.MetricDescriptor,
220 )
221 value_extractor: str = proto.Field(
222 proto.STRING,
223 number=6,
224 )
225 label_extractors: MutableMapping[str, str] = proto.MapField(
226 proto.STRING,
227 proto.STRING,
228 number=7,
229 )
230 bucket_options: distribution_pb2.Distribution.BucketOptions = proto.Field(
231 proto.MESSAGE,
232 number=8,
233 message=distribution_pb2.Distribution.BucketOptions,
234 )
235 create_time: timestamp_pb2.Timestamp = proto.Field(
236 proto.MESSAGE,
237 number=9,
238 message=timestamp_pb2.Timestamp,
239 )
240 update_time: timestamp_pb2.Timestamp = proto.Field(
241 proto.MESSAGE,
242 number=10,
243 message=timestamp_pb2.Timestamp,
244 )
245 version: ApiVersion = proto.Field(
246 proto.ENUM,
247 number=4,
248 enum=ApiVersion,
249 )
252class ListLogMetricsRequest(proto.Message):
253 r"""The parameters to ListLogMetrics.
255 Attributes:
256 parent (str):
257 Required. The name of the project containing the metrics:
259 ::
261 "projects/[PROJECT_ID]".
262 page_token (str):
263 Optional. If present, then retrieve the next batch of
264 results from the preceding call to this method.
265 ``pageToken`` must be the value of ``nextPageToken`` from
266 the previous response. The values of other method parameters
267 should be identical to those in the previous call.
268 page_size (int):
269 Optional. The maximum number of results to return from this
270 request. Non-positive values are ignored. The presence of
271 ``nextPageToken`` in the response indicates that more
272 results might be available.
273 """
275 parent: str = proto.Field(
276 proto.STRING,
277 number=1,
278 )
279 page_token: str = proto.Field(
280 proto.STRING,
281 number=2,
282 )
283 page_size: int = proto.Field(
284 proto.INT32,
285 number=3,
286 )
289class ListLogMetricsResponse(proto.Message):
290 r"""Result returned from ListLogMetrics.
292 Attributes:
293 metrics (MutableSequence[google.cloud.logging_v2.types.LogMetric]):
294 A list of logs-based metrics.
295 next_page_token (str):
296 If there might be more results than appear in this response,
297 then ``nextPageToken`` is included. To get the next set of
298 results, call this method again using the value of
299 ``nextPageToken`` as ``pageToken``.
300 """
302 @property
303 def raw_page(self):
304 return self
306 metrics: MutableSequence["LogMetric"] = proto.RepeatedField(
307 proto.MESSAGE,
308 number=1,
309 message="LogMetric",
310 )
311 next_page_token: str = proto.Field(
312 proto.STRING,
313 number=2,
314 )
317class GetLogMetricRequest(proto.Message):
318 r"""The parameters to GetLogMetric.
320 Attributes:
321 metric_name (str):
322 Required. The resource name of the desired metric:
324 ::
326 "projects/[PROJECT_ID]/metrics/[METRIC_ID]".
327 """
329 metric_name: str = proto.Field(
330 proto.STRING,
331 number=1,
332 )
335class CreateLogMetricRequest(proto.Message):
336 r"""The parameters to CreateLogMetric.
338 Attributes:
339 parent (str):
340 Required. The resource name of the project in which to
341 create the metric:
343 ::
345 "projects/[PROJECT_ID]"
347 The new metric must be provided in the request.
348 metric (google.cloud.logging_v2.types.LogMetric):
349 Required. The new logs-based metric, which
350 must not have an identifier that already exists.
351 """
353 parent: str = proto.Field(
354 proto.STRING,
355 number=1,
356 )
357 metric: "LogMetric" = proto.Field(
358 proto.MESSAGE,
359 number=2,
360 message="LogMetric",
361 )
364class UpdateLogMetricRequest(proto.Message):
365 r"""The parameters to UpdateLogMetric.
367 Attributes:
368 metric_name (str):
369 Required. The resource name of the metric to update:
371 ::
373 "projects/[PROJECT_ID]/metrics/[METRIC_ID]"
375 The updated metric must be provided in the request and it's
376 ``name`` field must be the same as ``[METRIC_ID]`` If the
377 metric does not exist in ``[PROJECT_ID]``, then a new metric
378 is created.
379 metric (google.cloud.logging_v2.types.LogMetric):
380 Required. The updated metric.
381 """
383 metric_name: str = proto.Field(
384 proto.STRING,
385 number=1,
386 )
387 metric: "LogMetric" = proto.Field(
388 proto.MESSAGE,
389 number=2,
390 message="LogMetric",
391 )
394class DeleteLogMetricRequest(proto.Message):
395 r"""The parameters to DeleteLogMetric.
397 Attributes:
398 metric_name (str):
399 Required. The resource name of the metric to delete:
401 ::
403 "projects/[PROJECT_ID]/metrics/[METRIC_ID]".
404 """
406 metric_name: str = proto.Field(
407 proto.STRING,
408 number=1,
409 )
412__all__ = tuple(sorted(__protobuf__.manifest))