0
# Google Cloud Monitoring
1

2
Google Cloud Monitoring is a comprehensive Python client library for Google Cloud Monitoring (formerly Stackdriver Monitoring) that enables developers to interact with Google's cloud monitoring and observability platform. It offers complete API coverage for collecting, analyzing, and alerting on metrics, events, and metadata from various cloud and on-premise sources including Google Cloud Platform, AWS, hybrid systems, and over 150 application components through BindPlane integration.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-monitoring
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-monitoring`
9
- **Python Version**: >= 3.7
10

11
## Core Imports
12

13
```python
14
from google.cloud import monitoring
15
```
16

17
Import specific service clients:
18

19
```python
20
from google.cloud.monitoring import AlertPolicyServiceClient
21
from google.cloud.monitoring import MetricServiceClient
22
from google.cloud.monitoring import NotificationChannelServiceClient
23
```
24

25
Import types and data structures:
26

27
```python
28
from google.cloud.monitoring import AlertPolicy
29
from google.cloud.monitoring import TimeSeries
30
from google.cloud.monitoring import TimeInterval
31
from google.cloud.monitoring import QueryServiceClient
32
```
33

34
## Basic Usage
35

36
```python
37
from google.cloud.monitoring import MetricServiceClient
38
from google.cloud.monitoring import TimeSeries, Point, TimeInterval
39
from google.api_core.datetime_helpers import DatetimeWithNanoseconds
40
import time
41

42
# Initialize the client (uses default credentials)
43
client = MetricServiceClient()
44

45
# Define project and time series data
46
project_name = f"projects/{project_id}"
47
now = time.time()
48
seconds = int(now)
49
nanos = int((now - seconds) * 10**9)
50

51
# Create a time series data point
52
series = TimeSeries()
53
series.metric.type = "custom.googleapis.com/my_metric"
54
series.resource.type = "gce_instance"
55
series.resource.labels["instance_id"] = "my-instance"
56
series.resource.labels["zone"] = "us-central1-a"
57

58
# Add a data point
59
point = Point()
60
point.value.double_value = 3.14
61
point.interval.end_time.seconds = seconds
62
point.interval.end_time.nanos = nanos
63
series.points = [point]
64

