0
# Metrics and Time Series
1
2
Core functionality for working with metrics, time series data, and monitored resources in Google Cloud Monitoring. This service handles metric descriptor management, time series data ingestion and querying, and monitored resource descriptor operations.
3
4
## Capabilities
5
6
### Metric Descriptor Management
7
8
Manage metric descriptors that define the schema and metadata for custom metrics.
9
10
```python { .api }
11
class MetricServiceClient:
12
def list_metric_descriptors(
13
self,
14
request=None,
15
*,
16
name: str = None,
17
retry=None,
18
timeout=None,
19
metadata=()
20
) -> pagers.ListMetricDescriptorsPager:
21
"""
22
Lists metric descriptors that match a filter.
23
24
Args:
25
request: The request object or dict equivalent
26
name: Required. Project name in format 'projects/[PROJECT_ID]'
27
retry: Retry configuration
28
timeout: Request timeout in seconds
29
metadata: Additional metadata
30
31
Returns:
32
Pager for iterating over metric descriptors
33
"""
34
35
def get_metric_descriptor(
36
self,
37
request=None,
38
*,
39
name: str = None,
40
retry=None,
41
timeout=None,
42
metadata=()
43
) -> metric_pb2.MetricDescriptor:
44
"""
45
Gets a single metric descriptor.
46
47
Args:
48
request: The request object or dict equivalent
49
name: Required. Metric descriptor name
50
retry: Retry configuration
51
timeout: Request timeout in seconds
52
metadata: Additional metadata
53
54
Returns:
55
MetricDescriptor object
56
"""
57
58
def create_metric_descriptor(
59
self,
60
request=None,
61
*,
62
name: str = None,
63
metric_descriptor=None,
64
retry=None,
65
timeout=None,
66
metadata=()
67
) -> metric_pb2.MetricDescriptor:
68
"""
69
Creates a user-defined metric descriptor.
70
71
Args:
72
request: The request object or dict equivalent
73
name: Required. Project name
74
metric_descriptor: Required. The metric descriptor to create
75
retry: Retry configuration
76
timeout: Request timeout in seconds
77
metadata: Additional metadata
78
79
Returns:
80
Created MetricDescriptor object
81
"""
82
83
def delete_metric_descriptor(
84
self,
85
request=None,
86
*,
87
name: str = None,
88
retry=None,
89
timeout=None,
90
metadata=()
91
) -> None:
92
"""
93
Deletes a metric descriptor.
94
95
Args:
96
request: The request object or dict equivalent
97
name: Required. Metric descriptor name to delete
98
retry: Retry configuration
99
timeout: Request timeout in seconds
100
metadata: Additional metadata
101
"""
102
```
103
104
### Time Series Operations
105
106
Manage time series data including reading historical data and writing new data points.
107
108
```python { .api }
109
class MetricServiceClient:
110
def list_time_series(
111
self,
112
request=None,
113
*,
114
name: str = None,
115
filter: str = None,
116
interval=None,
117
view=None,
118
retry=None,
119
timeout=None,
120
metadata=()
121
) -> pagers.ListTimeSeriesPager:
122
"""
123
Lists time series that match a filter.
124
125
Args:
126
request: The request object or dict equivalent
127
name: Required. Project name
128
filter: Required. Monitoring filter string
129
interval: Required. Time interval for data
130
view: Specifies which information is returned
131
retry: Retry configuration
132
timeout: Request timeout in seconds
133
metadata: Additional metadata
134
135
Returns:
136
Pager for iterating over TimeSeries objects
137
"""
138
139
def create_time_series(
140
self,
141
request=None,
142
*,
143
name: str = None,
144
time_series=None,
145
retry=None,
146
timeout=None,
147
metadata=()
148
) -> None:
149
"""
150
Creates or adds data to one or more time series.
151
152
Args:
153
request: The request object or dict equivalent
154
name: Required. Project name
155
time_series: Required. List of TimeSeries objects
156
retry: Retry configuration
157
timeout: Request timeout in seconds
158
metadata: Additional metadata
159
"""
160
161
def create_service_time_series(
162
self,
163
request=None,
164
*,
165
name: str = None,
166
time_series=None,
167
retry=None,
168
timeout=None,
169
metadata=()
170
) -> None:
171
"""
172
Creates or adds data to service time series.
173
174
Args:
175
request: The request object or dict equivalent
176
name: Required. Project name
177
time_series: Required. List of TimeSeries objects
178
retry: Retry configuration
179
timeout: Request timeout in seconds
180
metadata: Additional metadata
181
"""
182
```
183
184
### Monitored Resource Descriptors
185
186
Manage monitored resource descriptors that define resource types and their label schemas.
187
188
```python { .api }
189
class MetricServiceClient:
190
def list_monitored_resource_descriptors(
191
self,
192
request=None,
193
*,
194
name: str = None,
195
retry=None,
196
timeout=None,
197
metadata=()
198
) -> pagers.ListMonitoredResourceDescriptorsPager:
199
"""
200
Lists monitored resource descriptors.
201
202
Args:
203
request: The request object or dict equivalent
204
name: Required. Project name
205
retry: Retry configuration
206
timeout: Request timeout in seconds
207
metadata: Additional metadata
208
209
Returns:
210
Pager for iterating over MonitoredResourceDescriptor objects
211
"""
212
213
def get_monitored_resource_descriptor(
214
self,
215
request=None,
216
*,
217
name: str = None,
218
retry=None,
219
timeout=None,
220
metadata=()
221
) -> monitored_resource_pb2.MonitoredResourceDescriptor:
222
"""
223
Gets a single monitored resource descriptor.
224
225
Args:
226
request: The request object or dict equivalent
227
name: Required. Monitored resource descriptor name
228
retry: Retry configuration
229
timeout: Request timeout in seconds
230
metadata: Additional metadata
231
232
Returns:
233
MonitoredResourceDescriptor object
234
"""
235
```
236
237
## Data Types
238
239
### TimeSeries
240
241
Represents a collection of data points associated with a metric.
242
243
```python { .api }
244
class TimeSeries:
245
metric: Metric # Associated metric
246
resource: MonitoredResource # Associated resource
247
metadata: MonitoredResourceMetadata # Resource metadata
248
metric_kind: MetricDescriptor.MetricKind # Metric kind
249
value_type: MetricDescriptor.ValueType # Value type
250
points: List[Point] # Data points
251
unit: str # Unit of measurement
252
253
class Point:
254
interval: TimeInterval # Time interval for the point
255
value: TypedValue # The value of the point
256
257
class Metric:
258
type: str # Metric type name
259
labels: Dict[str, str] # Metric labels
260
261
class MonitoredResource:
262
type: str # Resource type
263
labels: Dict[str, str] # Resource labels
264
```
265
266
### Query Types
267
268
```python { .api }
269
class ListTimeSeriesRequest:
270
name: str # Required. Project name
271
filter: str # Required. Monitoring filter
272
interval: TimeInterval # Required. Time interval
273
aggregation: Aggregation # Aggregation specification
274
order_by: str # Ordering specification
275
view: ListTimeSeriesRequest.TimeSeriesView # View type
276
page_size: int # Maximum results per page
277
page_token: str # Page token
278
279
class ListTimeSeriesResponse:
280
time_series: List[TimeSeries] # Time series data
281
next_page_token: str # Next page token
282
execution_errors: List[Status] # Execution errors
283
284
class CreateTimeSeriesRequest:
285
name: str # Required. Project name
286
time_series: List[TimeSeries] # Required. Time series data
287
288
class CreateTimeSeriesSummary:
289
total_point_count: int # Total points processed
290
success_point_count: int # Successfully written points
291
errors: List[CreateTimeSeriesError] # Errors encountered
292
293
class CreateTimeSeriesError:
294
time_series: TimeSeries # Time series with error
295
status: Status # Error status
296
```
297
298
### Metric Descriptor Types
299
300
```python { .api }
301
class ListMetricDescriptorsRequest:
302
name: str # Required. Project name
303
filter: str # Filter expression
304
page_size: int # Maximum results per page
305
page_token: str # Page token
306
307
class ListMetricDescriptorsResponse:
308
metric_descriptors: List[MetricDescriptor] # Metric descriptors
309
next_page_token: str # Next page token
310
311
class CreateMetricDescriptorRequest:
312
name: str # Required. Project name
313
metric_descriptor: MetricDescriptor # Required. Metric descriptor
314
315
class GetMetricDescriptorRequest:
316
name: str # Required. Metric descriptor name
317
318
class DeleteMetricDescriptorRequest:
319
name: str # Required. Metric descriptor name to delete
320
321
class GetMonitoredResourceDescriptorRequest:
322
name: str # Required. Monitored resource descriptor name
323
324
class ListMonitoredResourceDescriptorsRequest:
325
name: str # Required. Project name
326
filter: str # Filter expression
327
page_size: int # Maximum results per page
328
page_token: str # Page token
329
330
class ListMonitoredResourceDescriptorsResponse:
331
resource_descriptors: List[MonitoredResourceDescriptor] # Resource descriptors
332
next_page_token: str # Next page token
333
```
334
335
## Usage Examples
336
337
### Creating a Custom Metric Descriptor
338
339
```python
340
from google.cloud.monitoring import MetricServiceClient
341
from google.api import metric_pb2
342
from google.api import label_pb2
343
344
client = MetricServiceClient()
345
project_name = f"projects/{project_id}"
346
347
# Create metric descriptor
348
descriptor = metric_pb2.MetricDescriptor()
349
descriptor.type = "custom.googleapis.com/my_metric"
350
descriptor.metric_kind = metric_pb2.MetricDescriptor.MetricKind.GAUGE
351
descriptor.value_type = metric_pb2.MetricDescriptor.ValueType.DOUBLE
352
descriptor.description = "My custom metric"
353
descriptor.display_name = "My Metric"
354
355
# Add labels
356
label = label_pb2.LabelDescriptor()
357
label.key = "environment"
358
label.value_type = label_pb2.LabelDescriptor.ValueType.STRING
359
label.description = "Environment label"
360
descriptor.labels.append(label)
361
362
# Create the descriptor
363
created_descriptor = client.create_metric_descriptor(
364
name=project_name,
365
metric_descriptor=descriptor
366
)
367
print(f"Created metric descriptor: {created_descriptor.type}")
368
```
369
370
### Writing Time Series Data
371
372
```python
373
from google.cloud.monitoring import MetricServiceClient
374
from google.cloud.monitoring_v3.types import TimeSeries, Point, TypedValue
375
from google.cloud.monitoring_v3.types import TimeInterval, Metric, MonitoredResource
376
from google.protobuf.timestamp_pb2 import Timestamp
377
import time
378
379
client = MetricServiceClient()
380
project_name = f"projects/{project_id}"
381
382
# Create time series
383
series = TimeSeries()
384
385
# Set metric
386
series.metric.type = "custom.googleapis.com/my_metric"
387
series.metric.labels["environment"] = "production"
388
389
# Set resource
390
series.resource.type = "gce_instance"
391
series.resource.labels["instance_id"] = "my-instance-123"
392
series.resource.labels["zone"] = "us-central1-a"
393
394
# Create data point
395
now = time.time()
396
seconds = int(now)
397
nanos = int((now - seconds) * 10**9)
398
399
point = Point()
400
point.value.double_value = 42.0
401
point.interval.end_time.seconds = seconds
402
point.interval.end_time.nanos = nanos
403
404
series.points = [point]
405
406
# Write the time series
407
client.create_time_series(
408
name=project_name,
409
time_series=[series]
410
)
411
print("Time series data written successfully")
412
```
413
414
### Querying Time Series Data
415
416
```python
417
from google.cloud.monitoring import MetricServiceClient
418
from google.cloud.monitoring_v3.types import TimeInterval, Aggregation
419
from google.protobuf.timestamp_pb2 import Timestamp
420
import time
421
422
client = MetricServiceClient()
423
project_name = f"projects/{project_id}"
424
425
# Define time interval (last hour)
426
now = time.time()
427
interval = TimeInterval()
428
interval.end_time.seconds = int(now)
429
interval.start_time.seconds = int(now - 3600) # 1 hour ago
430
431
# Query time series
432
filter_str = 'metric.type="compute.googleapis.com/instance/cpu/utilization"'
433
434
for series in client.list_time_series(
435
name=project_name,
436
filter=filter_str,
437
interval=interval
438
):
439
print(f"Metric: {series.metric.type}")
440
print(f"Resource: {series.resource.type}")
441
for point in series.points:
442
print(f"Value: {point.value.double_value} at {point.interval.end_time}")
443
```
444
445
### Aggregating Time Series Data
446
447
```python
448
from google.cloud.monitoring_v3.types import Aggregation, Duration
449
450
# Create aggregation specification
451
aggregation = Aggregation()
452
aggregation.alignment_period.seconds = 300 # 5 minutes
453
aggregation.per_series_aligner = Aggregation.Aligner.ALIGN_MEAN
454
aggregation.cross_series_reducer = Aggregation.Reducer.REDUCE_MEAN
455
aggregation.group_by_fields = ["resource.label.zone"]
456
457
# Query with aggregation
458
for series in client.list_time_series(
459
name=project_name,
460
filter=filter_str,
461
interval=interval,
462
aggregation=aggregation
463
):
464
print(f"Aggregated series: {series.metric.type}")
465
for point in series.points:
466
print(f"Aggregated value: {point.value.double_value}")
467
```
468
469
### Listing Metric Descriptors
470
471
```python
472
client = MetricServiceClient()
473
project_name = f"projects/{project_id}"
474
475
# List all metric descriptors
476
for descriptor in client.list_metric_descriptors(name=project_name):
477
print(f"Metric: {descriptor.type}")
478
print(f"Kind: {descriptor.metric_kind}")
479
print(f"Value Type: {descriptor.value_type}")
480
481
# Filter custom metrics
482
filter_expr = 'metric.type=starts_with("custom.googleapis.com/")'
483
request = {"name": project_name, "filter": filter_expr}
484
485
for descriptor in client.list_metric_descriptors(request=request):
486
print(f"Custom metric: {descriptor.type}")
487
```
488
489
### Async Operations
490
491
```python
492
import asyncio
493
from google.cloud.monitoring import MetricServiceAsyncClient
494
495
async def manage_metrics():
496
client = MetricServiceAsyncClient()
497
project_name = f"projects/{project_id}"
498
499
# List metric descriptors asynchronously
500
async for descriptor in await client.list_metric_descriptors(name=project_name):
501
print(f"Async metric: {descriptor.type}")
502
503
# Create time series asynchronously
504
await client.create_time_series(
505
name=project_name,
506
time_series=[series] # series defined earlier
507
)
508
print("Async time series creation completed")
509
510
asyncio.run(manage_metrics())
511
```
512
513
## Resource Path Helpers
514
515
```python { .api }
516
class MetricServiceClient:
517
@staticmethod
518
def metric_descriptor_path(project: str, metric_descriptor: str) -> str:
519
"""Returns a fully-qualified metric_descriptor string."""
520
521
@staticmethod
522
def monitored_resource_descriptor_path(
523
project: str,
524
monitored_resource_descriptor: str
525
) -> str:
526
"""Returns a fully-qualified monitored_resource_descriptor string."""
527
528
@staticmethod
529
def parse_metric_descriptor_path(path: str) -> Dict[str, str]:
530
"""Parses a metric_descriptor path into its component segments."""
531
```
532
533
## Error Handling
534
535
Metric operations can encounter various error conditions:
536
537
```python
538
from google.api_core import exceptions
539
from google.cloud.monitoring import MetricServiceClient
540
541
client = MetricServiceClient()
542
543
try:
544
# Attempt to create time series
545
client.create_time_series(name=project_name, time_series=invalid_series)
546
except exceptions.InvalidArgument as e:
547
print(f"Invalid time series data: {e}")
548
except exceptions.ResourceExhausted:
549
print("Rate limit exceeded")
550
except exceptions.NotFound:
551
print("Metric descriptor not found")
552
except exceptions.PermissionDenied:
553
print("Insufficient permissions to write metrics")
554
```