65
# Write the time series data
66
client.create_time_series(name=project_name, time_series=[series])
67
```
68

69
## Architecture
70

71
The Google Cloud Monitoring library follows a service-oriented architecture with specialized clients for different monitoring capabilities:
72

73
- **Service Clients**: Eight specialized clients handle different aspects of monitoring (alerts, metrics, notifications, etc.)
74
- **Request/Response Types**: Structured data types for all API interactions
75
- **Resource Management**: Built-in path helpers and resource name formatting
76
- **Async Support**: Full async/await support for all operations
77
- **Authentication**: Integrated Google Cloud authentication with multiple credential sources
78

79
## Capabilities
80

81
### Alert Policy Management
82

83
Manages alert policies that define conditions for generating alerts based on metrics and logs. Supports creating, updating, deleting, and listing alert policies with complex condition logic.
84

85
```python { .api }
86
class AlertPolicyServiceClient:
87
    def list_alert_policies(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> pagers.ListAlertPoliciesPager: ...
88
    def get_alert_policy(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> alert.AlertPolicy: ...
89
    def create_alert_policy(self, request=None, *, name=None, alert_policy=None, retry=None, timeout=None, metadata=()) -> alert.AlertPolicy: ...
90
    def update_alert_policy(self, request=None, *, update_mask=None, alert_policy=None, retry=None, timeout=None, metadata=()) -> alert.AlertPolicy: ...
91
    def delete_alert_policy(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
92

93
class AlertPolicyServiceAsyncClient:
94
    async def list_alert_policies(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> pagers.ListAlertPoliciesAsyncPager: ...
95
    async def get_alert_policy(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> alert.AlertPolicy: ...
96
    async def create_alert_policy(self, request=None, *, name=None, alert_policy=None, retry=None, timeout=None, metadata=()) -> alert.AlertPolicy: ...
97
    async def update_alert_policy(self, request=None, *, update_mask=None, alert_policy=None, retry=None, timeout=None, metadata=()) -> alert.AlertPolicy: ...
98
    async def delete_alert_policy(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
99
```
100

101
[Alert Policy Management](./alert-policies.md)
102

103
### Resource Group Management
104

105
Manages groups for organizing and categorizing monitored resources. Groups enable bulk operations and simplified resource management across your monitoring infrastructure.
106

107
```python { .api }
108
class GroupServiceClient:
109
    def list_groups(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> pagers.ListGroupsPager: ...
110
    def get_group(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> group.Group: ...
111
    def create_group(self, request=None, *, name=None, group=None, retry=None, timeout=None, metadata=()) -> group.Group: ...
112
    def update_group(self, request=None, *, group=None, retry=None, timeout=None, metadata=()) -> group.Group: ...
113
    def delete_group(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
114
    def list_group_members(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> pagers.ListGroupMembersPager: ...
115
```
116

117
[Resource Group Management](./groups.md)
118

119
### Metrics and Time Series
120

121
Core functionality for working with metrics, time series data, and monitored resources. Handles metric creation, data ingestion, querying, and resource descriptor management.
122

123
```python { .api }
124
class MetricServiceClient:
125
    def list_metric_descriptors(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> pagers.ListMetricDescriptorsPager: ...
126
    def get_metric_descriptor(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> metric_pb2.MetricDescriptor: ...
127
    def create_metric_descriptor(self, request=None, *, name=None, metric_descriptor=None, retry=None, timeout=None, metadata=()) -> metric_pb2.MetricDescriptor: ...
128
    def delete_metric_descriptor(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
129
    def list_time_series(self, request=None, *, name=None, filter=None, interval=None, view=None, retry=None, timeout=None, metadata=()) -> pagers.ListTimeSeriesPager: ...
130
    def create_time_series(self, request=None, *, name=None, time_series=None, retry=None, timeout=None, metadata=()) -> None: ...
131
```
132

133
[Metrics and Time Series](./metrics.md)
134

135
### Notification Channel Management
136

137
Manages notification channels for delivering alert notifications via email, SMS, Slack, PagerDuty, and other supported channels with verification and configuration management.
138

139
```python { .api }
140
class NotificationChannelServiceClient:
141
    def list_notification_channels(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> pagers.ListNotificationChannelsPager: ...
142
    def get_notification_channel(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> notification_pb2.NotificationChannel: ...
143
    def create_notification_channel(self, request=None, *, name=None, notification_channel=None, retry=None, timeout=None, metadata=()) -> notification_pb2.NotificationChannel: ...
144
    def update_notification_channel(self, request=None, *, update_mask=None, notification_channel=None, retry=None, timeout=None, metadata=()) -> notification_pb2.NotificationChannel: ...
145
    def delete_notification_channel(self, request=None, *, name=None, force=None, retry=None, timeout=None, metadata=()) -> None: ...
146
    def verify_notification_channel(self, request=None, *, name=None, code=None, retry=None, timeout=None, metadata=()) -> notification_pb2.NotificationChannel: ...
147
```
148

149
[Notification Channel Management](./notifications.md)
150

151
### Time Series Query Service (MQL - Deprecated)
152

153
Provides time series querying capabilities using Monitoring Query Language (MQL). This service is deprecated in favor of PromQL-based querying.
154

155
```python { .api }
156
class QueryServiceClient:
157
    def query_time_series(self, request=None, *, retry=None, timeout=None, metadata=()) -> pagers.QueryTimeSeriesPager: ...
158

159
class QueryServiceAsyncClient:
160
    async def query_time_series(self, request=None, *, retry=None, timeout=None, metadata=()) -> pagers.QueryTimeSeriesAsyncPager: ...
161
```
162

163
**Note**: This service is deprecated. Use PromQL queries with the Monitoring API instead.
164

165
### Service Level Monitoring
166

167
Manages services and Service Level Objectives (SLOs) for service-oriented monitoring, including SLI definitions, error budgets, and service health tracking.
168

169
```python { .api }
170
class ServiceMonitoringServiceClient:
171
    def create_service(self, request=None, *, parent=None, service=None, retry=None, timeout=None, metadata=()) -> service.Service: ...
172
    def get_service(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> service.Service: ...
173
    def list_services(self, request=None, *, parent=None, retry=None, timeout=None, metadata=()) -> pagers.ListServicesPager: ...
174
    def update_service(self, request=None, *, service=None, retry=None, timeout=None, metadata=()) -> service.Service: ...
175
    def delete_service(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
176
    def create_service_level_objective(self, request=None, *, parent=None, service_level_objective=None, retry=None, timeout=None, metadata=()) -> service.ServiceLevelObjective: ...
177
    def get_service_level_objective(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> service.ServiceLevelObjective: ...
178
    def list_service_level_objectives(self, request=None, *, parent=None, retry=None, timeout=None, metadata=()) -> pagers.ListServiceLevelObjectivesPager: ...
179
    def update_service_level_objective(self, request=None, *, service_level_objective=None, retry=None, timeout=None, metadata=()) -> service.ServiceLevelObjective: ...
180
    def delete_service_level_objective(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
181
```
182

183
[Service Level Monitoring](./services.md)
184

185
### Uptime Check Management
186

187
Manages uptime check configurations for monitoring the availability and response time of HTTP/HTTPS endpoints, TCP services, and other network resources.
188

189
```python { .api }
190
class UptimeCheckServiceClient:
191
    def list_uptime_check_configs(self, request=None, *, parent=None, retry=None, timeout=None, metadata=()) -> pagers.ListUptimeCheckConfigsPager: ...
192
    def get_uptime_check_config(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> uptime.UptimeCheckConfig: ...
193
    def create_uptime_check_config(self, request=None, *, parent=None, uptime_check_config=None, retry=None, timeout=None, metadata=()) -> uptime.UptimeCheckConfig: ...
194
    def update_uptime_check_config(self, request=None, *, uptime_check_config=None, retry=None, timeout=None, metadata=()) -> uptime.UptimeCheckConfig: ...
195
    def delete_uptime_check_config(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> None: ...
196
    def list_uptime_check_ips(self, request=None, *, retry=None, timeout=None, metadata=()) -> pagers.ListUptimeCheckIpsPager: ...
197
```
198

199
[Uptime Check Management](./uptime-checks.md)
200

201
### Alert Suppression (Snooze)
202

203
Temporarily suppresses alert notifications using snooze functionality, allowing planned maintenance windows and temporary alert silencing with configurable duration and criteria.
204

205
```python { .api }
206
class SnoozeServiceClient:
207
    def create_snooze(self, request=None, *, parent=None, snooze=None, retry=None, timeout=None, metadata=()) -> snooze.Snooze: ...
208
    def list_snoozes(self, request=None, *, parent=None, retry=None, timeout=None, metadata=()) -> pagers.ListSnoozesPager: ...
209
    def get_snooze(self, request=None, *, name=None, retry=None, timeout=None, metadata=()) -> snooze.Snooze: ...
210
    def update_snooze(self, request=None, *, snooze=None, update_mask=None, retry=None, timeout=None, metadata=()) -> snooze.Snooze: ...
211
```
212

213
[Alert Suppression](./snooze.md)
214

215
## Common Types
216

217
Core data types used across all monitoring services:
218

219
```python { .api }
220
class TimeInterval:
221
    end_time: Timestamp
222
    start_time: Timestamp
223

224
class TypedValue:
225
    bool_value: bool
226
    int64_value: int
227
    double_value: float
228
    string_value: str
229
    distribution_value: Distribution
230

231
class Aggregation:
232
    alignment_period: Duration
233
    per_series_aligner: Aligner
234
    cross_series_reducer: Reducer
235
    group_by_fields: List[str]
236

237
class ComparisonType(enum.Enum):
238
    COMPARISON_GREATER = 1
239
    COMPARISON_GREATER_EQUAL = 2
240
    COMPARISON_LESS = 3
241
    COMPARISON_LESS_EQUAL = 4
242
    COMPARISON_EQUAL = 5
243
    COMPARISON_NOT_EQUAL = 6
244

245
class ServiceTier(enum.Enum):
246
    SERVICE_TIER_BASIC = 1
247
    SERVICE_TIER_PREMIUM = 2
248

249
class DroppedLabels:
250
    label: Dict[str, str]  # Labels that were dropped
251

252
class SpanContext:
253
    span_name: str  # Span name for tracing integration
254

255
class TextLocator:
256
    source: str  # Source text
257
    start_position: int  # Start position
258
    end_position: int  # End position
259

260
class LabelValue:
261
    bool_value: bool  # Boolean label value
262
    int64_value: int  # Integer label value
263
    string_value: str  # String label value
264

265
class QueryError:
266
    locator: TextLocator  # Error location
267
    message: str  # Error message
268

269
class QueryErrorList:
270
    errors: List[QueryError]  # List of query errors
271

272
class TimeSeriesData:
273
    label_values: List[LabelValue]  # Label values
274
    point_data: List[Point.PointData]  # Point data
275

276
class TimeSeriesDescriptor:
277
    label_descriptors: List[LabelDescriptor]  # Label descriptors
278
    point_descriptor: Point.PointDescriptor  # Point descriptor
279

280
class QueryTimeSeriesRequest:
281
    name: str  # Required. Project name
282
    query: str  # Required. MQL query string
283
    page_size: int  # Maximum results per page
284
    page_token: str  # Page token for pagination
285

286
class QueryTimeSeriesResponse:
287
    time_series_descriptor: TimeSeriesDescriptor  # Time series metadata
288
    time_series_data: List[TimeSeriesData]  # Time series data
289
    next_page_token: str  # Next page token
290
    partial_errors: List[Status]  # Partial errors
291
```
292

293
## Authentication
294

295
The library supports multiple authentication methods:
296

297
```python
298
# Default credentials (recommended)
299
from google.cloud.monitoring import MetricServiceClient
300
client = MetricServiceClient()
301

302
# Service account file
303
client = MetricServiceClient.from_service_account_file("path/to/credentials.json")
304

305
# Service account info (dict)
306
client = MetricServiceClient.from_service_account_info(credentials_dict)
307

308
# Explicit credentials
309
from google.oauth2 import service_account
310
credentials = service_account.Credentials.from_service_account_file("path/to/file.json")
311
client = MetricServiceClient(credentials=credentials)
312
```
313

314
## Error Handling
315

316
All service methods can raise Google Cloud exceptions:
317

318
```python
319
from google.api_core import exceptions
320
from google.cloud.monitoring import MetricServiceClient
321

322
client = MetricServiceClient()
323

324
try:
325
    metric = client.get_metric_descriptor(name="projects/my-project/metricDescriptors/invalid")
326
except exceptions.NotFound:
327
    print("Metric descriptor not found")
328
except exceptions.PermissionDenied:
329
    print("Insufficient permissions")
330
except exceptions.GoogleAPIError as e:
331
    print(f"API error: {e}")
332
```